devin-graph 0.1.0__tar.gz → 0.1.2__tar.gz

{devin_graph-0.1.0/src/devin_graph.egg-info → devin_graph-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devin-graph
-Version: 0.1.0
+Version: 0.1.2
 Summary: Knowledge graph over Devin sessions — projects, files, tools and decisions as queryable nodes.
 Author: Icaro0310
 License: MIT
@@ -10,32 +10,34 @@ License-File: LICENSE
 Requires-Dist: devin-internals-spec<0.4.0,>=0.3.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: mcp>=1.2; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
 Dynamic: license-file
 
 <div align="center">
 
 <img src="assets/banner.svg" alt="devin-graph" width="100%"/>
 
-<a href="https://github.com/Icaro0310/devin-graph/actions/workflows/ci.yml"><img src="https://github.com/Icaro0310/devin-graph/actions/workflows/ci.yml/badge.svg" alt="ci"/></a>
+<a href="https://github.com/Icaro0310/devin-explore/actions/workflows/test-graph.yml"><img src="https://github.com/Icaro0310/devin-explore/actions/workflows/test-graph.yml/badge.svg" alt="ci"/></a>
 
-
-<a href="https://scorecard.dev/viewer/?uri=github.com/Icaro0310/devin-graph"><img src="https://api.scorecard.dev/projects/github.com/Icaro0310/devin-graph/badge" alt="OpenSSF Scorecard"/></a>
+<a href="https://scorecard.dev/viewer/?uri=github.com/Icaro0310/devin-explore"><img src="https://api.scorecard.dev/projects/github.com/Icaro0310/devin-explore/badge" alt="OpenSSF Scorecard"/></a>
 <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"/></a>
 <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+"/></a>
-<a href="https://github.com/Icaro0310/devin-graph"><img src="https://img.shields.io/github/stars/Icaro0310/devin-graph" alt="GitHub stars"/></a>
-<a href="https://github.com/Icaro0310/devin-graph/commits/main"><img src="https://img.shields.io/github/last-commit/Icaro0310/devin-graph" alt="Last commit"/></a>
+<a href="https://github.com/Icaro0310/devin-explore"><img src="https://img.shields.io/github/stars/Icaro0310/devin-explore" alt="GitHub stars"/></a>
+<a href="https://github.com/Icaro0310/devin-explore/commits/main"><img src="https://img.shields.io/github/last-commit/Icaro0310/devin-explore" alt="Last commit"/></a>
 <a href="https://github.com/Icaro0310/awesome-devin"><img src="https://img.shields.io/badge/part%20of-devin--*-ecosystem-7c3aed" alt="devin-* ecosystem"/></a>
-<a href="https://github.com/Icaro0310/devin-graph/issues"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome"/></a>
+<a href="https://github.com/Icaro0310/devin-explore/issues"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome"/></a>
 </div>
 
 <!-- DEVIN-ECO:BEGIN -->
 > **Part of the [DEVIN ecosystem](https://github.com/Icaro0310/awesome-devin)**  
 > Track: Understand · Nature: product  
-> For: Developers, AI engineers  
-> Interface: CLI / Python library
+> For: Developers, AI engineers, Data Scientists  
+> Interface: CLI / Python library  
+> Path: Data Scientists · step 1/4 — before `devin-search`
 <!-- DEVIN-ECO:END -->
 
-
 # devin-graph
 
 > **Unofficial community project.** Not affiliated with, endorsed by, or
@@ -79,17 +81,6 @@ build. Schema drift is gated by `devin-internals-spec`'s version detector.
 
 Requires Python ≥ 3.10 and `pipx` or `uv`. Per-OS setup lives in the platform guides: [Linux](README.linux.md) · [Personal Windows](README.windows.md) · [Corporate Windows](README.corporate-windows.md).
 
-<!-- DIST-STATUS:BEGIN — generated from devin-powerups/registry.json -->
-> **Source-only distribution.** This tool is not yet published to PyPI.
-> Install from source:
->
-> ```bash
-> pipx install git+https://github.com/Icaro0310/devin-graph.git
-> # or
-> uv tool install git+https://github.com/Icaro0310/devin-graph.git
-> ```
-<!-- DIST-STATUS:END -->
-
 ## Usage
 
 ```bash
@@ -106,6 +97,10 @@ devin-graph query projects-graph           --graph graph.db --json
 
 # D3-friendly dump: {"meta", "nodes", "edges"}
 devin-graph export --format json --graph graph.db --out graph.json
+
+# diagnostics: edge-less nodes (report-only) and per-session blame
+devin-graph orphans                      --graph graph.db
+devin-graph blame-session <id-or-prefix> --graph graph.db
 ```
 
 Matching is forgiving (`src/app.py` finds `/repo/alpha/src/app.py`);
@@ -114,6 +109,15 @@ by two or more distinct projects, with the project and session lists —
 exportable as JSON like the other queries. The source DB is opened
 `mode=ro` and never written — tests assert its hash is unchanged.
 
+`orphans` lists nodes with no incident edges (id, kind, owner, a
+`prunable` flag marking the subset the next `build` would drop —
+shared, ownerless nodes; owned orphans persist with their owner). It is
+report-only and never deletes. `blame-session <id>` shows what a
+session produced and touched: its owned nodes and edges plus the
+resolved files, tools, projects and commits reachable through them,
+with the extraction-ledger timestamp. `<id>` accepts a unique prefix;
+a missing or ambiguous match exits 2 and lists candidates.
+
 ## Works with Devin alone (Devin-only mode)
 
 devin-graph builds `graph.db` locally from Devin's session stores — the whole
@@ -129,13 +133,10 @@ Windows and `$XDG_DATA_HOME/devin/cli/sessions.db` on Linux (default
 `~/.local/share/devin/cli/sessions.db`). A legacy `~/.config/devin` location
 is also checked. Pass `--sessions-db` to override.
 
-
 `commit` nodes + `produced`/`referenced` edges attribute sessions to git SHAs seen in tool calls (exact when the SHA appears in a `git commit`/`git push` call, `seen` otherwise). `devin-graph sql "SELECT ..."` runs read-only SQL over graph.db (SELECT/WITH only, `query_only` pragma).
 
-
 `--vscdb` (auto-detected on build) adds GUI coverage: `gui_session` nodes keyed by the generated session slug, `gui_workspace` edges to their workspace project, enriched with `lastAccessed` when a `resourceToSpace` editor URI links a space to the slug. Best-effort: only the observed `windsurfSpace.*` keys are read; unknown/malformed keys are skipped. Pass `--vscdb none` to disable.
 
-
 `devin-graph view --out file.html` renders the graph as a self-contained HTML page (embedded JSON + vanilla-JS force layout — zero CDN, works fully offline). `--limit` caps nodes (highest-degree kept, flagged TRUNCATED in the header).
 
 ## Limitations
@@ -165,6 +166,47 @@ DDL, synthetic rows) — no binary fixtures are committed. See
 [docs/SPEC.md](docs/SPEC.md) for the graph model and
 [STATUS.md](STATUS.md) for the roadmap.
 
+## Adapters (MCP server, Devin skill, plugin)
+
+`devin_graph.mcp_server` exposes one read-only tool via the
+`devin-graph-mcp` entry point (`pip install 'devin-graph[mcp]'`):
+`graph_query` (same JSON as `devin-graph query <what> --json`).
+
+`adapters/` is a self-contained Devin plugin root
+(`adapters/.devin-plugin/plugin.json` +
+`adapters/skills/devin-graph/SKILL.md`), installed with
+`devin plugins install
+Icaro0310/devin-explore#packages/graph/adapters` — it ships in the
+repo, not inside the wheel. The manifest launches the server through
+`uvx --from 'devin-graph[mcp]' devin-graph-mcp`, which resolves the
+published PyPI release — no local install needed. To run the server
+from a source checkout instead, install it editable
+(`pip install -e '.[mcp]'`) and call `devin-graph-mcp` directly, or
+point a local manifest copy at the checkout
+(`uvx --from './packages/graph[mcp]' devin-graph-mcp`).
+
+### MCP host configs
+
+Same stdio server in other hosts — server name `devin-graph`:
+
+**Zed** — `context_servers` in `~/.config/zed/settings.json`:
+
+```jsonc
+{ "context_servers": { "devin-graph": { "command": { "path": "devin-graph-mcp", "args": [] } } } }
+```
+
+**JetBrains AI Assistant** — Settings → Tools → AI Assistant → Model Context Protocol → Add:
+
+```json
+{ "mcpServers": { "devin-graph": { "command": "devin-graph-mcp" } } }
+```
+
+**Antigravity** — `~/.gemini/config/mcp_config.json`:
+
+```json
+{ "mcpServers": { "devin-graph": { "command": "devin-graph-mcp" } } }
+```
+
 ## When to use this
 
 - You need cross-session questions: which sessions touched file X, which

{devin_graph-0.1.0 → devin_graph-0.1.2}/README.md

@@ -2,26 +2,25 @@
 
 <img src="assets/banner.svg" alt="devin-graph" width="100%"/>
 
-<a href="https://github.com/Icaro0310/devin-graph/actions/workflows/ci.yml"><img src="https://github.com/Icaro0310/devin-graph/actions/workflows/ci.yml/badge.svg" alt="ci"/></a>
+<a href="https://github.com/Icaro0310/devin-explore/actions/workflows/test-graph.yml"><img src="https://github.com/Icaro0310/devin-explore/actions/workflows/test-graph.yml/badge.svg" alt="ci"/></a>
 
-
-<a href="https://scorecard.dev/viewer/?uri=github.com/Icaro0310/devin-graph"><img src="https://api.scorecard.dev/projects/github.com/Icaro0310/devin-graph/badge" alt="OpenSSF Scorecard"/></a>
+<a href="https://scorecard.dev/viewer/?uri=github.com/Icaro0310/devin-explore"><img src="https://api.scorecard.dev/projects/github.com/Icaro0310/devin-explore/badge" alt="OpenSSF Scorecard"/></a>
 <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"/></a>
 <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+"/></a>
-<a href="https://github.com/Icaro0310/devin-graph"><img src="https://img.shields.io/github/stars/Icaro0310/devin-graph" alt="GitHub stars"/></a>
-<a href="https://github.com/Icaro0310/devin-graph/commits/main"><img src="https://img.shields.io/github/last-commit/Icaro0310/devin-graph" alt="Last commit"/></a>
+<a href="https://github.com/Icaro0310/devin-explore"><img src="https://img.shields.io/github/stars/Icaro0310/devin-explore" alt="GitHub stars"/></a>
+<a href="https://github.com/Icaro0310/devin-explore/commits/main"><img src="https://img.shields.io/github/last-commit/Icaro0310/devin-explore" alt="Last commit"/></a>
 <a href="https://github.com/Icaro0310/awesome-devin"><img src="https://img.shields.io/badge/part%20of-devin--*-ecosystem-7c3aed" alt="devin-* ecosystem"/></a>
-<a href="https://github.com/Icaro0310/devin-graph/issues"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome"/></a>
+<a href="https://github.com/Icaro0310/devin-explore/issues"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome"/></a>
 </div>
 
 <!-- DEVIN-ECO:BEGIN -->
 > **Part of the [DEVIN ecosystem](https://github.com/Icaro0310/awesome-devin)**  
 > Track: Understand · Nature: product  
-> For: Developers, AI engineers  
-> Interface: CLI / Python library
+> For: Developers, AI engineers, Data Scientists  
+> Interface: CLI / Python library  
+> Path: Data Scientists · step 1/4 — before `devin-search`
 <!-- DEVIN-ECO:END -->
 
-
 # devin-graph
 
 > **Unofficial community project.** Not affiliated with, endorsed by, or
@@ -65,17 +64,6 @@ build. Schema drift is gated by `devin-internals-spec`'s version detector.
 
 Requires Python ≥ 3.10 and `pipx` or `uv`. Per-OS setup lives in the platform guides: [Linux](README.linux.md) · [Personal Windows](README.windows.md) · [Corporate Windows](README.corporate-windows.md).
 
-<!-- DIST-STATUS:BEGIN — generated from devin-powerups/registry.json -->
-> **Source-only distribution.** This tool is not yet published to PyPI.
-> Install from source:
->
-> ```bash
-> pipx install git+https://github.com/Icaro0310/devin-graph.git
-> # or
-> uv tool install git+https://github.com/Icaro0310/devin-graph.git
-> ```
-<!-- DIST-STATUS:END -->
-
 ## Usage
 
 ```bash
@@ -92,6 +80,10 @@ devin-graph query projects-graph           --graph graph.db --json
 
 # D3-friendly dump: {"meta", "nodes", "edges"}
 devin-graph export --format json --graph graph.db --out graph.json
+
+# diagnostics: edge-less nodes (report-only) and per-session blame
+devin-graph orphans                      --graph graph.db
+devin-graph blame-session <id-or-prefix> --graph graph.db
 ```
 
 Matching is forgiving (`src/app.py` finds `/repo/alpha/src/app.py`);
@@ -100,6 +92,15 @@ by two or more distinct projects, with the project and session lists —
 exportable as JSON like the other queries. The source DB is opened
 `mode=ro` and never written — tests assert its hash is unchanged.
 
+`orphans` lists nodes with no incident edges (id, kind, owner, a
+`prunable` flag marking the subset the next `build` would drop —
+shared, ownerless nodes; owned orphans persist with their owner). It is
+report-only and never deletes. `blame-session <id>` shows what a
+session produced and touched: its owned nodes and edges plus the
+resolved files, tools, projects and commits reachable through them,
+with the extraction-ledger timestamp. `<id>` accepts a unique prefix;
+a missing or ambiguous match exits 2 and lists candidates.
+
 ## Works with Devin alone (Devin-only mode)
 
 devin-graph builds `graph.db` locally from Devin's session stores — the whole
@@ -115,13 +116,10 @@ Windows and `$XDG_DATA_HOME/devin/cli/sessions.db` on Linux (default
 `~/.local/share/devin/cli/sessions.db`). A legacy `~/.config/devin` location
 is also checked. Pass `--sessions-db` to override.
 
-
 `commit` nodes + `produced`/`referenced` edges attribute sessions to git SHAs seen in tool calls (exact when the SHA appears in a `git commit`/`git push` call, `seen` otherwise). `devin-graph sql "SELECT ..."` runs read-only SQL over graph.db (SELECT/WITH only, `query_only` pragma).
 
-
 `--vscdb` (auto-detected on build) adds GUI coverage: `gui_session` nodes keyed by the generated session slug, `gui_workspace` edges to their workspace project, enriched with `lastAccessed` when a `resourceToSpace` editor URI links a space to the slug. Best-effort: only the observed `windsurfSpace.*` keys are read; unknown/malformed keys are skipped. Pass `--vscdb none` to disable.
 
-
 `devin-graph view --out file.html` renders the graph as a self-contained HTML page (embedded JSON + vanilla-JS force layout — zero CDN, works fully offline). `--limit` caps nodes (highest-degree kept, flagged TRUNCATED in the header).
 
 ## Limitations
@@ -151,6 +149,47 @@ DDL, synthetic rows) — no binary fixtures are committed. See
 [docs/SPEC.md](docs/SPEC.md) for the graph model and
 [STATUS.md](STATUS.md) for the roadmap.
 
+## Adapters (MCP server, Devin skill, plugin)
+
+`devin_graph.mcp_server` exposes one read-only tool via the
+`devin-graph-mcp` entry point (`pip install 'devin-graph[mcp]'`):
+`graph_query` (same JSON as `devin-graph query <what> --json`).
+
+`adapters/` is a self-contained Devin plugin root
+(`adapters/.devin-plugin/plugin.json` +
+`adapters/skills/devin-graph/SKILL.md`), installed with
+`devin plugins install
+Icaro0310/devin-explore#packages/graph/adapters` — it ships in the
+repo, not inside the wheel. The manifest launches the server through
+`uvx --from 'devin-graph[mcp]' devin-graph-mcp`, which resolves the
+published PyPI release — no local install needed. To run the server
+from a source checkout instead, install it editable
+(`pip install -e '.[mcp]'`) and call `devin-graph-mcp` directly, or
+point a local manifest copy at the checkout
+(`uvx --from './packages/graph[mcp]' devin-graph-mcp`).
+
+### MCP host configs
+
+Same stdio server in other hosts — server name `devin-graph`:
+
+**Zed** — `context_servers` in `~/.config/zed/settings.json`:
+
+```jsonc
+{ "context_servers": { "devin-graph": { "command": { "path": "devin-graph-mcp", "args": [] } } } }
+```
+
+**JetBrains AI Assistant** — Settings → Tools → AI Assistant → Model Context Protocol → Add:
+
+```json
+{ "mcpServers": { "devin-graph": { "command": "devin-graph-mcp" } } }
+```
+
+**Antigravity** — `~/.gemini/config/mcp_config.json`:
+
+```json
+{ "mcpServers": { "devin-graph": { "command": "devin-graph-mcp" } } }
+```
+
 ## When to use this
 
 - You need cross-session questions: which sessions touched file X, which

{devin_graph-0.1.0 → devin_graph-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devin-graph"
-version = "0.1.0"
+version = "0.1.2"
 description = "Knowledge graph over Devin sessions — projects, files, tools and decisions as queryable nodes."
 readme = "README.md"
 license = { text = "MIT" }
@@ -15,10 +15,12 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=8"]
+dev = ["pytest>=8", "mcp>=1.2"]
+mcp = ["mcp>=1.2"]
 
 [project.scripts]
 devin-graph = "devin_graph.cli:main"
+devin-graph-mcp = "devin_graph.mcp_server:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]

devin_graph-0.1.2/src/devin_graph/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.2"

{devin_graph-0.1.0 → devin_graph-0.1.2}/src/devin_graph/cli.py

@@ -10,20 +10,19 @@ from pathlib import Path
 from devin_internals import SchemaError
 from devin_internals.parsers import SessionsStore
 
-from devin_graph.paths import default_state_vscdb
-from devin_graph.vscdb import extract_vscdb
-
 from devin_graph import __version__
-from devin_graph.paths import default_sessions_db
+from devin_graph.paths import default_sessions_db, default_state_vscdb
 from devin_graph.query import (
+    blame_session,
+    orphaned_nodes,
     project_detail,
     projects_graph,
     sessions_for_file,
     sessions_for_tool,
     shared_files,
-    tools_for_project,
 )
 from devin_graph.store import GraphStore
+from devin_graph.vscdb import extract_vscdb
 
 DEFAULT_GRAPH = "graph.db"
 
@@ -56,7 +55,7 @@ def _open_graph(graph_arg: str | None) -> GraphStore:
             file=sys.stderr,
         )
         raise SystemExit(2)
-    return GraphStore(path)
+    return GraphStore(path, readonly=True)
 
 
 def _add_graph(sub: argparse.ArgumentParser) -> None:
@@ -113,6 +112,24 @@ def build_parser() -> argparse.ArgumentParser:
     sq.add_argument("--json", action="store_true")
     sq.set_defaults(func=_cmd_query)
 
+    o = sub.add_parser(
+        "orphans", help="nodes with no incident edges — report-only, "
+        "never deletes (prunable flags what the next build would drop)")
+    _add_graph(o)
+    o.add_argument("--json", action="store_true")
+    o.set_defaults(func=_cmd_orphans)
+
+    bl = sub.add_parser(
+        "blame-session",
+        help="what a session produced/touched in the graph — owned "
+        "nodes and edges plus the files, tools, projects and commits "
+        "they reach")
+    bl.add_argument(
+        "session_id", help="session id or unique prefix")
+    _add_graph(bl)
+    bl.add_argument("--json", action="store_true")
+    bl.set_defaults(func=_cmd_blame)
+
     e = sub.add_parser("export", help="dump nodes+edges (D3-friendly)")
     e.add_argument("--format", choices=["json"], default="json")
     _add_graph(e)
@@ -229,6 +246,64 @@ def _print_query(what: str, data: dict) -> None:
             print(f"call: {t['id']} → {t['file']}")
 
 
+def _cmd_orphans(args: argparse.Namespace) -> int:
+    with _open_graph(args.graph) as gs:
+        data = orphaned_nodes(gs)
+    if args.json:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return 0
+    if not data["nodes"]:
+        print("no orphaned nodes")
+        return 0
+    for n in data["nodes"]:
+        label = n.get("name") or ""
+        keep = "" if n["prunable"] else " (owned — kept by prune)"
+        print(f"{n['id']}  {label}{keep}".rstrip())
+    print(f"{data['count']} orphan(s)")
+    return 0
+
+
+def _cmd_blame(args: argparse.Namespace) -> int:
+    with _open_graph(args.graph) as gs:
+        data = blame_session(gs, args.session_id)
+    if data["session"] is None:
+        cand = data.get("candidates") or []
+        hint = f" — candidates: {', '.join(cand[:10])}" if cand else ""
+        print(
+            f"devin-graph: no session matches {args.session_id!r}{hint}",
+            file=sys.stderr,
+        )
+        return 2
+    if args.json:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return 0
+    s = data["session"]
+    print(f"session: {data['session_id']}  {s.get('title') or 'Untitled'}")
+    if data["projects"]:
+        print("project: " + ", ".join(data["projects"]))
+    c = data["counts"]
+    print(
+        f"produced: {c['nodes']} node(s), {c['edges']} edge(s) · "
+        f"touched: {c['files']} file(s), {c['tools']} tool(s), "
+        f"{c['commits']} commit(s)"
+    )
+    if data["nodes_owned"]:
+        owned = [n for n in data["nodes_owned"] if n["kind"] == "tool_call"]
+        if owned:
+            print(f"tool calls ({len(owned)}):")
+            for n in owned:
+                print(f"  {n['key']}")
+    if data["files"]:
+        print(f"files ({len(data['files'])}):")
+        for f in data["files"]:
+            print(f"  {f}")
+    if data["tools"]:
+        print("tools: " + ", ".join(data["tools"]))
+    for cm in data["commits"]:
+        print(f"commit {cm['sha'][:7]} ({cm['relation']})")
+    return 0
+
+
 def _cmd_export(args: argparse.Namespace) -> int:
     with _open_graph(args.graph) as gs:
         data = gs.export()

{devin_graph-0.1.0 → devin_graph-0.1.2}/src/devin_graph/extract.py

@@ -30,10 +30,11 @@ from __future__ import annotations
 import json
 import posixpath
 import re
+from collections.abc import Iterable, Iterator
 from dataclasses import dataclass, field
+from typing import Any
 
 from devin_internals.commits import commit_references
-from typing import Any, Iterable, Iterator
 
 NODE_KINDS = ("session", "project", "file", "tool", "tool_call", "commit",
               "gui_session")
@@ -87,7 +88,7 @@ class Extraction:
     nodes: list[Node] = field(default_factory=list)
     edges: list[Edge] = field(default_factory=list)
 
-    def merged(self) -> "Extraction":
+    def merged(self) -> Extraction:
         seen_n: dict[tuple[str, str], Node] = {}
         seen_e: set[tuple] = set()
         out = Extraction()

devin_graph-0.1.2/src/devin_graph/mcp_server.py

@@ -0,0 +1,134 @@
+"""devin-graph as an MCP server: the ``query`` subcommands as one tool.
+
+One tool, ``graph_query`` — the read half of ``devin-graph query`` —
+returns the same JSON payloads as ``devin-graph query <what> --json``.
+Read-only by construction: ``build``, ``export``, ``sql`` and ``view``
+stay CLI-only; opening the graph never writes to it, and the source
+stores are never touched.
+
+The logic lives in :func:`do_query`, unit-testable without a running
+server or the ``mcp`` package. ``build_server()`` wraps it — needs the
+``mcp`` extra: ``pip install 'devin-graph[mcp]'``.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from devin_graph.query import (
+    project_detail,
+    projects_graph,
+    sessions_for_file,
+    sessions_for_tool,
+    shared_files,
+)
+from devin_graph.store import GraphStore
+
+# Same default as the CLI (`devin-graph query ... --graph graph.db`).
+DEFAULT_GRAPH = "graph.db"
+
+QUERY_TYPES = ("file", "tool", "project", "projects-graph", "shared-files")
+
+
+def do_query(query_type: str, target: str = "", graph: str = "") -> dict:
+    """Run one canned graph query; return its ``--json`` payload as a dict.
+
+    ``graph.db`` must already exist — the read-write
+    :class:`GraphStore` creates the file on open, so the missing-file
+    case (the CLI's exit-2) is checked *before* opening and maps to
+    ``{"error": "no_graph"}``. The store is then opened read-only
+    (``mode=ro`` + ``query_only``): no schema DDL, no repair of an
+    incomplete schema.
+    """
+    path = Path(graph or DEFAULT_GRAPH).expanduser()
+    if not path.exists():
+        return {
+            "error": "no_graph",
+            "detail": f"{path}: no such graph file — "
+            "run `devin-graph build` first",
+        }
+    with GraphStore(path, readonly=True) as gs:
+        if query_type == "file":
+            return sessions_for_file(gs, target)
+        if query_type == "tool":
+            return sessions_for_tool(gs, target)
+        if query_type == "project":
+            return project_detail(gs, target)
+        if query_type == "projects-graph":
+            return projects_graph(gs)
+        if query_type == "shared-files":
+            return shared_files(gs)
+    return {
+        "error": "bad_query",
+        "detail": f"unknown query_type {query_type!r} — "
+        f"expected one of {', '.join(QUERY_TYPES)}",
+    }
+
+
+def _err(error: Exception) -> dict:
+    return {"error": type(error).__name__, "detail": str(error)[:500]}
+
+
+def _make_app(name: str):
+    """Return an MCP server app across SDK versions.
+
+    mcp 2.x renamed FastMCP -> MCPServer; both expose the same .tool()
+    decorator and .run(transport='stdio'). Support whichever is installed.
+    """
+    try:  # mcp 2.x
+        from mcp.server.mcpserver import MCPServer
+        return MCPServer(name)
+    except ImportError:
+        pass
+    try:  # mcp 1.x
+        from mcp.server.fastmcp import FastMCP
+        return FastMCP(name)
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            "The MCP server needs the 'mcp' extra: "
+            "pip install 'devin-graph[mcp]'"
+        ) from e
+
+
+def build_server():
+    """Build the MCP server app with every devin-graph tool registered."""
+    server = _make_app("devin-graph")
+
+    @server.tool()
+    def graph_query(
+        query_type: str,
+        target: str = "",
+        graph: str = "",
+    ) -> dict:
+        """Query the session knowledge graph — the same JSON as
+        ``devin-graph query <what> --json``. Read-only: never modifies
+        ``graph.db`` or the source stores. ``query_type`` is one of
+        ``file`` (sessions that touched a path), ``tool``
+        (sessions/projects that used a tool), ``project`` (a project's
+        sessions, tools and files), ``projects-graph`` (project adjacency)
+        or ``shared-files`` (files touched by ≥2 projects). ``target`` is
+        the path/name for the first three; ``graph`` overrides the
+        default ``./graph.db`` location."""
+        try:
+            return do_query(query_type, target=target, graph=graph)
+        except Exception as error:  # noqa: BLE001 — tool boundary must not raise
+            return _err(error)
+
+    return server
+
+
+def main() -> None:
+    try:
+        server = build_server()
+    except ImportError as exc:
+        # Missing 'mcp' extra — install hint lives in the exception text.
+        print(f"error: {exc}", file=sys.stderr)
+        raise SystemExit(1)
+    # Startup failures at .run() are NOT the missing-extra case: let them
+    # keep their traceback so the real failure stays debuggable.
+    server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()