graphlens-mcp 0.1.0__tar.gz

graphlens_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikita Rybalchenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

graphlens_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.3
+Name: graphlens-mcp
+Version: 0.1.0
+Summary: Semantic code graph MCP server for coding agents
+Author: Neko1313
+Author-email: Neko1313 <nikita.ribalchencko@yandex.ru>
+License: MIT License
+         
+         Copyright (c) 2026 Nikita Rybalchenko
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: click>=8.4.2
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: graphlens[go,python,rust,typescript,php]>=0.7.0
+Requires-Dist: questionary>=2.0.1
+Requires-Dist: tomlkit>=0.15.0
+Requires-Dist: watchfiles>=0.24
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# graphlens-mcp
+
+[![CI](https://github.com/Neko1313/graphlens-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Neko1313/graphlens-mcp/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-github%20pages-blue)](https://neko1313.github.io/graphlens-mcp/)
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.13-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+A free, MIT-licensed [MCP](https://modelcontextprotocol.io) server that gives coding
+agents (Claude Code, Cursor, and compatible clients) a **semantic code graph** of your
+project — symbols, cross-file calls, references, imports and cross-language boundaries.
+
+Instead of reading files top-to-bottom or grepping for names, the agent **navigates the
+structure**: *who calls this function*, *what does it depend on*, *what breaks if I change
+its signature*. It is a thin runtime layer over the
+[`graphlens`](https://github.com/Neko1313/graphlens) analysis engine: `graphlens` provides
+the mechanisms (parsing, stable node identity, resolvers); `graphlens-mcp` owns the storage,
+freshness and the agent-facing surface.
+
+📖 **Documentation:** <https://neko1313.github.io/graphlens-mcp/>
+
+> Status: early. The core navigation works; see [Known limitations](#known-limitations).
+
+## Why
+
+A `filesystem`/grep MCP makes the agent read whole files and match text — slow, noisy, and
+blind to which of three modules actually calls `OrderService.create`. Bare tree-sitter
+gives single-file syntax but cannot resolve links *between* files. `graphlens-mcp` answers
+the cross-file questions — call graphs and impact analysis — and keeps the graph fresh as
+you edit, then teaches the agent to use it via a bundled navigation skill.
+
+## Install
+
+Requires **Python ≥ 3.13** (a constraint inherited from `graphlens`).
+
+```bash
+uv tool install graphlens-mcp      # or: pipx install graphlens-mcp
+```
+
+Python language analysis works out of the box (the `ty` type engine ships as a
+dependency). Other languages parse immediately and unlock full cross-file semantics once
+their toolchain is present (Node for TypeScript, the Go toolchain, etc.); without it that
+language is reported as `degraded` rather than blocking `init`.
+
+## Quickstart (two commands)
+
+```bash
+uv tool install graphlens-mcp        # 1. install
+cd your-project && graphlens-mcp init  # 2. index + configure your agent
+```
+
+`init` detects the project's languages, indexes the code into a local graph, writes the
+MCP server entry into your agent's config and installs the navigation skill. You do **not**
+run `serve` yourself — your agent launches it from the config. Restart the agent and ask
+it something like *"what breaks if I change the signature of `create_order`?"*.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `graphlens-mcp init` | Detect languages → toolchain doctor → full index → configure agents → install skill |
+| `graphlens-mcp serve` | Start the MCP server over stdio. **Launched by the agent**, not by you |
+| `graphlens-mcp status` | Show detected languages, toolchain status, and graph size/freshness |
+| `graphlens-mcp reindex` | Force a full rebuild (e.g. after installing a new toolchain) |
+| `graphlens-mcp remove` | Deregister from agents and (with `--purge-db`) delete the local graph |
+
+Useful `init` flags: `--root <dir>`, `--agent claude_code --agent cursor` (repeatable),
+`--no-agent`, `--no-skills`, `--db <path>`.
+
+The graph lives at `<project>/.graphlens/graph.db` (SQLite). It is a regenerable cache —
+safe to delete; `reindex` rebuilds it. Add `.graphlens/` to your VCS ignore (the bundled
+`init` flow assumes it is not committed).
+
+## Supported languages
+
+| Language | Engine | Out-of-box |
+|---|---|---|
+| Python | `ty` (bundled) | Full semantics immediately |
+| TypeScript | Node bridge | `degraded` without Node; full semantics with Node installed |
+| Go | Go toolchain | `degraded` without toolchain |
+| Rust | SCIP / rust-analyzer | `degraded` without toolchain |
+| PHP | PHP parser | `degraded` without toolchain |
+
+`graphlens-mcp status` reports the actual resolver status per language. When a toolchain is
+missing, that language is reported as **degraded** (parsed structure, calls/types not fully
+resolved) with an install hint — it never blocks `init`.
+
+## Agent tools
+
+Each response carries a graph-quality status (`ok` | `degraded`) so the agent never mistakes
+a partial answer for a complete one.
+
+| Tool | Purpose |
+|---|---|
+| `search_symbols` | Full-text search over symbol names — **start here** |
+| `get_node_info` | Source snippet + signature + location for a node |
+| `get_file_structure` | Symbol outline of a file |
+| `get_callees` | What a function calls (outgoing, up to `max_depth`) |
+| `get_callers` | Who calls a function — primary impact-analysis tool |
+| `get_neighbors` | Nodes within N hops in any direction |
+| `find_references` | Non-call usages (type annotations, assignments) |
+| `get_cross_language_calls` | Connections across service boundaries (HTTP/gRPC/queues) |
+
+## Freshness model
+
+A single mechanism keeps the graph current: a **filesystem watcher** (`serve` starts it by
+default; disable with `--no-watch`). When a file changes on disk the server re-indexes the
+**connected set** — the changed file plus the files that import it and the files it imports —
+with one full analyze, so cross-file edges are rebuilt correctly rather than left partial.
+Deleting a file prunes its symbols and refreshes its importers. There is no polling and no
+structure-only "skeleton" phase: every (re)index produces the full graph the resolver can
+give. As a backstop, a tool that touches a file the watcher hasn't processed yet triggers the
+same connected re-index on access.
+
+Files created, deleted or edited *while the server was down* are invisible to an event-based
+watcher, so `serve` runs a one-shot **reconcile** at startup: it scans the project, indexes
+new files, prunes vanished ones, and refreshes any that changed — then hands off to the
+watcher.
+
+## Known limitations
+
+- **Whole-project re-link:** the watcher re-links the *connected set* of a change, not the
+  entire project. A rename that ripples through many indirection layers — or creating a file
+  that an *unchanged* file already imports — may need a full `reindex` for an exact graph.
+- **Cross-language edges on incremental edits:** synthesized `COMMUNICATES_WITH` edges are
+  rebuilt on a full `reindex`; they can erode across incremental edits (the boundary-based
+  query still resolves connections). Run `reindex` for an exact cross-language view.
+
+## Uninstall
+
+`graphlens-mcp remove` deregisters the server from your agents; add `--purge-db` to also
+delete the local `.graphlens/` cache.
+
+## Development
+
+```bash
+uv sync --all-groups   # install lint + test tooling
+task check             # ruff + format-check + ty + bandit + pytest (the CI gate)
+task docs:serve        # preview the docs site locally (needs Node + pnpm)
+```
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the design and invariants, or the
+[documentation site](https://neko1313.github.io/graphlens-mcp/) for the full guide.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

graphlens_mcp-0.1.0/README.md

@@ -0,0 +1,146 @@
+# graphlens-mcp
+
+[![CI](https://github.com/Neko1313/graphlens-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Neko1313/graphlens-mcp/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-github%20pages-blue)](https://neko1313.github.io/graphlens-mcp/)
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.13-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+A free, MIT-licensed [MCP](https://modelcontextprotocol.io) server that gives coding
+agents (Claude Code, Cursor, and compatible clients) a **semantic code graph** of your
+project — symbols, cross-file calls, references, imports and cross-language boundaries.
+
+Instead of reading files top-to-bottom or grepping for names, the agent **navigates the
+structure**: *who calls this function*, *what does it depend on*, *what breaks if I change
+its signature*. It is a thin runtime layer over the
+[`graphlens`](https://github.com/Neko1313/graphlens) analysis engine: `graphlens` provides
+the mechanisms (parsing, stable node identity, resolvers); `graphlens-mcp` owns the storage,
+freshness and the agent-facing surface.
+
+📖 **Documentation:** <https://neko1313.github.io/graphlens-mcp/>
+
+> Status: early. The core navigation works; see [Known limitations](#known-limitations).
+
+## Why
+
+A `filesystem`/grep MCP makes the agent read whole files and match text — slow, noisy, and
+blind to which of three modules actually calls `OrderService.create`. Bare tree-sitter
+gives single-file syntax but cannot resolve links *between* files. `graphlens-mcp` answers
+the cross-file questions — call graphs and impact analysis — and keeps the graph fresh as
+you edit, then teaches the agent to use it via a bundled navigation skill.
+
+## Install
+
+Requires **Python ≥ 3.13** (a constraint inherited from `graphlens`).
+
+```bash
+uv tool install graphlens-mcp      # or: pipx install graphlens-mcp
+```
+
+Python language analysis works out of the box (the `ty` type engine ships as a
+dependency). Other languages parse immediately and unlock full cross-file semantics once
+their toolchain is present (Node for TypeScript, the Go toolchain, etc.); without it that
+language is reported as `degraded` rather than blocking `init`.
+
+## Quickstart (two commands)
+
+```bash
+uv tool install graphlens-mcp        # 1. install
+cd your-project && graphlens-mcp init  # 2. index + configure your agent
+```
+
+`init` detects the project's languages, indexes the code into a local graph, writes the
+MCP server entry into your agent's config and installs the navigation skill. You do **not**
+run `serve` yourself — your agent launches it from the config. Restart the agent and ask
+it something like *"what breaks if I change the signature of `create_order`?"*.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `graphlens-mcp init` | Detect languages → toolchain doctor → full index → configure agents → install skill |
+| `graphlens-mcp serve` | Start the MCP server over stdio. **Launched by the agent**, not by you |
+| `graphlens-mcp status` | Show detected languages, toolchain status, and graph size/freshness |
+| `graphlens-mcp reindex` | Force a full rebuild (e.g. after installing a new toolchain) |
+| `graphlens-mcp remove` | Deregister from agents and (with `--purge-db`) delete the local graph |
+
+Useful `init` flags: `--root <dir>`, `--agent claude_code --agent cursor` (repeatable),
+`--no-agent`, `--no-skills`, `--db <path>`.
+
+The graph lives at `<project>/.graphlens/graph.db` (SQLite). It is a regenerable cache —
+safe to delete; `reindex` rebuilds it. Add `.graphlens/` to your VCS ignore (the bundled
+`init` flow assumes it is not committed).
+
+## Supported languages
+
+| Language | Engine | Out-of-box |
+|---|---|---|
+| Python | `ty` (bundled) | Full semantics immediately |
+| TypeScript | Node bridge | `degraded` without Node; full semantics with Node installed |
+| Go | Go toolchain | `degraded` without toolchain |
+| Rust | SCIP / rust-analyzer | `degraded` without toolchain |
+| PHP | PHP parser | `degraded` without toolchain |
+
+`graphlens-mcp status` reports the actual resolver status per language. When a toolchain is
+missing, that language is reported as **degraded** (parsed structure, calls/types not fully
+resolved) with an install hint — it never blocks `init`.
+
+## Agent tools
+
+Each response carries a graph-quality status (`ok` | `degraded`) so the agent never mistakes
+a partial answer for a complete one.
+
+| Tool | Purpose |
+|---|---|
+| `search_symbols` | Full-text search over symbol names — **start here** |
+| `get_node_info` | Source snippet + signature + location for a node |
+| `get_file_structure` | Symbol outline of a file |
+| `get_callees` | What a function calls (outgoing, up to `max_depth`) |
+| `get_callers` | Who calls a function — primary impact-analysis tool |
+| `get_neighbors` | Nodes within N hops in any direction |
+| `find_references` | Non-call usages (type annotations, assignments) |
+| `get_cross_language_calls` | Connections across service boundaries (HTTP/gRPC/queues) |
+
+## Freshness model
+
+A single mechanism keeps the graph current: a **filesystem watcher** (`serve` starts it by
+default; disable with `--no-watch`). When a file changes on disk the server re-indexes the
+**connected set** — the changed file plus the files that import it and the files it imports —
+with one full analyze, so cross-file edges are rebuilt correctly rather than left partial.
+Deleting a file prunes its symbols and refreshes its importers. There is no polling and no
+structure-only "skeleton" phase: every (re)index produces the full graph the resolver can
+give. As a backstop, a tool that touches a file the watcher hasn't processed yet triggers the
+same connected re-index on access.
+
+Files created, deleted or edited *while the server was down* are invisible to an event-based
+watcher, so `serve` runs a one-shot **reconcile** at startup: it scans the project, indexes
+new files, prunes vanished ones, and refreshes any that changed — then hands off to the
+watcher.
+
+## Known limitations
+
+- **Whole-project re-link:** the watcher re-links the *connected set* of a change, not the
+  entire project. A rename that ripples through many indirection layers — or creating a file
+  that an *unchanged* file already imports — may need a full `reindex` for an exact graph.
+- **Cross-language edges on incremental edits:** synthesized `COMMUNICATES_WITH` edges are
+  rebuilt on a full `reindex`; they can erode across incremental edits (the boundary-based
+  query still resolves connections). Run `reindex` for an exact cross-language view.
+
+## Uninstall
+
+`graphlens-mcp remove` deregisters the server from your agents; add `--purge-db` to also
+delete the local `.graphlens/` cache.
+
+## Development
+
+```bash
+uv sync --all-groups   # install lint + test tooling
+task check             # ruff + format-check + ty + bandit + pytest (the CI gate)
+task docs:serve        # preview the docs site locally (needs Node + pnpm)
+```
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the design and invariants, or the
+[documentation site](https://neko1313.github.io/graphlens-mcp/) for the full guide.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

graphlens_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "graphlens-mcp"
+version = "0.1.0"
+description = "Semantic code graph MCP server for coding agents"
+readme = { file = "README.md", content-type = "text/markdown" }
+license = { file = "LICENSE" }
+authors = [
+    { name = "Neko1313", email = "nikita.ribalchencko@yandex.ru" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "aiosqlite>=0.22.1",
+    "click>=8.4.2",
+    "fastmcp>=3.4.2",
+    "graphlens[go,python,rust,typescript,php]>=0.7.0",
+    "questionary>=2.0.1",
+    "tomlkit>=0.15.0",
+    "watchfiles>=0.24",
+]
+
+[project.scripts]
+graphlens-mcp = "graphlens_mcp.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+# Mirrors the graphlens engine: a lint group and a test group, synced together via
+# `uv sync --all-groups`. Ruff/ty config lives in ruff.toml / ty.toml (engine parity).
+lint = [
+    "bandit>=1.9.3",
+    "ruff>=0.15.0",
+    "ty>=0.0.15",
+]
+test = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "pytest-timeout>=2.3",
+]
+
+# ----------------------------------------------------------------------
+# Tooling
+# ----------------------------------------------------------------------
+
+[tool.bandit]
+exclude_dirs = ["tests"]
+# B608: the only f-string SQL builds an IN(...) from a count of '?' placeholders or a
+# fixed table allowlist — never user data. Ruff's S608 (enabled via ALL) is the active
+# per-site guard that will flag any genuinely unsafe new query.
+skips = ["B608"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+# A per-test ceiling so a single hang (e.g. a stalled DB worker) fails fast with a
+# traceback instead of stalling the whole run; integration analyze stays well under it.
+addopts = "-q --strict-markers --timeout=120"
+markers = [
+    "unit: pure tests, no external processes",
+    "integration: real graphlens analyze / filesystem / CLI",
+    "store: SqliteStore behavior",
+    "workspace: indexing & freshness",
+    "agents: agent registry (de)registration",
+    "cli: command-line interface",
+    "tools: MCP tool layer",
+    "golden: batch == incremental invariant",
+    "paths: path normalization",
+]

graphlens_mcp-0.1.0/src/graphlens_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""graphlens-mcp: semantic code graph MCP server for coding agents."""
+
+__version__ = "0.1.0"

graphlens_mcp-0.1.0/src/graphlens_mcp/agents/__init__.py

@@ -0,0 +1,11 @@
+"""Per-agent MCP config registry (de/registration of the graphlens server)."""
+
+from graphlens_mcp.agents.base import (
+    SERVER_KEY,
+    AgentSpec,
+    configure,
+    deregister,
+)
+from graphlens_mcp.agents.registry import REGISTRY
+
+__all__ = ["REGISTRY", "SERVER_KEY", "AgentSpec", "configure", "deregister"]

graphlens_mcp-0.1.0/src/graphlens_mcp/agents/base.py

@@ -0,0 +1,150 @@
+"""
+Agent registry primitives: a data-driven spec per MCP client + (de)register.
+
+Each coding agent stores MCP server config differently — Claude Code and
+Cursor use a ``mcpServers`` map, VS Code uses ``servers`` with a ``type``
+field, configs live at different paths and some are global.
+:class:`AgentSpec` captures those differences so adding an agent is data,
+not code, and ``init``/``remove`` operate on any spec uniformly.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import tomlkit
+import tomlkit.exceptions
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+# Key under which we register our server in each agent's config.
+SERVER_KEY = "graphlens"
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    """Declarative description of how to (de)register graphlens here."""
+
+    name: str  # registry key / --agent value
+    label: str  # human display name
+    scope: str  # 'project' or 'global'
+    servers_key: (
+        str  # top-level config key: 'mcpServers' | 'servers' | 'mcp_servers'
+    )
+    stdio_type: bool  # emit {"type": "stdio", ...} in the entry (VS Code)
+    path_fn: Callable[[Path], Path]  # config file location for a project root
+    detect_fn: Callable[[Path], bool]  # is this agent plausibly used here?
+    fmt: str = "json"  # config file format: 'json' | 'toml' (Codex)
+    install_skill: Callable[[Path], Path | None] | None = None
+
+    def config_path(self, project_root: Path) -> Path:
+        """Return this agent's MCP config file location for *project_root*."""
+        return self.path_fn(project_root.resolve())
+
+    def detect(self, project_root: Path) -> bool:
+        """Return True if this agent looks used for *project_root*."""
+        try:
+            return bool(self.detect_fn(project_root.resolve()))
+        except OSError:
+            return False
+
+
+def _server_entry(spec: AgentSpec, project_root: Path, db_path: Path) -> dict:
+    # Pass absolute --db and --root so the entry does not depend on the agent's
+    # working directory (clients launch the server with varying cwd).
+    entry: dict = {
+        "command": "graphlens-mcp",
+        "args": ["serve", "--db", str(db_path), "--root", str(project_root)],
+    }
+    if spec.stdio_type:
+        return {"type": "stdio", **entry}
+    return entry
+
+
+def configure(spec: AgentSpec, project_root: Path, db_path: Path) -> Path:
+    """Write/update the graphlens MCP entry in *spec*'s config. Idempotent."""
+    project_root = project_root.resolve()
+    path = spec.config_path(project_root)
+    entry = _server_entry(spec, project_root, db_path.resolve())
+
+    if spec.fmt == "toml":
+        doc = _load_toml(path)
+        table = doc.get(spec.servers_key)
+        if not isinstance(table, dict):
+            table = tomlkit.table()
+            doc[spec.servers_key] = table
+        table[SERVER_KEY] = entry
+        _atomic_write_text(path, tomlkit.dumps(doc))
+    else:
+        cfg = _load_json(path)
+        cfg.setdefault(spec.servers_key, {})[SERVER_KEY] = entry
+        _atomic_write_text(path, json.dumps(cfg, indent=2) + "\n")
+    return path
+
+
+def deregister(spec: AgentSpec, project_root: Path) -> bool:
+    """Remove graphlens entry from *spec*'s config. True if removed."""
+    path = spec.config_path(project_root.resolve())
+    if not path.exists():
+        return False
+
+    if spec.fmt == "toml":
+        doc = _load_toml(path)
+        table = doc.get(spec.servers_key)
+        if not isinstance(table, dict) or SERVER_KEY not in table:
+            return False
+        del table[SERVER_KEY]
+        if len(table) == 0:
+            del doc[spec.servers_key]
+        _atomic_write_text(path, tomlkit.dumps(doc))
+        return True
+
+    cfg = _load_json(path)
+    servers = cfg.get(spec.servers_key)
+    if not isinstance(servers, dict) or SERVER_KEY not in servers:
+        return False
+    del servers[SERVER_KEY]
+    if not servers:
+        cfg.pop(spec.servers_key, None)
+    _atomic_write_text(path, json.dumps(cfg, indent=2) + "\n")
+    return True
+
+
+def _load_json(path: Path) -> dict:
+    if path.exists():
+        try:
+            data = json.loads(path.read_text())
+            return data if isinstance(data, dict) else {}
+        except (OSError, json.JSONDecodeError):
+            return {}
+    return {}
+
+
+def _load_toml(path: Path) -> tomlkit.TOMLDocument:
+    if path.exists():
+        try:
+            return tomlkit.parse(path.read_text())
+        except (OSError, tomlkit.exceptions.TOMLKitError):
+            return tomlkit.document()
+    return tomlkit.document()
+
+
+def _atomic_write_text(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(
+        dir=path.parent, prefix=".graphlens-", suffix=".tmp"
+    )
+    tmp_path = Path(tmp)
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(text)
+        tmp_path.replace(path)
+    finally:
+        if tmp_path.exists():
+            tmp_path.unlink()

graphlens_mcp-0.1.0/src/graphlens_mcp/agents/registry.py

@@ -0,0 +1,90 @@
+"""
+The set of supported coding agents.
+
+Only agents whose MCP config format and location are known are included, so we
+never write a config an agent cannot read. Adding another agent is a single
+:class:`AgentSpec` entry. Codex uses TOML (``~/.codex/config.toml``); the
+rest use JSON. Zed and Cline use distinct schemas/locations and are not
+registered yet.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from graphlens_mcp.agents.base import AgentSpec
+
+_SKILL_SRC = (
+    Path(__file__).parent.parent
+    / "skills"
+    / "graphlens-navigation"
+    / "SKILL.md"
+)
+
+
+def _install_claude_skill(_project_root: Path) -> Path | None:
+    if not _SKILL_SRC.exists():
+        return None
+    dest_dir = Path.home() / ".claude" / "skills" / "graphlens-navigation"
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / "SKILL.md"
+    shutil.copy2(_SKILL_SRC, dest)
+    return dest
+
+
+REGISTRY: dict[str, AgentSpec] = {
+    "claude_code": AgentSpec(
+        name="claude_code",
+        label="Claude Code",
+        scope="project",
+        servers_key="mcpServers",
+        stdio_type=False,
+        path_fn=lambda r: r / ".mcp.json",
+        detect_fn=lambda r: (
+            (r / ".claude").is_dir()
+            or (r / ".mcp.json").exists()
+            or (r / "CLAUDE.md").exists()
+        ),
+        install_skill=_install_claude_skill,
+    ),
+    "cursor": AgentSpec(
+        name="cursor",
+        label="Cursor",
+        scope="project",
+        servers_key="mcpServers",
+        stdio_type=False,
+        path_fn=lambda r: r / ".cursor" / "mcp.json",
+        detect_fn=lambda r: (r / ".cursor").is_dir(),
+    ),
+    "windsurf": AgentSpec(
+        name="windsurf",
+        label="Windsurf",
+        scope="global",
+        servers_key="mcpServers",
+        stdio_type=False,
+        path_fn=lambda _r: (
+            Path.home() / ".codeium" / "windsurf" / "mcp_config.json"
+        ),
+        detect_fn=lambda _r: (Path.home() / ".codeium" / "windsurf").is_dir(),
+    ),
+    "vscode": AgentSpec(
+        name="vscode",
+        label="VS Code (Copilot)",
+        scope="project",
+        servers_key="servers",
+        stdio_type=True,
+        path_fn=lambda r: r / ".vscode" / "mcp.json",
+        detect_fn=lambda r: (r / ".vscode").is_dir(),
+    ),
+    "codex": AgentSpec(
+        name="codex",
+        label="Codex CLI",
+        scope="global",
+        servers_key="mcp_servers",
+        stdio_type=False,
+        fmt="toml",
+        path_fn=lambda _r: Path.home() / ".codex" / "config.toml",
+        detect_fn=lambda _r: (Path.home() / ".codex").is_dir(),
+    ),
+}