HydraGraph MCP

HydraGraph turns a TypeScript codebase into an explicit structural graph and serves graph-native code questions to any MCP client. It uses tree-sitter for AST extraction and self-hosted HydraDB for graph storage and OpenCypher traversal.

Status: early hackathon MVP. TypeScript/TSX is the deliberately narrow first-language scope.

Why the implementation differs from the hosted Hydra docs

The self-hosted hydra-db/hydradb repository does not expose the hosted knowledge SDK methods (upload.knowledge, full_recall, or graph_relations_by_source_id). Its documented public interfaces are Neo4j-compatible Bolt and:

POST /v1/graphs/{graph_id}/query

HydraGraph therefore inserts AST-derived vertices and edges with batched, parameterized OpenCypher UNWIND queries. CALLS, CALLS_API, IMPORTS, and CONTAINS edges are explicit and deterministic; no LLM relationship inference is involved. Static frontend fetch() paths are matched to Express route registrations to preserve cross-boundary dependencies.

MCP tools

• find_callers: direct reverse traversal over CALLS edges.
• impact_of_change: bounded transitive reverse traversal over CALLS and CALLS_API for a symbol or route's blast radius.
• explain_context: accepts a natural-language question, matches it to a HydraDB symbol, and returns structured callers, callees, call-site evidence, and two-hop impact for the MCP client's own model to reason over.

Quickstart

Requirements: Node.js 20+, npm, Docker Desktop, and PowerShell for the bundled Windows HydraDB startup script.

npm install
Copy-Item .env.example .env
npm run hydradb:start
$env:HYDRADB_TOKEN = "local-development-token-32-bytes"

The development script binds Bolt, HTTP, and admin ports to 127.0.0.1 only. It must not be used as a public deployment configuration.

Clone the real validation target next to this repository:

git clone https://github.com/sayan365/docwise ../target-docwise
npm run index -- ../target-docwise --dry-run
npm run index -- ../target-docwise
npm run hydradb:validate
npm run mcp:smoke

mcp:smoke verifies the tool schemas and makes live graph-backed impact_of_change and natural-language explain_context calls. No external LLM API key is required; the calling MCP client performs the reasoning.

The index command replaces HydraGraph's generated CodeNode data and its four relationship types. The MVP intentionally stores one repository per configured HydraDB graph.

Build and run the stdio MCP server:

npm run build
node dist/src/server.js

Real validation scenario

The target is sayan365/docwise, Sayan's TypeScript/React document-analysis application. HydraGraph extracts 27 source files, 92 nodes, and 165 resolved relationships, including six Express route nodes and four CALLS_API edges. It verifies this real cross-boundary chain from the checked-out source:

ScanView event handlers
  -> scanSample / scanDocumentText / scanDocumentFile
  -> analyzeWithAI
       -> getLanguage
       -> POST /api/analyze-document

That makes the headline question concrete: changing the /api/analyze-document response format reaches analyzeWithAI, all three scan entry points, and their upstream UI handlers. External and ambiguous ordinary calls remain unresolved instead of being guessed; the current dry run reports 449 such calls and zero unresolved static fetch() paths.

What HydraDB contributes

Without HydraDB, this project is an AST dump plus in-process maps. HydraDB persists the structural model and answers traversal queries: callers are incoming CALLS edges, and impact is a bounded breadth-first traversal over HydraDB results. The database is load-bearing, not an optional storage swap.

Verification

npm run check
npm test
npm run hydradb:validate
npm run mcp:smoke

Attribution

• HydraDB, AGPL-3.0, used as the external graph database.
• tree-sitter and tree-sitter-typescript, MIT, used for TypeScript/TSX parsing.
• Model Context Protocol TypeScript SDK, MIT, used for MCP transport and tool definitions.
• Docwise, used as the real-world validation target and not redistributed here.

License

MIT. See LICENSE. Project requirements and milestone evidence are tracked in docs/PRD.md.