How do I use repomap-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@repomap-mcp generate a repo map for this project" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

repomap-mcp

by fl0w1nd

Overview Schema Related Servers Score Discussions

Local

repomap-mcp

中文文档

An MCP server and CLI tool that generates ranked, token-budgeted code structure maps using Tree-sitter AST analysis and PageRank. Designed for AI agents that need to quickly understand unfamiliar codebases.

Inspired by aider's repo map, reimplemented in TypeScript via RepoMapper.

Why repomap-mcp?

AI coding agents face a fundamental problem: large codebases don't fit in a context window. Without structural awareness, agents resort to guessing file paths, reading irrelevant code, or asking the user to point them to the right place.

	Without repomap-mcp	With repomap-mcp
Codebase understanding	Blindly `cat` files one by one	Get a ranked structural overview in one call
Finding related code	Grep for strings, miss semantic connections	PageRank surfaces cross-file dependencies
Token efficiency	Read entire files, blow context budget	Token-budgeted output, only the important parts
Multi-language repos	Regex-based hacks per language	40+ languages via Tree-sitter AST, zero config
Task-specific focus	Same flat file listing every time	Personalized ranking based on focus files and identifiers

Key Features

Semantic, not textual — uses Tree-sitter AST to extract real definitions and references, not string matching
PageRank ranking — files that are heavily referenced across the codebase rank higher, just like important web pages
Neighbor propagation — when focusing on a type definition file, code that uses those types also gets boosted
Token-budgeted — binary search automatically selects the maximum amount of relevant code that fits your budget
Context-aware rendering — shows parent scopes (class/function signatures) around each definition, not raw line dumps
Disk cache — parsed tags are cached per-file with mtime invalidation; subsequent runs are near-instant
Zero config — auto-detects MCP mode, respects .gitignore, discovers languages by extension

Related MCP server: CodeSift

How It Works

Source files ──scan──▶ Tree-sitter AST ──extract──▶ Definitions & References
                                                            │
                                                            ▼
                                                  Cross-file ref graph
                                                            │
                                                            ▼
Token-budgeted output ◀──select── Ranked definitions ◀──PageRank──┘

File discovery — recursive scan respecting .gitignore
AST parsing — Tree-sitter (WASM) with Aider's SCM queries, 40+ languages
Graph construction — cross-file reference edges (file A references identifier defined in file B → A→B)
PageRank — personalized ranking with neighbor propagation for focus/priority files
Token budgeting — binary search to fit the most relevant definitions within a token limit
Context rendering — code snippets with parent scope context and elision

Quick Start

As an MCP Server

Add to your MCP client config (Claude Desktop, Cursor, Windsurf, etc.):

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

The server auto-detects MCP mode when stdin is piped — no flags needed.

As a CLI Tool

# Generate a repo map for the current directory
npx repomap-mcp --root .

# With token limit and verbose report
npx repomap-mcp --root /path/to/repo --map-tokens 4096 --verbose

# Focus on known files, boost specific identifiers
npx repomap-mcp --root . --focus-files src/db.ts --priority-idents "UserService"

Use Cases

1. Explore an unfamiliar codebase

"I just cloned this repo. Give me a structural overview."

The agent calls repo_map with just projectRoot. The output is a ranked list of the most important definitions across the entire codebase — entry points, core types, key functions — all within the token budget.

2. Investigate code around a known file

"I've read src/lib/db.ts. What else should I look at?"

The agent sets focusFiles: ["src/lib/db.ts"]. The map now centers around db.ts — files that import its types, functions that call its exports — while db.ts itself is excluded since the agent already has it.

3. Locate a specific symbol

"Where is handleWebSocket defined and who calls it?"

The agent calls search_identifiers with query: "handleWebSocket". Returns definition sites and all reference sites with surrounding code context.

4. Task-focused deep dive

"Refactor the authentication flow. The key types are in src/auth/types.ts and the main logic is AuthService."

The agent combines parameters:

{
  "projectRoot": "/path/to/repo",
  "focusFiles": ["src/auth/types.ts"],
  "priorityIdentifiers": ["AuthService"],
  "tokenLimit": 4096
}

The output prioritizes: code related to src/auth/types.ts (neighbor propagation), any file defining or heavily using AuthService (×10 boost), all within 4096 tokens.

Prompt Example

Here's a system prompt snippet showing how an AI agent can leverage repomap-mcp:

You have access to the `repo_map` tool. Use it to understand the codebase before
making changes:

1. On first interaction with a repo, call repo_map with just the projectRoot to
   get an overview.
2. After reading key files, pass them as focusFiles to discover related code you
   haven't seen yet.
3. When the user mentions specific functions or classes, pass them as
   priorityIdentifiers to surface their definitions and usage patterns.
4. Use search_identifiers to locate exact definition and reference sites for any
   symbol.

MCP Tools

`repo_map`

Generate a ranked repository map of code definitions.

