code-intelligence-mcp

A standalone Model Context Protocol (MCP) server that gives AI coding agents deep code intelligence — 37 tools spanning indexing, structural search, impact analysis, quality metrics, design-pattern recognition, documentation generation, and architectural governance.

The server parses repositories with tree-sitter, builds a SQLite knowledge graph, and exposes that graph to any MCP-compatible client (Claude Code, Claude Desktop, Cursor, Continue, etc.) over stdio or HTTP.

---

Table of Contents

• Features
• Architecture
• Requirements
• Installation
• Configuration
  • Claude Code / Claude Desktop
  • HTTP Mode
  • Environment Variables
• Quick Start
• Tool Reference (37 Tools)
  • Indexing & Project Management
  • Search & Retrieval
  • Impact & Dependencies
  • Code Quality
  • Documentation & Context
  • Change & Traces
  • Pattern Recognition
• CLI Usage
• HTTP API
• Development
• Security
• License

---

Features

• 37 MCP tools covering the full code-intelligence lifecycle.
• Multi-language parsers (tree-sitter): TypeScript, JavaScript, Python, Go, Rust, Java.
• SQLite-backed knowledge graph with WAL mode, FTS5 full-text search, and MinHash similarity.
• Cypher-like graph queries for multi-hop traversals.
• MinHash + LSH code similarity (K=64, 32×2 bands) for duplicate and near-duplicate detection.
• Impact analysis with hop-distance risk classification (CRITICAL / HIGH / MEDIUM / LOW).
• Design-pattern detection: Singleton, Factory, Observer, Repository, CircuitBreaker, plus anti-patterns (GodClass, SpaghettiCode, DeadCode, …).
• Architectural conformance checks against declared patterns (Hexagonal, CQRS, Microservices, …).
• HTTP + React UI on port 9749 for visual exploration.
• OpenTelemetry trace ingestion for runtime-augmented graphs.
• GitHub integration via @octokit/rest for PR analysis.

---

Architecture

Imports flow downward only — a hard rule enforced by linting.

shared/          ← zero deps (types, constants, utils)
  ↓
db/              ← better-sqlite3 (only here)
  ↓
pipeline/ + analysis/   ← pure logic
  ↓
mcp/tools/ + http/routes/   ← orchestration
  ↓
integrations/ + cli/    ← external effects

---

Requirements

Dependency	Version
Node.js	≥ 20.0.0
npm	≥ 10
OS	macOS, Linux, Windows (native better-sqlite3 + tree-sitter bindings)
Build tools	Python, a C/C++ compiler (for node-gyp)

---

Installation

From source

git clone <your-fork-or-path>/code-intelligence-mcp.git
cd code-intelligence-mcp
npm install
npm run build

The build produces:

• dist/index.js — MCP stdio server (primary entry point)
• dist/server.js — Fastify HTTP + UI server
• dist/cli.js — cim CLI

Tip: if npm install fails on tree-sitter-go peer-dependency resolution, run npm install --legacy-peer-deps.

---

Configuration

Claude Code / Claude Desktop

Add the server to your MCP configuration file.

Claude Code (.mcp.json in your workspace, or ~/.claude/mcp.json globally):

{
  "mcpServers": {
    "code-intelligence": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/absolute/path/to/code-intelligence-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "code-intelligence": {
      "command": "node",
      "args": ["/absolute/path/to/code-intelligence-mcp/dist/index.js"]
    }
  }
}

Restart the client and you should see all 37 tools exposed under the code-intelligence namespace.

HTTP Mode

node dist/server.js
# → http://127.0.0.1:9749

Open a browser at http://127.0.0.1:9749 for the React UI (graph view, quality metrics, patterns, ADRs).

Environment Variables

Variable	Default	Purpose
LOG_LEVEL	info	trace / debug / info / warn / error
CIM_HTTP_HOST	127.0.0.1	HTTP bind host (localhost only by default)
CIM_HTTP_PORT	9749	HTTP port
CIM_DB_PATH	~/.cim/projects.db	SQLite DB location
GITHUB_TOKEN	—	Enables GitHub PR integration
OTEL_EXPORTER_OTLP_ENDPOINT	—	OTLP trace ingest target

---

Quick Start

Once the MCP server is wired into your agent:

1. Index a repository — ask the agent: "Index the repo at /path/to/project."
2. Ask structural questions — "Find all HTTP routes in my-project", "Who calls createUser?", "Show the blast radius of changing AuthService.login."
3. Inspect quality — "Show me hotspots and god classes."
4. Detect patterns — "Does this codebase follow the Repository pattern?"
5. Open the UI — node dist/server.js, then visit http://127.0.0.1:9749.

---

