代码智能MCP服务器

codesight-mcp

Security-hardened, token-efficient code intelligence for AI assistants.

An MCP server that indexes local and GitHub codebases via tree-sitter AST parsing, then exposes 34 operations for symbol retrieval, code graph traversal, and impact analysis — available either as individual MCP tools (the default) or through a single query dispatch wrapper (advanced). All retrieval uses byte-offset precision to cut token costs by ~99% compared to sending full files. Supports 66 languages.

Based on jcodemunch-mcp by J. Gravelle, with code graph techniques from CodeGraphContext and security patterns from basalt-mcp.

Quick Navigation

• Features
• Supported Languages
• Quick Start
• Operations Reference
• Code Graph & Relationship Analysis
• Security Model
• Git Hooks
• Semantic Search
• Environment Variables

Features

Code Indexing & Retrieval

• Tree-sitter AST parsing across 66 languages with byte-offset O(1) symbol retrieval
• Incremental indexing via content hashing — skip unchanged files on re-index
• Local + GitHub repository indexing — index folders on disk or fetch from GitHub
• AI-generated summaries — optional Anthropic API integration for symbol descriptions
• Full-text search across indexed file contents with redaction-aware matching
• Semantic search — hybrid keyword+vector scoring via on-device embeddings (optional [semantic] extra)

Code Graph & Relationship Analysis

• Callers & callees — who calls a function, and what does it call?
• Call chains — trace the full path between any two symbols
• Type hierarchy — inheritance trees and interface implementations
• Import graphs — which files import what, and from where?
• Impact analysis — change a function, see everything affected downstream

Security

• 6-step path validation chain — null bytes, traversal, limits, resolution, containment, symlinks
• Content boundary markers — indirect prompt injection defense (Microsoft spotlighting research)
• Error sanitization — raw exceptions never reach the AI; system paths are always stripped
• Per-tool trust annotations — each of the 34 operations registers as its own MCP tool carrying readOnlyHint/destructiveHint annotations; source code in tool output is wrapped in <<<UNTRUSTED_CODE_{random token}>>> boundary markers (Microsoft spotlighting) that content cannot forge an end marker for, so it can never escape the boundary
• 2,648 tests — adversarial, security, integration, benchmark, fuzz, and stress coverage with real temp directories

Supported Languages

codesight-mcp supports 66 programming languages via tree-sitter, including Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, C#, Ruby, Swift, Kotlin, PHP, Dart, Perl, Haskell, Scala, Erlang, and 49 more. See the full language list for details.

Each language parser extracts functions, classes, methods, parameters, call relationships, imports, and inheritance to build a comprehensive code graph.

Quick Start

Platform support: POSIX only (Linux/macOS); Windows is not supported.

Prerequisites: git, Python ≥ 3.10, uv, and an MCP client (the examples below use the claude CLI). Everything after that comes from this repository.

Step 1: Install

git clone https://github.com/cmillstead/codesight-mcp.git
cd codesight-mcp
uv sync            # creates .venv/ from the lockfile with pinned versions

uv sync creates the .venv/ that every command below refers to. If you prefer pip, create the virtualenv yourself so those paths still resolve — and note this uses version ranges rather than the lockfile:

python3 -m venv .venv && .venv/bin/pip install -e .

Not published to PyPI — install from source only.

Step 2: Register the MCP server

Register the codesight-mcp stdio entrypoint that Step 1 installed into .venv/bin/. Run this from the repo root:

claude mcp add codesight --scope user \
  -e CODESIGHT_ALLOWED_ROOTS="$HOME/src" \
  -e GITHUB_TOKEN=ghp_... \
  -- "$PWD/.venv/bin/codesight-mcp"

Two details that matter:

• --scope user registers the server for every project. Without it claude mcp add defaults to local scope, which binds the server to whichever project you ran it in — here, the codesight-mcp clone itself — so it would not load in the repos you actually want to explore.
• The command path must be absolute. $PWD expands at registration time; your client does not run from this directory. Likewise CODESIGHT_ALLOWED_ROOTS must cover the repos you intend to index — $HOME/src works on both Linux and macOS, and indexing is denied outside it.

This registers 34 MCP tools — one per operation — each carrying its own readOnlyHint / destructiveHint annotation, so your client can distinguish safe reads from index-mutating calls.