Parameter	Type	Description
`projectRoot`	`string`	Required. Absolute path to the repository root
`focusFiles`	`string[]`	Already-known files as ranking anchor (×20). Excluded from output
`additionalFiles`	`string[]`	Extra files to include in analysis
`priorityFiles`	`string[]`	Important files to boost in ranking (×5)
`priorityIdentifiers`	`string[]`	Identifier names to boost in ranking (×10)
`tokenLimit`	`number`	Max tokens for output (default: `8192`)
`excludeUnranked`	`boolean`	Exclude zero-PageRank files (default: `false`)
`forceRefresh`	`boolean`	Bypass tag cache (default: `false`)

`search_identifiers`

Search for code identifiers across the repository via AST analysis.

Parameter	Type	Description
`projectRoot`	`string`	Required. Absolute path to the repository root
`query`	`string`	Required. Identifier name (case-insensitive substring match)
`maxResults`	`number`	Max results (default: `50`)
`includeDefinitions`	`boolean`	Include definition sites (default: `true`)
`includeReferences`	`boolean`	Include reference sites (default: `true`)

CLI Options

Option	Default	Description
`--root <dir>`	`.`	Repository root directory
`--map-tokens <n>`	`8192`	Maximum tokens for output
`--focus-files <files...>`	—	Known files; ranking anchor, excluded from output (×20)
`--additional-files <files...>`	—	Extra files to include in analysis
`--priority-files <files...>`	—	Important files to boost (×5)
`--priority-idents <idents...>`	—	Important identifiers to boost (×10)
`--verbose`	`false`	Print report to stderr
`--force-refresh`	`false`	Bypass tag cache
`--exclude-unranked`	`false`	Hide zero-PageRank files
`--serve`	—	Force MCP stdio server mode

Supported Languages

Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, Scala, Dart, Lua, Elixir, Elm, OCaml, Haskell, Julia, Fortran, Clojure, R, Zig, HCL/Terraform, Solidity, and more — 40+ languages via Tree-sitter WASM grammars.

Development

git clone https://github.com/fl0w1nd/repomap-mcp.git
cd repomap-mcp
pnpm install
pnpm build

Debug with MCP Inspector

pnpm inspect

Opens a web UI at http://localhost:6274 for interactive tool testing. Config stored in mcp.json.

Architecture

src/
├── index.ts           Entry point — CLI / MCP mode dispatch
├── server.ts          MCP server and tool registration
├── cli.ts             CLI argument parsing
├── repomap.ts         Core pipeline orchestration
├── tags.ts            Tree-sitter tag extraction
├── pagerank.ts        PageRank algorithm
├── tree-context.ts    Code snippet rendering with context
├── file-discovery.ts  Recursive file scanning + .gitignore
├── languages.ts       Language detection from extensions
├── token-counter.ts   Token counting (gpt-tokenizer)
├── cache.ts           Disk-based tag cache
└── utils.ts           Shared types
queries/               Tree-sitter SCM queries (from Aider)

License

MIT

Available Tools

2 tools

repo_mapGenerate Repo MapA

Generate a ranked repository map of code definitions via PageRank over cross-file reference graphs. Useful for understanding codebase structure, discovering entry points, or finding code related to specific files or identifiers.

ParametersJSON Schema

Name	Required	Description
`verbose`	No
`focusFiles`	No	Already-known files used as ranking anchor (x20 boost). Related code ranks higher; these files are excluded from output.
`tokenLimit`	No	Maximum token count for the output map
`projectRoot`	Yes	Absolute path to the repository root
`forceRefresh`	No	Bypass tag cache and re-parse all files
`priorityFiles`	No	Important files that receive a ranking boost (x5). Still included in output, unlike focusFiles.
`additionalFiles`	No	Extra file paths to include in analysis beyond auto-discovered ones.
`excludeUnranked`	No	Exclude files with zero PageRank from output
`priorityIdentifiers`	No	Identifier names to boost in ranking (x10). Matches definitions across all files.

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It explains the core mechanism (PageRank over reference graphs) and key behaviors like focusFiles being excluded from output while getting a 20x boost. It could be more transparent about performance implications (e.g., parsing large repos) or caching behavior beyond the forceRefresh parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is reasonably concise at two sentences, front-loading the core mechanism and purpose. It efficiently covers key use cases without unnecessary detail. Minor improvement could be made by adding a brief sentence about output format or limitations, but the current structure is effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the moderate complexity (9 parameters, 1 required, no output schema), the description adequately covers the tool's purpose and key behaviors. The schema covers parameter descriptions well, reducing the burden on the description. Without an output schema, the description could be more explicit about what the map contains (e.g., code definitions, file paths) but remains sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 89% schema description coverage, the baseline is 3. Most parameters have clear descriptions in the schema, but the description adds value by explaining the ranking boost multipliers (e.g., 'x20 boost' for focusFiles, 'x5' for priorityFiles, 'x10' for priorityIdentifiers) and the exclusion behavior of focusFiles. This extra context justifies the baseline score but does not significantly exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a 'ranked repository map of code definitions via PageRank over cross-file reference graphs.' It specifies the primary purpose (understanding codebase structure, discovering entry points, finding related code) and distinguishes itself from sibling 'search_identifiers' by emphasizing ranking and graph analysis rather than simple search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage contexts like 'understanding codebase structure' and 'finding code related to specific files or identifiers,' giving clear guidance on when to use it. However, it does not explicitly state when not to use it or directly compare to 'search_identifiers' as an alternative, which would elevate it to a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_identifiersSearch IdentifiersA

