From 8b0edd53730a7eb8b19fbb566e32ceedfe3477eb Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 15 Aug 2026 20:18:13 +0000 Subject: [PATCH] Add MCP server: the vault's knowledge, queryable by AI tools MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit graphier-mcp (also python -m graphier.mcp) speaks Model Context Protocol over stdio — newline-delimited JSON-RPC 2.0, zero new dependencies — so Claude Code, Claude Desktop, Cursor, and any MCP client can query the knowledge graph instead of doing RAG over raw text. Nine tools: search_vault (hybrid search), get_entity (the full dossier: quoted mentions, relations with sentence evidence, conflicts, inferred connections — with did-you-mean on a miss), list_entities, get_relations, query_datalog (against extracted facts AND the user's own rules), get_conflicts, get_timeline (year-bounded), list_notes, read_note. Every answer carries the same sentence-level provenance as the app. Tool errors surface as isError tool results rather than protocol failures; unknown tools/methods return proper JSON-RPC errors. The graph is rebuilt per call on the content-hash extraction cache, so unchanged notes cost nothing. 4 new tests (51 total) over the seeded demo corpus, plus an end-to-end stdio smoke test (initialize → datalog query returns the user-rule derivations). README gains the client config snippet; ROADMAP checks off its headliner; CHANGELOG updated. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01QVbxD1gd3gsC6zXKE6L3ya --- CHANGELOG.md | 7 + README.md | 25 ++++ ROADMAP.md | 6 +- backend/graphier/mcp.py | 302 ++++++++++++++++++++++++++++++++++++++ backend/pyproject.toml | 1 + backend/tests/test_mcp.py | 84 +++++++++++ 6 files changed, 421 insertions(+), 4 deletions(-) create mode 100644 backend/graphier/mcp.py create mode 100644 backend/tests/test_mcp.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 073213a..8e3d7d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,13 @@ ## Unreleased +- **MCP server** (`graphier-mcp`): the vault's knowledge graph queryable + by Claude Code, Claude Desktop, Cursor, and any MCP client over stdio — + nine tools (search, entity dossiers, relations, Datalog, conflicts, + timeline, notes), every answer carrying sentence-level provenance. +- Community infrastructure: CONTRIBUTING, extension guide, roadmap, + issue/PR templates, packaging + release workflow. + ## 0.1.0 — first public cut Everything so far, in merge order: diff --git a/README.md b/README.md index 9c9cb86..d4dd05f 100644 --- a/README.md +++ b/README.md @@ -216,6 +216,31 @@ be rebuilt from the files at any time. Extraction is deterministic (no LLM, no network) — the pattern extractors run on an offset-preserving masked copy of each note so spans map exactly onto what you typed. +## Ask your AI about your notes' knowledge + +Graphier ships an [MCP](https://modelcontextprotocol.io/) server, so +Claude Code, Claude Desktop, Cursor — any MCP client — can query the +knowledge graph instead of doing RAG over raw text: + +```json +{ + "mcpServers": { + "graphier": { + "command": "graphier-mcp", + "env": { "GRAPHIER_VAULT": "/path/to/your/vault" } + } + } +} +``` + +Nine tools: `search_vault`, `get_entity` (the full dossier with quoted +mentions), `get_relations`, `query_datalog` (against your own rules), +`get_conflicts`, `get_timeline`, `list_entities`, `list_notes`, +`read_note`. Every answer carries provenance — ask "who founded Acme +Corp?" and the AI can cite both conflicting sources, sentence and all. +From a checkout, use `python -m graphier.mcp` with `--app-dir backend` +semantics (`PYTHONPATH=backend`). + ## Contributing Small codebase, 47 tests, deliberately hackable — see diff --git a/ROADMAP.md b/ROADMAP.md index 8b04aeb..22181e9 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -20,12 +20,10 @@ for the bigger ones so we can agree on shape. - [x] Document sources: PDF, HTML, DOCX, TXT - [x] Chronology: cross-source timeline + entity lifeline chart - [x] Launch kit: LICENSE, demo mode, Docker, CI +- [x] MCP server — the vault graph queryable by Claude/Cursor/any MCP + client, provenance included ## Next - -- [ ] **MCP server** — expose the vault graph to Claude/Cursor/any MCP - client: search, entity pages, relations, Datalog queries, provenance. - The AI queries your notes' *knowledge*, not raw text. - [ ] **Conflict resolution workflow** — accept / mark-superseded buttons on conflicts, writing the verdict back as a fact with provenance. - [ ] **Vault diff** — "what changed between snapshot A and B": entities diff --git a/backend/graphier/mcp.py b/backend/graphier/mcp.py new file mode 100644 index 0000000..6003f9e --- /dev/null +++ b/backend/graphier/mcp.py @@ -0,0 +1,302 @@ +"""Graphier MCP server: the vault's knowledge, queryable by AI tools. + +A Model Context Protocol server over stdio (newline-delimited JSON-RPC +2.0) exposing the knowledge graph — not raw text — to Claude Code, +Claude Desktop, Cursor, and any other MCP client. Every answer carries +the same sentence-level provenance as the app: the AI can always say +which sentence, in which source, justified a claim. + +Run: GRAPHIER_VAULT=/path/to/vault graphier-mcp + (or python -m graphier.mcp) +""" + +from __future__ import annotations + +import json +import os +import sys +from typing import Any + +from .enrichment import Enricher, enrich +from .extraction import ExtractionService +from .graph import build_graph, entity_page +from .search import search as search_vault +from .timeline import build_timeline +from .vault import NoteNotFound, Vault, VaultError + +PROTOCOL_VERSION = "2024-11-05" +SERVER_INFO = {"name": "graphier", "version": "0.1.0"} + + +class GraphierTools: + """Tool implementations over one vault. The graph is rebuilt per call — + extraction is content-hash cached, so unchanged notes cost nothing.""" + + def __init__(self, vault_dir: str): + self.vault = Vault(vault_dir) + self.extractor = ExtractionService() + + def _graph(self) -> dict[str, Any]: + return build_graph(self.vault, self.extractor) + + # ---- tools ---- + + def search(self, query: str) -> dict[str, Any]: + notes = {m.id: self.vault.read(m.id) for m in self.vault.list_notes()} + graph = self._graph() + return search_vault(query, notes, graph["note_titles"], graph) + + def get_entity(self, name: str) -> dict[str, Any]: + graph = self._graph() + wanted = name.strip().lower() + node = next( + (n for n in graph["nodes"] if n["text"].strip().lower() == wanted or n["id"] == name), + None, + ) + if node is None: + candidates = [n["text"] for n in graph["nodes"] if wanted in n["text"].lower()][:5] + return {"error": f"entity not found: {name}", "did_you_mean": candidates} + page = entity_page(graph, node["id"]) or {} + enrichment = enrich(graph) + page["conflicts"] = [ + c for c in enrichment["conflicts"] + if c["subject"] == node["text"] + or any(cl["object"] == node["text"] for cl in c["claims"]) + ] + page["inferred"] = [ + i for i in enrichment["inferred"] if node["text"] in (i["source"], i["target"]) + ] + return page + + def list_entities(self, label: str | None = None) -> list[dict[str, Any]]: + graph = self._graph() + return [ + {"text": n["text"], "label": n["label"], "mentions": n["count"], "notes": n["notes"]} + for n in graph["nodes"] + if n["label"] != "NOTE" and (label is None or n["label"] == label.upper()) + ] + + def get_relations(self, predicate: str | None = None) -> list[dict[str, Any]]: + graph = self._graph() + display = {n["id"]: n["text"] for n in graph["nodes"]} + wanted = predicate.lower().replace(" ", "_") if predicate else None + return [ + { + "subject": display.get(e["source"], e["source"]), + "predicate": e["predicate"], + "object": display.get(e["target"], e["target"]), + "origin": e["origin"], + "confidence": e["confidence"], + "evidence": e["evidence"], + } + for e in graph["edges"] + if wanted is None or e["predicate"] == wanted + ] + + def query_datalog(self, pattern: str) -> dict[str, Any]: + pattern = pattern.strip() + if pattern.startswith("?-"): + pattern = pattern[2:].strip() + rows = Enricher(self._graph()).datalog_query(pattern) + return {"pattern": pattern, "rows": rows} + + def get_conflicts(self) -> list[dict[str, Any]]: + return enrich(self._graph())["conflicts"] + + def get_timeline(self, year_from: int | None = None, year_to: int | None = None) -> list[dict[str, Any]]: + events = build_timeline(self.vault, self.extractor) + return [ + e for e in events + if (year_from is None or e["year"] >= year_from) + and (year_to is None or e["year"] <= year_to) + ] + + def list_notes(self) -> list[dict[str, Any]]: + return [ + {"id": m.id, "title": m.title, "kind": m.kind} for m in self.vault.list_notes() + ] + + def read_note(self, note_id: str) -> dict[str, Any]: + try: + return {"id": note_id, "content": self.vault.read(note_id)} + except (NoteNotFound, VaultError) as exc: + return {"error": str(exc)} + + +TOOL_DEFS = [ + { + "name": "search_vault", + "description": "Hybrid search over the vault: TF-IDF ranking boosted by the " + "knowledge graph. Returns ranked note hits with snippets, plus entities " + "matching the query.", + "inputSchema": { + "type": "object", + "properties": {"query": {"type": "string"}}, + "required": ["query"], + }, + }, + { + "name": "get_entity", + "description": "Everything the vault knows about one entity: every mention " + "quoted verbatim with its source, every relation backed by the exact " + "sentence that asserted it, plus conflicts and inferred connections it " + "participates in.", + "inputSchema": { + "type": "object", + "properties": {"name": {"type": "string", "description": "Entity name, e.g. 'Ada Lovelace'"}}, + "required": ["name"], + }, + }, + { + "name": "list_entities", + "description": "List entities in the knowledge graph, optionally filtered by " + "type (PERSON, ORG, GPE, DATE, CONCEPT, or any user-defined domain type).", + "inputSchema": { + "type": "object", + "properties": {"label": {"type": "string"}}, + }, + }, + { + "name": "get_relations", + "description": "Typed relations from the graph (founded_by, acquired_by, " + "user-defined predicates…), each with origin, confidence, and the sentence " + "evidence that produced it. Filter by predicate or get all.", + "inputSchema": { + "type": "object", + "properties": {"predicate": {"type": "string"}}, + }, + }, + { + "name": "query_datalog", + "description": "Run a Datalog query against the vault's extracted facts AND " + "the user's own inference rules. Facts: rel(Subject, Object, predicate), " + "comention(A, B, note). Example: 'empire_builder(P, B)'. Variables start " + "uppercase.", + "inputSchema": { + "type": "object", + "properties": {"pattern": {"type": "string"}}, + "required": ["pattern"], + }, + }, + { + "name": "get_conflicts", + "description": "Contradictions the vault has detected: the same subject and " + "predicate asserted with different objects in different sources, each claim " + "with its source notes.", + "inputSchema": {"type": "object", "properties": {}}, + }, + { + "name": "get_timeline", + "description": "Chronology of every dated fact across all sources (notes, " + "PDFs, DOCX, HTML), each event with its exact sentence and source. " + "Optionally bounded by year.", + "inputSchema": { + "type": "object", + "properties": { + "year_from": {"type": "integer"}, + "year_to": {"type": "integer"}, + }, + }, + }, + { + "name": "list_notes", + "description": "List every source in the vault (markdown notes and " + "documents) with id, title, and kind.", + "inputSchema": {"type": "object", "properties": {}}, + }, + { + "name": "read_note", + "description": "Read one source's full text (markdown content, or the " + "extracted text of a PDF/DOCX/HTML document).", + "inputSchema": { + "type": "object", + "properties": {"note_id": {"type": "string"}}, + "required": ["note_id"], + }, + }, +] + + +def handle_request(tools: GraphierTools, request: dict[str, Any]) -> dict[str, Any] | None: + """Dispatch one JSON-RPC request. Returns None for notifications.""" + method = request.get("method", "") + request_id = request.get("id") + + def result(payload: Any) -> dict[str, Any]: + return {"jsonrpc": "2.0", "id": request_id, "result": payload} + + def error(code: int, message: str) -> dict[str, Any]: + return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}} + + if method == "initialize": + return result( + { + "protocolVersion": PROTOCOL_VERSION, + "capabilities": {"tools": {}}, + "serverInfo": SERVER_INFO, + } + ) + if method.startswith("notifications/"): + return None + if method == "ping": + return result({}) + if method == "tools/list": + return result({"tools": TOOL_DEFS}) + if method == "tools/call": + params = request.get("params", {}) + name = params.get("name", "") + args = params.get("arguments") or {} + handlers = { + "search_vault": lambda: tools.search(args["query"]), + "get_entity": lambda: tools.get_entity(args["name"]), + "list_entities": lambda: tools.list_entities(args.get("label")), + "get_relations": lambda: tools.get_relations(args.get("predicate")), + "query_datalog": lambda: tools.query_datalog(args["pattern"]), + "get_conflicts": lambda: tools.get_conflicts(), + "get_timeline": lambda: tools.get_timeline(args.get("year_from"), args.get("year_to")), + "list_notes": lambda: tools.list_notes(), + "read_note": lambda: tools.read_note(args["note_id"]), + } + handler = handlers.get(name) + if handler is None: + return error(-32602, f"unknown tool: {name}") + try: + payload = handler() + except KeyError as exc: + return error(-32602, f"missing required argument: {exc}") + except Exception as exc: # tool errors surface as tool results, not crashes + return result( + {"content": [{"type": "text", "text": f"error: {exc}"}], "isError": True} + ) + return result( + {"content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False, indent=1)}]} + ) + if request_id is None: + return None + return error(-32601, f"method not found: {method}") + + +def main() -> None: + os.environ.setdefault("SEMANTICA_DISABLE_PROGRESS", "1") + tools = GraphierTools(os.environ.get("GRAPHIER_VAULT", "vault")) + for line in sys.stdin: + line = line.strip() + if not line: + continue + try: + request = json.loads(line) + except json.JSONDecodeError: + print( + json.dumps( + {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "parse error"}} + ), + flush=True, + ) + continue + response = handle_request(tools, request) + if response is not None: + print(json.dumps(response, ensure_ascii=False), flush=True) + + +if __name__ == "__main__": + main() diff --git a/backend/pyproject.toml b/backend/pyproject.toml index aceb547..96f4c57 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -31,6 +31,7 @@ dev = ["pytest>=8.0", "httpx>=0.27"] [project.scripts] graphier = "graphier.main:main" +graphier-mcp = "graphier.mcp:main" [build-system] requires = ["setuptools>=68"] diff --git a/backend/tests/test_mcp.py b/backend/tests/test_mcp.py new file mode 100644 index 0000000..0f81c53 --- /dev/null +++ b/backend/tests/test_mcp.py @@ -0,0 +1,84 @@ +import json + +import pytest + +from graphier.demo import seed_demo +from graphier.mcp import GraphierTools, handle_request +from graphier.vault import Vault + + +@pytest.fixture() +def tools(tmp_path): + seed_demo(Vault(str(tmp_path))) + return GraphierTools(str(tmp_path)) + + +def call(tools, name, args=None, request_id=1): + response = handle_request( + tools, + {"jsonrpc": "2.0", "id": request_id, "method": "tools/call", + "params": {"name": name, "arguments": args or {}}}, + ) + assert "error" not in response, response + result = response["result"] + assert not result.get("isError"), result + return json.loads(result["content"][0]["text"]) + + +def test_initialize_and_tool_list(tools): + init = handle_request(tools, {"jsonrpc": "2.0", "id": 0, "method": "initialize"}) + assert init["result"]["serverInfo"]["name"] == "graphier" + + assert handle_request(tools, {"jsonrpc": "2.0", "method": "notifications/initialized"}) is None + + listing = handle_request(tools, {"jsonrpc": "2.0", "id": 1, "method": "tools/list"}) + names = {t["name"] for t in listing["result"]["tools"]} + assert names == { + "search_vault", "get_entity", "list_entities", "get_relations", + "query_datalog", "get_conflicts", "get_timeline", "list_notes", "read_note", + } + + +def test_search_and_entity_with_provenance(tools): + hits = call(tools, "search_vault", {"query": "ada lovelace"}) + assert hits["results"] and any(e["text"] == "Ada Lovelace" for e in hits["entities"]) + + page = call(tools, "get_entity", {"name": "Acme Corp"}) + assert page["node"]["label"] == "ORG" + assert any("founded Acme Corp" in m["sentence"] for m in page["mentions"]) + assert page["conflicts"], "demo vault has a deliberate Acme Corp conflict" + + miss = call(tools, "get_entity", {"name": "Acme"}) + assert "did_you_mean" in miss and "Acme Corp" in miss["did_you_mean"] + + +def test_relations_datalog_conflicts_timeline(tools): + rels = call(tools, "get_relations", {"predicate": "founded by"}) + assert rels and all(r["predicate"] == "founded_by" for r in rels) + assert rels[0]["evidence"][0]["sentence"] + + rows = call(tools, "query_datalog", {"pattern": "?- empire_builder(P, B)"}) + assert {"P": "Ada Lovelace", "B": "Widget Inc"} in rows["rows"] + + conflicts = call(tools, "get_conflicts") + assert any(c["subject"] == "Acme Corp" for c in conflicts) + + events = call(tools, "get_timeline", {"year_from": 2024}) + assert events and all(e["year"] >= 2024 for e in events) + + +def test_notes_roundtrip_and_errors(tools): + notes = call(tools, "list_notes") + assert any(n["id"] == "research-log" for n in notes) + note = call(tools, "read_note", {"note_id": "research-log"}) + assert "Ada Lovelace" in note["content"] + + unknown = handle_request( + tools, + {"jsonrpc": "2.0", "id": 9, "method": "tools/call", + "params": {"name": "no_such_tool", "arguments": {}}}, + ) + assert unknown["error"]["code"] == -32602 + + bad_method = handle_request(tools, {"jsonrpc": "2.0", "id": 10, "method": "bogus"}) + assert bad_method["error"]["code"] == -32601