jeromeetienne / jeromeetienne/codespine

Add an MCP server contrib exposing the graph as native agent tools

Open
#12 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
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 own package.json, following the web_visualisation contrib layout).
  • Stdio MCP server (@modelcontextprotocol/sdk) that opens the graph database and adapts GraphQuery to MCP tool calls.
  • Reuse the existing tool names/descriptions from agent_tools.ts so behavior matches the in-process agent.
  • README with install snippet and the mcpServers config block for Claude Code / Cursor.

Out of scope

  • The Skill (step 1 of #10) and the PreToolUse always-on hook (deferred in #10).
  • Any change to core GraphQuery / extraction code — the adapter should be additive.

References

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.