Search for code identifiers (functions, classes, variables) across the repository via Tree-sitter AST analysis. Returns matching definitions and references with code context.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Identifier name to search for (case-insensitive substring match)
`maxResults`	No	Maximum number of results
`projectRoot`	Yes	Absolute path to the repository root
`includeReferences`	No	Include reference sites
`includeDefinitions`	No	Include definition sites

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It mentions AST analysis and returning definitions/references, but does not disclose performance characteristics, failure modes, supported languages, or prerequisites. The behavioral transparency is insufficient for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence (two clauses) that is front-loaded with the core action. Every word contributes meaning; there is no redundancy or fluff. It is an exemplary model of conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters, no output schema, and a sibling tool, the description covers the basic purpose but lacks details on return value structure, limitations, or edge cases. It is adequate for a straightforward search tool but leaves gaps for an agent to fully understand invocation behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds context that the search is for 'code identifiers' and returns 'definitions and references', but this does not significantly enhance understanding beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific verb 'Search', resource 'code identifiers', and method 'Tree-sitter AST analysis'. It distinguishes from the sibling 'repo_map' by focusing on identifiers rather than repository structure. The purpose is unambiguous and not a tautology.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for searching code identifiers but provides no explicit guidance on when to use this tool versus the sibling 'repo_map'. There are no conditions, exclusions, or alternative suggestions, leaving the agent to infer context from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

2 tool updatesv0.1.1Aug 18, 2026
- First observedrepo_map
- First observedsearch_identifiers

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Disambiguation5/5

The two tools have clearly distinct purposes: repo_map provides a high-level structural overview via PageRank, while search_identifiers finds specific code symbols. There is no overlap in functionality, so an agent can easily choose the right one.

Naming Consistency5/5

Both tool names use a consistent verb_noun pattern (repo_map, search_identifiers) with clear verbs describing the action and nouns describing the target. The naming is predictable and descriptive.

Tool Count3/5

With only two tools, the server feels thin but not inadequate given its focused purpose on codebase mapping and identifier search. The scope is narrow enough that two tools may suffice, though additional tools like file listing or definition retrieval could be expected.

Completeness3/5

The server covers two core needs (structural overview and symbol search), but is missing common operations like viewing file contents, getting code definitions at a point, or listing references for a symbol. An agent may hit dead ends if it needs more detailed code navigation beyond identifiers.

Maintenance

ActivityMaintained

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

gread A
io.github.NitroRCr
An MCP server that gives your AI access to the source code and docs of all public github repos
Version Control Code Analysis Documentation Access
5361
H-Index A
ai.xr-utilities
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Search Documentation Access
2
driflyte-mcp-server
com.driflyte
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
Search Web Scraping Knowledge & Memory
211
Remote Desktop CommanderOAuth
app.desktopcommander
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Shell Access OS Automation
214

Related MCP Servers

codeweave-mcp
Code Analysis Developer Tools RAG Systems
semihkayan
A
license
Not graded
quality
D
maintenance
An MCP server that gives AI agents structured code understanding and precise code intelligence via local indexing of AST, call graphs, and semantic search.
Updated 3 months ago (2026-05-26 10:13 UTC)
76
4
Apache 2.0
CodeSift
Code Analysis Developer Tools
greglas75
A
license
Not graded
quality
C
maintenance
Token-efficient code intelligence MCP server that indexes codebases with tree-sitter AST parsing and provides 150 tools for AI agents, using 61-95% fewer tokens than traditional grep/Read workflows.
Updated 3 days ago (2026-09-03 20:57 UTC)
380
4
Business Source 1.1
@penqwin/mcp
Developer Tools Code Analysis
Penqwin
A
license
A
quality
B
maintenance
An AST-based MCP server that provides token-efficient codebase skeletons to LLM agents, reducing context token usage by 80-95% by exposing structural information instead of full source files.
Updated 2 months ago (2026-07-11 13:21 UTC)
5
16
2
MIT
Kodama MCP
krazke
-
license
Not graded
quality
Not graded
maintenance
AST-aware code exploration MCP server for AI agents, optimized for token efficiency.
Updated 3 months ago (2026-06-19 12:36 UTC)
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/fl0w1nd/repomap-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

repomap-mcp

Why repomap-mcp?

Key Features

How It Works

Quick Start

As an MCP Server

As a CLI Tool

Use Cases

1. Explore an unfamiliar codebase

2. Investigate code around a known file

3. Locate a specific symbol

4. Task-focused deep dive

Prompt Example

MCP Tools

repo_map

search_identifiers

CLI Options

Supported Languages

Development

Debug with MCP Inspector

Architecture

License

Available Tools

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

codeweave-mcp

CodeSift

@penqwin/mcp

Kodama MCP

Latest Blog Posts

MCP directory API

`repo_map`

`search_identifiers`