If your client reads a project-level config file instead, .mcp.json.example shows the equivalent registration. Its command is relative, which only resolves when the client is launched from this repo root; anywhere else, substitute an absolute path.

Step 3: Verify the install

.venv/bin/codesight-mcp tools        # lists every registered tool as JSON
.venv/bin/codesight-mcp get-status   # server status, storage config, index stats

Both exit 0 on success. Running .venv/bin/codesight-mcp with no arguments starts the stdio server and waits for an MCP client — it will look like it has hung, which is correct; press Ctrl-C.

Then confirm the client side. Start a new client session (or reconnect) first — an already-running session will not pick up a server registered in Step 2. Ask your AI: "What's the codesight server status?" It should call get_status and report the indexed repo count.

Step 4: Index a repository

Before any other operations work, you must index at least one repository. Ask your AI:

• Local folder: "Index the repo at ~/src/myproject"
• GitHub repo: "Index the GitHub repo owner/myproject"

The AI calls the index_folder or index_repo tool, which fetches files, parses ASTs, and extracts symbols into ~/.code-index/. Subsequent calls skip unchanged files automatically.

Step 5: Explore

Once indexed, the AI uses get_repo_outline, search_symbols, and get_symbol to navigate your codebase — retrieving only the symbols it needs instead of entire files.

Step 6 (optional): Add a CLAUDE.md to indexed repos

Add a CLAUDE.md to each indexed repo so Claude Code prefers codesight-mcp over reading full files:

## Code Navigation

This repo is indexed in codesight-mcp. Use the codesight tools for all code
exploration instead of reading full files:

- `mcp__codesight__search_symbols` — find functions/classes/types by name or description
- `mcp__codesight__get_file_outline` — all symbols in a file with signatures
- `mcp__codesight__get_symbol` — full source of a specific symbol
- `mcp__codesight__get_repo_outline` — directory structure and language breakdown
- `mcp__codesight__get_callers` / `mcp__codesight__get_callees` — call graph navigation
- `mcp__codesight__get_call_chain` — trace execution paths between two symbols
- `mcp__codesight__get_impact` — see what's affected by changing a symbol

Use `Read` only for content that isn't a named symbol (config files, etc).

If you registered the dispatch wrapper instead (see below), replace those names with a single call: mcp__codesight__query({operation: "search-symbols", params: {...}}).

Advanced: single query dispatch tool

An alternative TypeScript wrapper collapses all 34 operations behind one MCP tool named query, which accepts { operation, params }. Use it if you would rather present your client with a single tool than one tool per operation, at the cost of losing per-tool annotations.