Tool Reference (37 Tools)

Each tool below shows:

• Tool name as exposed to the MCP client
• Purpose (one-liner)
• Example natural-language prompt that will cause a good agent to invoke the tool
• Required / notable parameters

Indexing & Project Management

index_repository

Parse a repository into the knowledge graph.

• Prompt: "Index the repository at /Users/me/src/my-app."
• Params: repo_path (required), mode = full | moderate | fast

list_projects

List all indexed projects.

• Prompt: "Which projects have you indexed?"
• Params: (none)

index_status

Check indexing progress / completion.

• Prompt: "What's the indexing status of my-app?"
• Params: project

delete_project

Remove a project from the index.

• Prompt: "Delete the my-app index."
• Params: project

Search & Retrieval

search_graph

Search functions, classes, routes, variables in the graph. Prefer this over grep.

• Prompt: "Find all functions named login in my-app." / "Search my-app for anything related to payment webhooks."
• Params: project, plus any of query (BM25), name_pattern, qn_pattern, file_pattern, label, relationship, semantic_query (array)

query_graph

Run a Cypher-like query for multi-hop patterns / aggregations.

• Prompt: "Run a Cypher query on my-app to find classes with more than 20 outgoing CALLS edges."
• Params: query, project, max_rows?

trace_path

Trace callers, callees, data flow, or cross-service paths.

• Prompt: "Trace who calls PaymentService.charge in my-app, 3 levels deep."
• Params: function_name, project, direction, depth, mode = calls | data_flow | cross_service

get_code_snippet

Read source code for a specific symbol (after locating it with search_graph).

• Prompt: "Show me the source of src.auth.AuthService.login."
• Params: qualified_name, project, include_neighbors?

get_graph_schema

Return node labels and edge types present in the graph.

• Prompt: "What node labels exist in my-app?"
• Params: project

get_architecture

High-level architecture overview (packages, services, routes).

• Prompt: "Give me an architecture overview of my-app."
• Params: project, aspects? = structure | dependencies | routes | all

search_code

Graph-augmented text/regex code search (grep + graph enrichment).

• Prompt: "Grep for TODO: in my-app but rank by structural importance."
• Params: pattern, project, file_pattern?, mode = compact | full | files, regex?, limit?

Impact & Dependencies

analyze_impact

Blast-radius analysis of a change, with risk labels by hop distance.

• Prompt: "What's the blast radius of changing UserRepo.save in my-app?"
• Params: project, qualified_name, depth?, edge_types?

find_circular_deps

