mcp-codemap

MCP server that gives coding agents a mental map of your codebase with progressive disclosure - like foldable code sections in an IDE, but for LLMs.

The first run parses every source file using tree-sitter and builds a graph of entities (classes, functions, interfaces, etc.) and their relationships (imports, extends, implements). This is stored in a local SQLite database (.codemap/graph.db) so subsequent sessions read from the index instantly - no re-parsing needed.

It exposes three tools. map builds the big picture - every file, class, and function at a chosen detail level, from a quick outline to full signatures with docstrings and dependency edges. query zooms into a single entity for its source code, members, and relationships without a separate file read. reindex keeps things fresh after edits, auto-detecting changes via git diff.

Supported languages:

Why

Typical exploration to understand a backend directory (44 files, ~420 entities):

Without codemap - Glob/Read/Grep or an Explore subagent:

Step	Tool calls	Chars consumed
Glob to find files	1	~500
Read models.py (572 lines)	1	~15K
Read world_service.py (628 lines)	1	~18K
Read ws.py (570 lines)	1	~15K
Read events.py (299 lines)	1	~8K
Read 4-5 API route files	4-5	~60K
Grep for cross-file imports/usage	3-5	~10K
Total	~12-15 calls	~125K+

And that's optimistic - an Explore subagent often does 15-25 tool calls across multiple turns, each with its own overhead, and still misses things.

With codemap - one or two calls:

Level	Tool calls	Chars consumed
names (quick orient)	1	~6K
signatures (working knowledge)	1	~25K

That's 5-6x fewer tokens, 12-20x fewer tool calls, and complete coverage - every entity in every file, not just the ones the agent guessed to read.

Setup

Claude Code

# npx
claude mcp add codemap -- npx mcp-codemap

# docker
claude mcp add codemap -- docker run --rm -i -v .:/project:z ghcr.io/breca/mcp-codemap

The project directory is auto-detected via MCP roots. To set it explicitly:

npx mcp-codemap serve -p /path/to/your/project

The first run indexes the project automatically. The index is stored in .codemap/graph.db inside the project directory. Subsequent calls to map or query auto-detect changed files via git diff and refresh the index before returning results — no manual reindexing needed.

Other clients

Add the MCP server config to your client's config file:

Client	Config file
Claude Code	.mcp.json in project root
Cursor	.cursor/mcp.json in project root
Crush	.crush.json in project root
Continue	.continue/config.yaml
OpenCode	opencode.json in project root

.mcp.json (Claude Code, Cursor):

{
  "mcpServers": {
    "codemap": {
      "command": "npx",
      "args": ["mcp-codemap"]
    }
  }
}

{
  "mcpServers": {
    "codemap": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", ".:/project:z", "ghcr.io/breca/mcp-codemap"]
    }
  }
}

<details> <summary>Crush / OpenCode / Continue configs</summary>

.crush.json:

{
  "mcp": {
    "codemap": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-codemap"]
    }
  }
}

{
  "mcp": {
    "codemap": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", ".:/project:z", "ghcr.io/breca/mcp-codemap"]
    }
  }
}

opencode.json:

{
  "mcp": {
    "codemap": {
      "type": "local",
      "command": ["npx", "mcp-codemap"]
    }
  }
}

{
  "mcp": {
    "codemap": {
      "type": "local",
      "command": ["docker", "run", "--rm", "-i", "-v", ".:/project:z", "ghcr.io/breca/mcp-codemap"]
    }
  }
}

.continue/config.yaml:

mcpServers:
  - name: codemap
    command: npx
    args:
      - mcp-codemap

mcpServers:
  - name: codemap
    command: docker
    args:
      - run
      - --rm
      - -i
      - -v
      - .:/project:z
      - ghcr.io/breca/mcp-codemap

</details>

Tools

Response structure:

Element	Meaning
Header line	PROJECT: <files> | <entities> | <languages> - project summary
=== dir/ [N files, M entities] ===	Directory section with aggregate counts
C/F/M/I/P/E	Kind prefix: Class, Function, Method, Interface, Property, Enum
:10-342	Line range (start-end)
exp	Exported / public symbol
> imports:	Files this file imports from (resolved paths)
> used-by:	Files that import from this file

map - structural overview

Returns files, entities, signatures, and relationships as a compact text map.

map(scope?, detail?, max_depth?)

detail controls output density (default: "signatures"):

Level	Content	Relative size
"outline"	Files + entity counts	~1%
"names"	Entity names, kinds, line ranges + docstrings on top-level entities	~8%
"signatures"	Full signatures, docstrings, imports/used-by	~25%
"full"	Signatures + cross-file relationships	~40%

