refactor: extract kb_framework package, build graph in memory
Scripts become thin CLIs over kb_framework (graph, query, query_tools, vault, instructions) so the hosted read-only connector shares one implementation with the stdio server. The MCP server builds the graph from Markdown on demand and invalidates it on writes; refresh_graph rebuilds in memory and reports validation problems. Pre-commit hook validates only; index/graph.json is no longer read, written or staged (generate-graph.py --write remains for operators). Golden fixtures pin graph and tool payloads to the previous output. Agent and skill docs updated to match. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Claude Fable 5.1
Vendored
+259
@@ -0,0 +1,259 @@
|
||||
{
|
||||
"graph_summary": {
|
||||
"tool": "graph_summary",
|
||||
"args": {
|
||||
"topLinked": 3,
|
||||
"topTags": 2
|
||||
},
|
||||
"structuredContent": {
|
||||
"version": 1,
|
||||
"node_count": 4,
|
||||
"edge_count": 4,
|
||||
"by_repo": {
|
||||
"global": 3,
|
||||
"alpha": 1
|
||||
},
|
||||
"tag_count": 3,
|
||||
"by_tag": [
|
||||
{
|
||||
"tag": "demo",
|
||||
"count": 2
|
||||
},
|
||||
{
|
||||
"tag": "alpha",
|
||||
"count": 1
|
||||
}
|
||||
],
|
||||
"top_linked": [
|
||||
{
|
||||
"id": "area-ops",
|
||||
"title": "Area Ops",
|
||||
"path": "02_areas/ops.md",
|
||||
"inbound_count": 2
|
||||
},
|
||||
{
|
||||
"id": "project-alpha",
|
||||
"title": "Project Alpha",
|
||||
"path": "01_projects/alpha.md",
|
||||
"inbound_count": 1
|
||||
},
|
||||
{
|
||||
"id": "resource-demo",
|
||||
"title": "Demo Resource",
|
||||
"path": "03_resources/demo/index.md",
|
||||
"inbound_count": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"graph_search_nodes": {
|
||||
"tool": "graph_search_nodes",
|
||||
"args": {
|
||||
"query": "alpha",
|
||||
"limit": 5
|
||||
},
|
||||
"structuredContent": {
|
||||
"total_matches": 1,
|
||||
"returned": 1,
|
||||
"items": [
|
||||
{
|
||||
"id": "project-alpha",
|
||||
"title": "Project Alpha",
|
||||
"path": "01_projects/alpha.md",
|
||||
"repo": "alpha",
|
||||
"type": "project",
|
||||
"status": "active",
|
||||
"tags": [
|
||||
"alpha",
|
||||
"demo"
|
||||
],
|
||||
"last_reviewed": "2026-01-01",
|
||||
"outbound_links": [
|
||||
"area-ops",
|
||||
"resource-demo"
|
||||
],
|
||||
"inbound_count": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"graph_neighbors": {
|
||||
"tool": "graph_neighbors",
|
||||
"args": {
|
||||
"id": "area-ops"
|
||||
},
|
||||
"structuredContent": {
|
||||
"node": {
|
||||
"id": "area-ops",
|
||||
"title": "Area Ops",
|
||||
"path": "02_areas/ops.md",
|
||||
"repo": "global",
|
||||
"type": "area",
|
||||
"status": "active",
|
||||
"tags": [
|
||||
"ops"
|
||||
],
|
||||
"last_reviewed": "",
|
||||
"outbound_links": [
|
||||
"project-alpha"
|
||||
],
|
||||
"inbound_count": 2
|
||||
},
|
||||
"inbound_count": 2,
|
||||
"outbound_count": 1,
|
||||
"inbound": [
|
||||
{
|
||||
"id": "project-alpha",
|
||||
"title": "Project Alpha",
|
||||
"path": "01_projects/alpha.md",
|
||||
"direction": "inbound",
|
||||
"type": "depends-on",
|
||||
"anchor_text": "Area Ops",
|
||||
"annotation": "operations area"
|
||||
},
|
||||
{
|
||||
"id": "resource-demo",
|
||||
"title": "Demo Resource",
|
||||
"path": "03_resources/demo/index.md",
|
||||
"direction": "inbound",
|
||||
"type": "related",
|
||||
"anchor_text": "Area Ops",
|
||||
"annotation": ""
|
||||
}
|
||||
],
|
||||
"outbound": [
|
||||
{
|
||||
"id": "project-alpha",
|
||||
"title": "Project Alpha",
|
||||
"path": "01_projects/alpha.md",
|
||||
"direction": "outbound",
|
||||
"type": "part-of",
|
||||
"anchor_text": "Project Alpha",
|
||||
"annotation": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"read_note_by_id": {
|
||||
"tool": "read_note",
|
||||
"args": {
|
||||
"id": "resource-demo"
|
||||
},
|
||||
"structuredContent": {
|
||||
"path": "03_resources/demo/index.md",
|
||||
"binary": false,
|
||||
"content": "---\nid: resource-demo\ntitle: Demo Resource\ntype: reference\ntags: [demo]\n---\n\n# Demo Resource\n\nRaw original kept in `raw/`. Related: [Area Ops](02_areas/ops.md).\n"
|
||||
}
|
||||
},
|
||||
"read_note_by_path": {
|
||||
"tool": "read_note",
|
||||
"args": {
|
||||
"path": "02_areas/ops.md"
|
||||
},
|
||||
"structuredContent": {
|
||||
"path": "02_areas/ops.md",
|
||||
"binary": false,
|
||||
"content": "---\nid: area-ops\ntitle: Area Ops\ntype: area\ntags: [ops]\n---\n\n# Area Ops\n\nParent hub: [Project Alpha](project-alpha){\"type\":\"part-of\"}.\n"
|
||||
}
|
||||
},
|
||||
"tool_definitions": [
|
||||
{
|
||||
"name": "read_instructions",
|
||||
"description": "Read framework AGENTS.md and AGENT_QUERY_GUIDE.md before working with the vault. These operating documents live outside an external vault and do not require a generated graph.",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {},
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "graph_summary",
|
||||
"description": "Orientation for a cold start: node and edge counts, the repo scopes, the most-linked notes, and the tag vocabulary as `by_tag` (most frequent first) plus `tag_count`, the number of distinct tags. Read `by_tag` before filtering `graph_search_nodes` by `tag` \u2014 that filter matches a tag verbatim, so a guessed spelling returns nothing.",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"topLinked": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 50,
|
||||
"description": "Most-linked notes to return (default 10)."
|
||||
},
|
||||
"topTags": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 500,
|
||||
"description": "Tags to return, most frequent first (default 50)."
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "graph_search_nodes",
|
||||
"description": "Search graph nodes by metadata and free text.",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"repo": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": {
|
||||
"type": "string"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
},
|
||||
"tag": {
|
||||
"type": "string"
|
||||
},
|
||||
"query": {
|
||||
"type": "string"
|
||||
},
|
||||
"limit": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 200
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "graph_neighbors",
|
||||
"description": "Show inbound and outbound links for a node ID. Each neighbor includes the edge `type` (relationship, e.g. supersedes, depends-on), `anchor_text` (the link's display text), and `annotation` (what to expect in that note).",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id"
|
||||
],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string"
|
||||
},
|
||||
"limit": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 200
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "read_note",
|
||||
"description": "Read note content by graph node ID or vault-relative path. Provide exactly one of `id` or `path`. If both or neither are provided, the call returns an error.",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Graph node ID (e.g. 'AGENTS')."
|
||||
},
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Vault-relative file path (e.g. 'README.md')."
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user