This is a separate repository, not part of this one. It lives at cmillstead/codesight-plugin and must be cloned independently. It also requires bun (curl -fsSL https://bun.sh/install | bash), which nothing else here needs. A future release replaces it with a generated wrapper/mcp-server.ts inside this repo; until then the two codebases can drift.

git clone https://github.com/cmillstead/codesight-plugin.git ~/src/codesight-plugin

claude mcp add codesight --scope user \
  -e CODESIGHT_ALLOWED_ROOTS="$HOME/src" \
  -e CODESIGHT_BIN="$PWD/.venv/bin/codesight-mcp" \
  -e GITHUB_TOKEN=ghp_... \
  -- bun run ~/src/codesight-plugin/mcp-server.ts

CODESIGHT_BIN is required here: the wrapper spawns the Python engine from this repo, and uv sync does not put .venv/bin on your PATH. Run the command from this repo root so $PWD resolves correctly.

Because all operations flow through a single entry point, per-operation readOnlyHint/destructiveHint annotations do not apply in the usual per-tool way. Instead, the wrapper enforces a trust boundary at the parameter level: path-bearing fields are validated against a trusted prefix before dispatch, and output from operations that return repo-controlled text is wrapped in <UNTRUSTED_OUTPUT> framing tags so the consuming agent treats the content as data rather than instructions.

Operations

codesight-mcp exposes 34 operations, organized into seven categories. On the default path each is its own MCP tool, invoked by its underscored name (mcp__codesight__get_symbol). Through the dispatch wrapper they are invoked as mcp__codesight__query({operation: "<name>", params: {...}}) using the kebab-case names below.

Indexing

Navigation

Search

Code Graph

Analysis & Visualization

Security

Dependencies & Diffing

Natural Language Examples

Once indexed, interact through your AI assistant using plain English:

Finding Code

• "Where is the process_payment function?"
• "Show me all classes related to authentication"
• "Find any code that handles database connections"

Understanding Relationships

• "What functions call validate_input?"
• "What does initialize_system call?"
• "Show me the full call chain from main to process_data"
• "What's the inheritance hierarchy for BaseController?"

Impact Analysis

• "If I change calculate_tax, what else is affected?"
• "Which files import the utils module?"
• "Show me everything downstream of authenticate_user"

Exploring Structure

• "Give me an overview of this repository"
• "What symbols are in src/server.py?"
• "List all indexed repos"

Code Graph & Relationship Analysis

codesight-mcp builds an in-memory code graph from relationships extracted during AST parsing. No external graph database is required — the graph uses dict-of-sets adjacency lists, constructed at query time from the symbol index.

How it works:

1. During indexing, the AST parser extracts calls, imports, and inherits_from relationships for each symbol
2. These relationships are stored alongside symbol metadata in the JSON index
3. At query time, CodeGraph.build(symbols) constructs the graph from symbol dicts
4. Graph tools (callers, callees, call chains, impact) traverse this structure using BFS with cycle detection

Compared to CodeGraphContext: codesight-mcp uses no external database (FalkorDB/Neo4j). The trade-off is simplicity and zero-config vs. the ability to handle massive graphs. For most projects (thousands of files), the in-memory approach is fast and sufficient.

Git Hooks: Auto-Reindex on Commit and Push

codesight-mcp includes git hooks that keep indexes current automatically:

Install in any repo:

cp /path/to/codesight-mcp/hooks/post-commit .git/hooks/post-commit
cp /path/to/codesight-mcp/hooks/post-push   .git/hooks/post-push
chmod +x .git/hooks/post-commit .git/hooks/post-push

Both hooks run in the background so they never block your workflow. Remove --no-ai from either hook if you want AI-generated summaries updated automatically.

One-time setup — git hooks don't inherit your shell environment, so credentials and the binary path must be provided separately:

mkdir -p ~/.config/codesight-mcp
cat > ~/.config/codesight-mcp/env <<'EOF'
export GITHUB_TOKEN=ghp_...
export CODESIGHT_BIN=/path/to/.venv/bin/codesight-mcp
EOF
chmod 600 ~/.config/codesight-mcp/env

You can also index directly from the command line:

codesight-mcp index ~/src/myproject              # index a local folder
codesight-mcp index ~/src/myproject --no-ai     # skip AI summaries (faster)
codesight-mcp index-repo owner/myproject        # index a GitHub repo

Security Model

codesight-mcp treats the connected AI as an untrusted principal. Every tool argument is validated before use. Every file path from the index is re-validated at retrieval time. Error messages are sanitized so system paths never leak.

See SECURITY.md for the full threat model, defense matrix, and validation chain details. Architecture Decision Records for key security decisions are in docs/decisions/.

Data Handling

When ANTHROPIC_API_KEY is set, codesight-mcp sends function and class signatures to the Anthropic API for AI-generated summaries during indexing. No source code is sent — only signatures. To disable, omit the ANTHROPIC_API_KEY environment variable.

Environment Variables

Semantic Search

Search by intent instead of exact names. Requires the semantic extra:

pip install codesight-mcp[semantic]   # adds fastembed (~100MB ONNX runtime + model weights)

Without this extra, passing semantic params returns a helpful error explaining what to install.

Parameters

Examples

# Find by intent, not exact name
mcp__codesight__search_symbols(repo="myproject", query="the function that validates credentials", semantic=True)

# Pure semantic search
mcp__codesight__search_symbols(repo="myproject", query="password hashing utility", semantic_only=True)

Environment Variables

How It Works

Embeddings are generated lazily on the first semantic query and cached in gzip-JSON sidecar files alongside the index. The cache is invalidated automatically on reindex. The default provider runs entirely on-device with no API calls. When semantic=false (the default), there is zero overhead -- embeddings are never loaded or computed.

Keyword scoring includes compound identifier splitting (hash_password → {hash, password}, AuthManager → {auth, manager}) and suffix stemming (hashing → hash, validates → validate), so intent-based queries match even without semantic search enabled.

Attribution

Based on jcodemunch-mcp by J. Gravelle. Code graph techniques adapted from CodeGraphContext. Security hardening inspired by basalt-mcp.

License

MIT — see LICENSE.