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
+105
@@ -0,0 +1,105 @@
|
||||
{
|
||||
"version": 1,
|
||||
"nodes": [
|
||||
{
|
||||
"id": "README",
|
||||
"title": "README",
|
||||
"path": "README.md",
|
||||
"repo": "global",
|
||||
"type": "note",
|
||||
"status": "active",
|
||||
"tags": [],
|
||||
"last_reviewed": "",
|
||||
"outbound_links": [],
|
||||
"inbound_count": 0
|
||||
},
|
||||
{
|
||||
"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
|
||||
},
|
||||
{
|
||||
"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
|
||||
},
|
||||
{
|
||||
"id": "resource-demo",
|
||||
"title": "Demo Resource",
|
||||
"path": "03_resources/demo/index.md",
|
||||
"repo": "global",
|
||||
"type": "reference",
|
||||
"status": "active",
|
||||
"tags": [
|
||||
"demo"
|
||||
],
|
||||
"last_reviewed": "",
|
||||
"outbound_links": [
|
||||
"area-ops"
|
||||
],
|
||||
"inbound_count": 1
|
||||
}
|
||||
],
|
||||
"edges": [
|
||||
{
|
||||
"from": "area-ops",
|
||||
"to": "project-alpha",
|
||||
"kind": "markdown_link",
|
||||
"type": "part-of",
|
||||
"anchor_text": "Project Alpha",
|
||||
"annotation": "",
|
||||
"weight": 1.0
|
||||
},
|
||||
{
|
||||
"from": "project-alpha",
|
||||
"to": "area-ops",
|
||||
"kind": "markdown_link",
|
||||
"type": "depends-on",
|
||||
"anchor_text": "Area Ops",
|
||||
"annotation": "operations area",
|
||||
"weight": 1.0
|
||||
},
|
||||
{
|
||||
"from": "project-alpha",
|
||||
"to": "resource-demo",
|
||||
"kind": "markdown_link",
|
||||
"type": "related",
|
||||
"anchor_text": "the demo resource",
|
||||
"annotation": "resource landing page.",
|
||||
"weight": 1.0
|
||||
},
|
||||
{
|
||||
"from": "resource-demo",
|
||||
"to": "area-ops",
|
||||
"kind": "markdown_link",
|
||||
"type": "related",
|
||||
"anchor_text": "Area Ops",
|
||||
"annotation": "",
|
||||
"weight": 1.0
|
||||
}
|
||||
]
|
||||
}
|
||||
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
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: project-alpha
|
||||
title: Project Alpha
|
||||
type: project
|
||||
status: active
|
||||
tags: [alpha, demo]
|
||||
repo: alpha
|
||||
last_reviewed: 2026-01-01
|
||||
---
|
||||
|
||||
# Project Alpha
|
||||
|
||||
Depends on [Area Ops](area-ops){"type":"depends-on","link-info":"operations area"}.
|
||||
See [the demo resource](resource-demo) — resource landing page.
|
||||
External: [MCP spec](https://modelcontextprotocol.io/).
|
||||
Vendored
+10
@@ -0,0 +1,10 @@
|
||||
---
|
||||
id: area-ops
|
||||
title: Area Ops
|
||||
type: area
|
||||
tags: [ops]
|
||||
---
|
||||
|
||||
# Area Ops
|
||||
|
||||
Parent hub: [Project Alpha](project-alpha){"type":"part-of"}.
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
---
|
||||
id: resource-demo
|
||||
title: Demo Resource
|
||||
type: reference
|
||||
tags: [demo]
|
||||
---
|
||||
|
||||
# Demo Resource
|
||||
|
||||
Raw original kept in `raw/`. Related: [Area Ops](02_areas/ops.md).
|
||||
@@ -0,0 +1,2 @@
|
||||
not a note
|
||||
[broken](../missing.md)
|
||||
Binary file not shown.
Vendored
+1
@@ -0,0 +1 @@
|
||||
# README
|
||||
Reference in New Issue
Block a user