jeromeetienne / jeromeetienne/codespine
Add an MCP server contrib exposing the graph as native agent tools
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 5
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
Goal
Ship an MCP server under ./contribs/mcp_server that exposes the knowledge graph as native, callable agent tools — the "MCP server" row of the integration table in #10. This is step 2 of that issue's proposed plan (after the Skill), giving tool-native, cross-agent access (Claude Code, Cursor, etc.) with no Bash shell-out.
Tracks #10.
Why we are well positioned
The query layer is already "JSON in, JSON out" and the tool surface is effectively designed:
GraphQuery(src/query/graph_query.ts) exposes instance methods that map one-to-one onto tools:whoCalls,references,blastRadius,deadExports,neighborhood.- src/agent/agent_tools.ts already declares these as OpenAI-format function tools (
find_symbol,who_calls,references,blast_radius,dead_exports,neighborhood). The MCP server is a thin re-expression of the same schema over the MCP protocol.
The hard part (a clean, machine-readable query surface) is done; this is plumbing.
Proposed tools
| MCP tool | Backing call | Purpose |
|---|---|---|
find_symbol |
name → candidate ids | Resolve a symbol name to node ids. Entry point — never invent ids. |
who_calls |
GraphQuery.whoCalls(id) |
Direct callers of a function/method. |
references |
GraphQuery.references(id) |
Everything referencing a symbol/type (calls, type usage, heritage, reads). |
blast_radius |
GraphQuery.blastRadius(id, depth) |
Transitive impact of changing a node. |
dead_exports |
GraphQuery.deadExports() |
Exports with no references. |
neighborhood |
GraphQuery.neighborhood(id) |
Incoming/outgoing edges around a node. |
Scope
- New self-contained contrib package in
./contribs/mcp_server(its ownpackage.json, following theweb_visualisationcontrib layout). - Stdio MCP server (
@modelcontextprotocol/sdk) that opens the graph database and adaptsGraphQueryto MCP tool calls. - Reuse the existing tool names/descriptions from
agent_tools.tsso behavior matches the in-process agent. - README with install snippet and the
mcpServersconfig block for Claude Code / Cursor.
Out of scope
- The Skill (step 1 of #10) and the
PreToolUsealways-on hook (deferred in #10). - Any change to core
GraphQuery/ extraction code — the adapter should be additive.
References
- Parent issue: #10
GraphQuery: src/query/graph_query.ts- Existing tool schemas: src/agent/agent_tools.ts
- Graphify MCP roadmap (their issue #146): https://github.com/safishamsi/graphify
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading src/query/graph_query.ts and src/agent/agent_tools.ts, then compare the contribs/web_visualisation layout. The work is done when contribs/mcp_server contains its package, stdio MCP adapter, six matching tools, and README configuration examples, without changes to core GraphQuery or extraction code.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100