scope limits output to a directory or file prefix (e.g., "src/api").

Typical workflow:

map(detail="names")                          # orient on the whole project
map(scope="src/api", detail="signatures")    # drill into a module
map(detail="full")                           # inspect dependency graph

Example: map(scope="src/tools", detail="names")

PROJECT: 53 files | 642 entities | csharp/go/java/javascript/kotlin/php/python/ruby/rust/typescript
INDEXED: just now
C=class F=function M=method I=interface P=property E=enum V=variable T=type N=namespace

=== src/tools/ [5 files, 13 entities] ===

  src/tools/describe-entity.ts
    I DescribeEntityParams :6-9
      "Parameters for the describe-entity tool."
    F describeEntity :12-27
      "Generate or retrieve a natural-language description for a named entity."
    F formatDescribeResult :29-37

  src/tools/get-context.ts
    I GetContextParams :5-9
      "Parameters for the map tool: optional scope, depth limit, and detail level."
    F getContext :12-18
      "Build and return the compact text map of the codebase."

  src/tools/query.ts
    I QueryParams :6-8
      "Parameters for the query tool: entity name or qualified name."
    F queryEntity :11-104
      "Deep-dive on a single entity: signature, source, callers, callees, and members."

  src/tools/reindex.ts
    I ReindexParams :6-9
      "Parameters for the reindex tool: optional file paths and force flag."
    F reindex :12-52
      "Re-index changed files; auto-detects via git diff when no paths given."

  src/tools/update-context.ts
    I UpdateContextParams :6-10
      "Parameters for the update-context tool."
    F updateContext :13-55
      "Incrementally update the index; falls back to full rescan if requested."

Detail levels

outline - file list with entity counts:

PROJECT: 53 files | 642 entities | csharp/go/java/javascript/kotlin/php/python/ruby/rust/typescript
INDEXED: just now
C=class F=function M=method I=interface P=property E=enum V=variable T=type N=namespace

=== src/parser/languages/ [11 files, 162 entities] ===

  src/parser/languages/base.ts (10 entities)
  src/parser/languages/python.ts (12 entities)
  src/parser/languages/typescript.ts (10 entities)

names - adds entity names with kind prefix, line ranges, and docstrings on top-level entities:

  src/parser/languages/base.ts
    I ExtractedEntity :4-17
      "A code entity (class, function, variable, etc.) extracted from a parse tree."
    I FileParseResult :29-33
      "Complete extraction output for a single source file."
    I LanguageExtractor :45-50
      "Contract for language-specific extractors that turn parse trees into entities."
    F getDocComment :53-68
      "Extract a JSDoc-style comment immediately preceding a node."
    F getSignature :82-140
      "Build a human-readable signature string from a class, function, or interface node."

signatures - adds full signatures, docstrings, export markers, and dependency info:

  src/parser/languages/python.ts
    C class PythonExtractor implements LanguageExtractor :11-343  exp
      "Extracts classes, functions, and imports from Python source files."
      P language :12-12
      P extensions :13-13
      M extract(tree: Parser.Tree, sourceCode: string, filePath: string): FileParseResult :15-23
      M walkNode(
    node: Parser.SyntaxNode,
    sourceCode: string,
    filePath: string,
    entities: ExtractedEntity[],
    ...
  ): void :25-97
      M extractEntity(...): ExtractedEntity | null :99-171
    > imports: src/parser/languages/base.ts

  src/parser/languages/typescript.ts
    C class TypeScriptExtractor implements LanguageExtractor :15-352  exp
      "Extracts classes, functions, interfaces, and relationships from TypeScript/TSX files."
      ...
    > imports: src/parser/languages/base.ts
    > used-by: src/parser/languages/javascript.ts

full - adds a cross-file relationships section:

=== RELATIONSHIPS ===
src/parser/languages/javascript.ts -> src/parser/languages/typescript.ts [extends: TypeScriptExtractor]
src/parser/languages/python.ts -> src/parser/languages/base.ts [implements: LanguageExtractor]
src/parser/languages/typescript.ts -> src/parser/languages/base.ts [implements: LanguageExtractor]

query - deep dive on one entity

Returns signature, source code, callers, callees, and members for a single class, function, or method. Accepts simple or qualified names.

query(entity)

query(entity="UserService")             # find by name
query(entity="UserService.createUser")  # find by qualified name

Output includes the actual source code, so the agent doesn't need a separate file read to see the implementation.

Example output

class PythonExtractor [exported]
src/parser/languages/python.ts:10-342

SIGNATURE: class PythonExtractor implements LanguageExtractor