Detect circular dependency cycles (Tarjan's SCC).

• Prompt: "Are there any circular dependencies in my-app?"
• Params: project, scope?

get_dependency_graph

Package/module-level dependency graph.

• Prompt: "Show the module dependency graph for my-app."
• Params: project, scope?, include_external?, edge_types?

find_entry_points

List entry points, public APIs, HTTP routes.

• Prompt: "What are the entry points of my-app?"
• Params: project, label?, include_routes?

Code Quality

get_quality_metrics

Complexity distribution, function length stats, test ratio, language breakdown.

• Prompt: "Give me quality metrics for my-app."
• Params: project, file_pattern?

find_hotspots

High-complexity, high-fan-in functions (risky to change).

• Prompt: "Show me the top risky hotspots in my-app."
• Params: project, limit?, min_complexity?, min_fan_in?

find_code_smells

God classes, long functions, high complexity, hub functions, deep hierarchies.

• Prompt: "Find code smells in my-app."
• Params: project, smells?

find_similar_code

MinHash-based near-duplicate detection for a given symbol.

• Prompt: "Find code similar to src.util.parseConfig in my-app."
• Params: project, qualified_name, min_similarity?, limit?

find_dead_code

Functions/methods with no callers that are not entry points.

• Prompt: "Find dead code in my-app."
• Params: project, include_tests?, labels?

Documentation & Context

generate_docstring

Generate JSDoc / Python docstring / Markdown for a symbol based on graph context.

• Prompt: "Generate a JSDoc for src.auth.AuthService.login."
• Params: project, qualified_name, format = jsdoc | docstring | markdown

get_symbol_context

Rich context for a symbol: callers, callees, similar code, annotations, optional source.

• Prompt: "Give me full context for UserService.signup in my-app."
• Params: project, qualified_name, include_source?, caller_depth?, callee_depth?

annotate_node

Create / update / delete / list annotations on graph nodes.

• Prompt: "Annotate PaymentService.charge with a TODO: refactor retry logic."
• Params: project, mode = create | update | delete | list, plus qualified_name / content / kind / author / annotation_id depending on mode

manage_adr

Read or update Architecture Decision Records.

• Prompt: "Add an ADR to my-app about switching to event sourcing."
• Params: project, mode? = get | update | sections, content?, sections?

Change & Traces

detect_changes

Detect code changes and their impact since a git ref.

• Prompt: "What changed in my-app since HEAD~5?"
• Params: project, scope?, depth?, base_branch?, since?

get_change_summary

Summarize changed files, symbols, and blast radius since a ref.

• Prompt: "Summarize changes on this branch for my-app vs main."
• Params: project, since?, base_branch?, include_impact?, impact_depth?

ingest_traces

Ingest runtime traces (OTLP-compatible JSON) to enhance the graph.

• Prompt: "Ingest these runtime traces into my-app."
• Params: traces (array), project

Pattern Recognition

detect_singleton

• Prompt: "Find Singleton pattern instances in my-app."
• Params: project

detect_factory

• Prompt: "Detect Factory / Abstract Factory patterns in my-app."
• Params: project

detect_observer

• Prompt: "Detect Observer pattern usages in my-app."
• Params: project

detect_repository

• Prompt: "Find Repository pattern implementations in my-app."
• Params: project

detect_circuit_breaker

• Prompt: "Find CircuitBreaker / Retry patterns in my-app."
• Params: project

detect_anti_patterns

GodClass, SpaghettiCode, DeadCode, LongParameterList, CircularDependency.

• Prompt: "Detect anti-patterns in my-app."
• Params: project, kinds?

detect_patterns

Run every detector with optional category / confidence filter.

• Prompt: "Detect all design patterns in my-app with confidence ≥ 0.8."
• Params: project, category?, min_confidence?

generate_pattern_report

Comprehensive pattern report (design + anti + architectural style).

• Prompt: "Generate a pattern report for my-app."
• Params: project, min_confidence?

check_pattern_conformance

Verify the project conforms to a declared architectural pattern.

• Prompt: "Does my-app actually follow the Hexagonal architecture?"
• Params: project, declared_pattern, rules?

find_pattern_instances

Find all instances of a named pattern with location + evidence.

• Prompt: "Show all Singleton instances in my-app with evidence."
• Params: project, pattern, min_confidence?

---

CLI Usage

The cim CLI wraps the most common operations without needing an MCP client.

# after npm install -g . or using node dist/cli.js directly
cim index /path/to/repo
cim status <project>
cim search <project> --query "authenticate"
cim hotspots <project>
cim patterns <project> --report
cim delete <project>

Run cim --help for the full command list.

---

HTTP API

The Fastify server exposes REST endpoints at http://127.0.0.1:9749:

Endpoint	Method	Description
/api/layout	GET	3D graph layout (nodes + edges)
/api/index	POST	Trigger indexing
/api/index-status	GET	Indexing progress
/api/project-health	GET	DB integrity check
/api/logs	GET	SSE log stream
/api/browse	GET	Directory browser
/api/adr	GET / POST	Architecture Decision Records
/api/snapshots	GET	Temporal snapshots
/api/quality	GET	Quality metrics
/api/annotations	GET / POST	Node annotations
/api/patterns	GET	Pattern report
/api/project	DELETE	Remove project
/rpc	POST	JSON-RPC bridge for the UI
/v1/traces	POST	OTLP trace ingest

---

Development

npm run dev            # tsup watch mode
npm run typecheck      # tsc --noEmit (must pass before commit)
npm test               # vitest unit + integration
npm run test:coverage  # coverage report (≥ 80% gate on analysis/ and db/)
npm run lint           # eslint src

Project layout:

src/
  shared/         types, constants, utils, config
  db/             SQLite schema, prepared statements, migrations
  pipeline/       tree-sitter parsers, 8 indexing passes
  analysis/       quality, impact, patterns, similarity
  mcp/            MCP server + tool registry + handlers
  http/           Fastify routes, SSE, UI static assets
  integrations/   GitHub, CI gate, OpenTelemetry, VS Code
  cli/            commander-based `cim` binary
  watcher/        file-system change watcher
tests/
  unit/           in-memory DB, no filesystem
  integration/    tmp/ dirs, real DB, fixtures
ui/               React UI source (built to dist/ui/)

See CLAUDE.md for the full agent contributor guide (layering rules, MinHash invariants, tool-registration checklist, common pitfalls).

---

Security

• All SQL goes through prepared statements with ? placeholders — no string concatenation.
• No exec / spawn with unsanitized user input.
• File reads are sandboxed to the indexed repository root.
• The HTTP server binds to 127.0.0.1 by default; change via CIM_HTTP_HOST.
• GITHUB_TOKEN is read from env vars or cim.config.json — never commit it.

Report security issues privately rather than opening a public issue.

---

License

MIT © contributors.