code-graph-context

Code Graph Context is an MCP server that builds a semantic, queryable graph of your TypeScript codebase and exposes it to Claude Code as a knowledge graph. It parses your code (via ts-morph), stores structural relationships in Neo4j, and enriches nodes with vector embeddings from OpenAI to enable semantic search and natural language queries. You can ask questions like which services depend on a particular class, where a function is used across the codebase, or generate refactoring plans with risk analysis. The server is designed to be framework-aware (with built-in NestJS patterns) but also extensible to capture custom framework schemas and patterns you define in configuration files. You can run multi-project graphs, perform incremental parsing, and leverage streaming import for large repositories.

Prerequisites:

• Node.js v18 or newer
• Docker (optional but recommended for Neo4j) or an existing Neo4j instance
• OpenAI API key for embeddings and NL queries

Installation steps:

1. Install the MCP server globally:

npm install -g code-graph-context

2. Start Neo4j (using Docker for a quick setup):

docker run -d --name neo4j -p 7687:7687 -p 7474:7474 \
  -e NEO4J_AUTH=neo4j/PASSWORD \
  neo4j:5.3

3. Initialize the MCP environment (sets up Neo4j via Docker if needed):

code-graph-context init

4. Configure Claude Code with your OpenAI API key (example shown below). Save a config JSON as ~/.claude.json or project-local .claude.json as described in the docs:

{
  "mcpServers": {
    "code-graph-context": {
      "command": "node",
      "args": ["/absolute/path/to/code-graph-context/dist/cli/cli.js"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key-here"
      }
    }
  }
}

5. Point Claude Code at your project and start parsing:

• In Claude Code, add the MCP server and run the parsing command (e.g., parse_typescript_project) to build the initial graph.

Optional: If you prefer not to use Docker, connect the MCP server to an existing Neo4j instance by updating the NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD environment variables in the mcp config.

Environment variables:

• OPENAI_API_KEY is required for embeddings and NL queries.
• NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD are optional if you have a locally configured Neo4j instance; defaults assume a local bolt URL with neo4j/PASSWORD.

Common issues:

• If embeddings fail due to API limits, adjust request rate or set a higher timeout in the embeddings service.
• Ensure your Node.js version matches the server's requirements and that the dist/cli/cli.js path exists after build (run npm run build if needed).
• For large codebases, enable incremental parsing and streaming imports to avoid timeouts.
• If Claude Code cannot access your OpenAI model, verify API key scope and permissions.

Tips:

• Use the framework-aware features to define or override patterns for NestJS controllers/services, and extend the parser with custom framework schemas.
• Leverage multi-project support to isolate graphs per workspace while retaining the ability to compare across projects.