MEMBERS:
  property language :11-11
  property extensions :12-12
  method extract(tree, sourceCode, filePath): FileParseResult :14-22
  method walkNode(...): void :24-96
  method extractEntity(...): ExtractedEntity | null :98-170
  method extractDocstring(...): string | null :172-187

DEPENDS ON:
  imports ExtractedEntity (src/parser/languages/base.ts:3)
  imports FileParseResult (src/parser/languages/base.ts:26)
  implements LanguageExtractor (src/parser/languages/base.ts:40)

USED BY:
  imports ScanResult (src/parser/pipeline.ts:15)

SOURCE:
  10 | export class PythonExtractor implements LanguageExtractor {
  11 |   language = 'python';
  12 |   extensions = ['.py'];
  ...

Response structure:

Section	Content
Header	Entity kind, name, export status, file location
SIGNATURE	Full type signature
MEMBERS	Properties and methods with signatures and line ranges
DEPENDS ON	Entities this one imports, extends, or implements (with source locations)
USED BY	Entities that depend on this one
SOURCE	Full source code with line numbers

reindex - refresh after edits

Note: map and query automatically refresh the index before returning results, so explicit reindexing is only needed for a forced full rescan.

Re-indexes changed files. Auto-detects changes via git diff when called with no arguments.

reindex(paths?, force?)

reindex()                               # auto-detect via git diff
reindex(paths=["src/foo.ts"])           # specific files
reindex(force=true)                     # full rescan, ignore cache

Example output

Git diff update (30 changed files)
  Processed: 18
  Skipped (unchanged): 11
  Errors: 1
    src/broken.js: TypeError: Cannot read properties of undefined

Configuration

Place a config.json in the .codemap/ directory to override defaults:

{
  "excludePatterns": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/.git/**",
    "**/vendor/**",
    "**/__pycache__/**",
    "**/target/**",
    "**/*.min.js",
    "**/*.bundle.js",
    "**/*.generated.*",
    "**/.codemap/**"
  ],
  "maxFileSize": 1000000
}

Option	Type	Default	Description
excludePatterns	string[]	See above	Glob patterns for files/directories to skip
includePatterns	string[]	["**/*.{ts,tsx,js,...,c,h,cpp,hpp,...}"]	Glob patterns for files to include (non-git repos only)
languages	string[]	[] (all supported)	Restrict parsing to specific languages
maxFileSize	number	1000000	Skip files larger than this (bytes)
updateGitignore	boolean	true	Auto-add .codemap/ to .gitignore on init

In git repos, file discovery uses git ls-files and respects .gitignore automatically - includePatterns is only used in non-git repos as a fallback. The exclude patterns act as a secondary filter in both cases.

CLI

The same binary works as a standalone CLI:

# npx
npx mcp-codemap map [-s scope] [--detail level]     # print the map
npx mcp-codemap query <entity>                      # inspect an entity
npx mcp-codemap reindex [paths...]                  # re-index
npx mcp-codemap stats                               # show project stats
npx mcp-codemap web [--port 3333]                   # interactive web UI
npx mcp-codemap install-hooks                       # git hooks for auto re-indexing
npx mcp-codemap uninstall-hooks                     # remove installed git hooks

# docker (mount your project at /project)
docker run --rm -v .:/project:z ghcr.io/breca/mcp-codemap map -p /project
docker run --rm -v .:/project:z ghcr.io/breca/mcp-codemap stats -p /project
docker run --rm -v .:/project:z ghcr.io/breca/mcp-codemap query <entity> -p /project
docker run --rm -v .:/project:z -p 3333:3333 ghcr.io/breca/mcp-codemap web -p /project

Web UI

codemap web launches an interactive graph explorer in your browser - a visualization of every entity and relationship in the index.

codemap web [--port 3333]

Features:

• Graph canvas - entities rendered as color-coded nodes (red = class, blue = function, purple = interface, green = enum), sized by kind, with edges drawn between them. Pan, zoom, and drag nodes to explore.
• Layout modes - switch between five layouts via the top-right toolbar: Force (default), Clustered (grouped by file), Radial (most-connected at center), Columns (by directory), and Hierarchy (dependency depth top-to-bottom). Transitions are animated.
• Sidebar - searchable file tree with kind filters. Type a path prefix in the exclude input to hide irrelevant directories (e.g., tests).
• Detail panel - click any node or file to open a right-side panel showing its signature, file location, docstring, members, and incoming/outgoing edges. Click linked entities to navigate the graph.

Design decisions

Only path-resolved relationships (imports, extends, implements) are included in output. Name-based "calls" edges are excluded because global name lookup produces too many false positives (get, split, etc. matching unrelated symbols). See CONSTRAINTS.md for details.