Skip to main content
Glama
pdavis68

RepoMap

by pdavis68
OverviewSchemaRelated ServersScoreDiscussions
Hybrid

RepoMap - Command-Line Tool and MCP Server

RepoMap is a powerful tool designed to help, primarily LLMs, understand and navigate complex codebases. It functions both as a command-line application for on-demand analysis and as an MCP (Model Context Protocol) server, providing continuous repository mapping capabilities to other applications. By generating a "map" of the software repository, RepoMap highlights important files, code definitions, and their relationships. It leverages Tree-sitter for accurate code parsing and the PageRank algorithm to rank code elements by importance, ensuring that the most relevant information is always prioritized.

Table of Contents

Related MCP server: MCP-Repo2LLM

Aider

RepoMap is 100% based on Aider's Repo map functionality, but I don't believe it shares any code with it. Allow me to explain.

My original effort was to take the RepoMap class from Aider, remove all the aider-specific dependencies, and then make it into a command-line tool. Python isn't my native language and I really struggled to get it to work.

So a few hours ago, I had a different idea. I took the RepoMap and some of its related code from aider and I fed it to an LLM (Either Claude or Gemini 2.5 Pro, can't remember) and had it create specifications for this, basically, from aider's implementation. So it generated a very detailed specification for this application (minus the MCP bits) and then I fed that to, well, Aider with Claude 3.7, and it built the command-line version of this.

I then used a combination of Aider w/Claude 3.7, Cline w/Gemini 2.5 Pro Preview & Gemini 2.5 Flash Preview, and Phind.com, and Gemini.com and Claude.com and ChatGPT.com and after a few hours, I finally got the MCP server sorted out. Again, keeping in mind, Python isn't really my native tongue.

Example Output

> python repomap.py . --chat-files repomap_class.py
Chat files: ['/mnt/programming/RepoMapper/repomap_class.py']
repomap_class.py:
(Rank value: 10.8111)

  36: CACHE_VERSION = 1
  39: TAGS_CACHE_DIR = os.path.join(os.getcwd(), f".repomap.tags.cache.v{CACHE_VERSION}")
  40: SQLITE_ERRORS = (sqlite3.OperationalError, sqlite3.DatabaseError)
  43: Tag = namedtuple("Tag", "rel_fname fname line name kind".split())
  46: class RepoMap:
  49:     def __init__(
  93:     def load_tags_cache(self):
 102:     def save_tags_cache(self):
 459:     def get_ranked_tags_map_uncached(
 483:         def try_tags(num_tags: int) -> Tuple[Optional[str], int]:
 512:     def get_repo_map(

utils.py:
(Rank value: 0.2297)

  18: Tag = namedtuple("Tag", "rel_fname fname line name kind".split())
  21: def count_tokens(text: str, model_name: str = "gpt-4") -> int:
  35: def read_text(filename: str, encoding: str = "utf-8", silent: bool = False) -> Optional[str]:

importance.py:
(Rank value: 0.1149)

   8: IMPORTANT_FILENAMES = {
  27: IMPORTANT_DIR_PATTERNS = {
  34: def is_important(rel_file_path: str) -> bool:
  56: def filter_important_files(file_paths: List[str]) -> List[str]:

    ...
    ...
    ...

Features

  • Smart Code Analysis: Uses Tree-sitter to parse source code and extract function/class definitions

  • Relevance Ranking: Employs PageRank algorithm to rank code elements by importance

  • Token-Aware: Respects token limits to fit within LLM context windows

  • Caching: Persistent caching for fast subsequent runs

  • Multi-Language: Supports Python, JavaScript, TypeScript, Java, C/C++, Go, Rust, and more

  • Important File Detection: Automatically identifies and prioritizes important files (README, requirements.txt, etc.)

Installation

pip install -r requirements.txt

Usage

Basic Usage

# Map current directory
python repomap.py .

# Map specific directory with custom token limit
python repomap.py src/ --map-tokens 2048

# Map specific files
python repomap.py file1.py file2.py

# Specify chat files (higher priority) vs other files
python repomap.py --chat-files main.py --other-files src/

# Specify mentioned files and identifiers
python repomap.py --mentioned-files config.py --mentioned-idents "main_function"

# Enable verbose output
python repomap.py . --verbose

# Force refresh of caches
python repomap.py . --force-refresh

# Specify model for token counting
python repomap.py . --model gpt-3.5-turbo

# Set maximum context window
python repomap.py . --max-context-window 8192

# Exclude files with Page Rank 0
python repomap.py . --exclude-unranked

The tool prioritizes files in the following order:

  1. --chat-files: These files are given the highest priority, as they're assumed to be the files you're currently working on.

  2. --mentioned-files: These files are given a high priority, as they're explicitly mentioned in the current context.

  3. --other-files: These files are given the lowest priority and are used to provide additional context.

Advanced Options

# Enable verbose output
python repomap.py . --verbose

# Force refresh of caches
python repomap.py . --force-refresh

# Specify model for token counting
python repomap.py . --model gpt-3.5-turbo

# Set maximum context window
python repomap.py . --max-context-window 8192

# Exclude files with Page Rank 0
python repomap.py . --exclude-unranked

# Mention specific files or identifiers for higher priority
python repomap.py . --mentioned-files config.py --mentioned-idents "main_function"

How It Works

  1. File Discovery: Scans the repository for source files

  2. Code Parsing: Uses Tree-sitter to parse code and extract definitions/references

  3. Graph Building: Creates a graph where files are nodes and symbol references are edges

  4. Ranking: Applies PageRank algorithm to rank files and symbols by importance

  5. Token Optimization: Uses binary search to fit the most important content within token limits

  6. Output Generation: Formats the results as a readable code map

Output Format

The tool generates a structured view of your codebase showing:

  • File paths and important code sections

  • Function and class definitions

  • Key relationships between code elements

  • Prioritized based on actual usage and references

Dependencies

  • tiktoken: Token counting for various LLM models

  • networkx: Graph algorithms (PageRank)

  • diskcache: Persistent caching

  • grep-ast: Tree-sitter integration for code parsing

  • tree-sitter: Code parsing framework

  • pygments: Syntax highlighting and lexical analysis

Caching

The tool uses persistent caching to speed up subsequent runs:

  • Cache directory: .repomap.tags.cache.v1/

  • Automatically invalidated when files change

  • Can be cleared with --force-refresh

Supported Languages

Currently supports languages with Tree-sitter grammars:

  • arduino

  • chatito

  • commonlisp

  • cpp

  • csharp

  • c

  • dart

  • d

  • elisp

  • elixir

  • elm

  • gleam

  • go

  • javascript

  • java

  • lua

  • ocaml_interface

  • ocaml

  • pony

  • properties

  • python

  • racket

  • r

  • ruby

  • rust

  • solidity

  • swift

  • udev

  • c_sharp

  • hcl

  • kotlin

  • php

  • ql

  • scala

License

This implementation is based on the RepoMap design from the Aider project.

Running as an MCP Server

RepoMap can also be run as an MCP (Model Context Protocol) server, allowing other applications to access its repository mapping capabilities.

Setup

  1. The RepoMap MCP server uses STDIO (standard input/output) for communication. No additional configuration is required for the transport layer.

  2. To set up RepoMap as an MCP server with Cline (or similar tools like Roo), add the following configuration to your Cline settings file (e.g., cline_mcp_settings.json):

{
  "mcpServers": {
    "RepoMapper": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "/usr/bin/python3",
      "args": [
        "/absolute/path/to/repomap_server.py"
      ]
    }
  }
}

  • Replace "/absolute/path/to/repomap_server.py" with the actual path to your repomap_server.py file.

Usage

  1. Run the repomap_server.py script:

python repomap_server.py

  1. The server will start and listen for requests via STDIO.

  2. Other applications can then use the repo_map tool provided by the server to generate repository maps. They must specify the project_root parameter as an absolute path to the project they want to map.

Changelog

7/13/2025 - Removed the project.json dependency. Fixed the MCP server to be a little easier for the LLM to work with in terms of filenames.

Available Tools

2 tools
repo_mapA

Generate a repository map for the specified files, providing a list of function prototypes and variables for files as well as relevant related files. Provide filenames relative to the project_root. In addition to the files provided, relevant related files will also be included with a very small ranking boost.

:param project_root: Root directory of the project to search. (must be an absolute path!) :param chat_files: A list of file paths that are currently in the chat context. These files will receive the highest ranking. :param other_files: A list of other relevant file paths in the repository to consider for the map. They receive a lower ranking boost than mentioned_files and chat_files. :param token_limit: The maximum number of tokens the generated repository map should occupy. Defaults to 8192. :param exclude_unranked: If True, files with a PageRank of 0.0 will be excluded from the map. Defaults to False. :param force_refresh: If True, forces a refresh of the repository map cache. Defaults to False. :param mentioned_files: Optional list of file paths explicitly mentioned in the conversation and receive a mid-level ranking boost. :param mentioned_idents: Optional list of identifiers explicitly mentioned in the conversation, to boost their ranking. :param verbose: If True, enables verbose logging for the RepoMap generation process. Defaults to False. :param max_context_window: Optional maximum context window size for token calculation, used to adjust map token limit when no chat files are provided. :returns: A dictionary containing: - 'map': the generated repository map string - 'report': a dictionary with file processing details including: - 'included': list of processed files - 'excluded': dictionary of excluded files with reasons - 'definition_matches': count of matched definitions - 'reference_matches': count of matched references - 'total_files_considered': total files processed Or an 'error' key if an error occurred.

ParametersJSON Schema
NameRequiredDescriptionDefault
project_rootYes
chat_filesNo
other_filesNo
token_limitNo
exclude_unrankedNo
force_refreshNo
mentioned_filesNo
mentioned_identsNo
verboseNo
max_context_windowNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it generates a map with ranking boosts for different file types, includes related files, respects a token limit, can exclude unranked files, supports cache refreshing, and returns a structured dictionary with map and report. It doesn't mention permissions, rate limits, or error handling beyond the returns statement, but covers core operational traits well.

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

Conciseness3/5

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

The description is front-loaded with the core purpose, but becomes verbose with extensive parameter documentation that might be better suited to the schema. While informative, the length could be optimized; some parameter details (like defaults) are redundant if the schema is well-structured. Every sentence adds value, but the structure mixes high-level purpose with low-level param specs.

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

Completeness5/5

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

Given the complexity (10 parameters, no annotations, output schema provided), the description is highly complete. It explains the tool's purpose, parameter semantics, ranking logic, and return structure. The output schema existence means the description doesn't need to detail return values, and it adequately covers behavioral aspects. No significant gaps remain for effective agent use.

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

Parameters5/5

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

Given 0% schema description coverage and 10 parameters, the description compensates fully by providing detailed semantic explanations for each parameter. It clarifies the purpose, constraints (e.g., 'must be an absolute path!' for project_root), ranking hierarchies (e.g., chat_files get 'highest ranking'), defaults, and optionality. This adds significant value beyond the bare schema.

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

Purpose4/5

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

The description clearly states the tool's purpose: 'Generate a repository map for the specified files, providing a list of function prototypes and variables for files as well as relevant related files.' It specifies the verb ('generate'), resource ('repository map'), and scope ('for the specified files'). However, it doesn't explicitly distinguish this from its sibling tool 'search_identifiers', which appears to be a different operation.

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 context through parameter explanations (e.g., 'files that are currently in the chat context' for chat_files), but doesn't provide explicit guidance on when to use this tool versus alternatives like 'search_identifiers'. It mentions ranking boosts for different file types, which hints at prioritization logic, but lacks clear when/when-not directives or named alternatives.

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

search_identifiersA

Search for identifiers in code files. Get back a list of matching identifiers with their file, line number, and context. When searching, just use the identifier name without any special characters, prefixes or suffixes. The search is case-insensitive.

Args: project_root: Root directory of the project to search. (must be an absolute path!) query: Search query (identifier name) max_results: Maximum number of results to return context_lines: Number of lines of context to show include_definitions: Whether to include definition occurrences include_references: Whether to include reference occurrences

Returns: Dictionary containing search results or error message

ParametersJSON Schema
NameRequiredDescriptionDefault
project_rootYes
queryYes
max_resultsNo
context_linesNo
include_definitionsNo
include_referencesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses some behavioral traits: search is case-insensitive, query formatting requirements, and that results include file, line number, and context. However, it doesn't mention performance characteristics, error handling, or other operational details like rate limits or authentication needs.

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 appropriately sized and well-structured with clear sections for purpose, usage notes, arguments, and returns. Each sentence adds value, though the formatting could be slightly more front-loaded by moving the 'Args' explanation closer to the beginning.

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 tool's moderate complexity (6 parameters, no annotations, but with output schema), the description is reasonably complete. It explains the purpose, parameters, and return format. The presence of an output schema means the description doesn't need to detail return values, which it correctly avoids. Some behavioral context could be added, but overall it's adequate.

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

Parameters4/5

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

With 0% schema description coverage, the description compensates well by explaining all 6 parameters in the 'Args' section, adding meaning beyond the bare schema. It clarifies that 'project_root' must be an absolute path and explains what each boolean parameter controls. The description provides essential semantic context that the schema lacks.

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 searches for identifiers in code files and returns matching identifiers with file, line number, and context. It specifies the resource (identifiers in code files) and verb (search), distinguishing it from the sibling 'repo_map' tool which likely provides a different functionality.

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

Usage Guidelines2/5

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

The description provides some usage guidance about how to format the search query (identifier name without special characters, case-insensitive), but it doesn't specify when to use this tool versus alternatives or mention the sibling 'repo_map' tool. There's no explicit guidance on use cases or exclusions.

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.

  1. 2 tool updates
    • 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 generates a comprehensive repository map with ranking and token management, while search_identifiers performs targeted identifier searches. There is no overlap in functionality—one is for mapping and the other for searching.

Naming Consistency4/5

Both tools use snake_case naming, which is consistent. However, repo_map uses a noun_verb pattern (map as a noun), while search_identifiers uses a verb_noun pattern, creating a minor deviation in naming conventions.

Tool Count3/5

With only 2 tools, the server feels thin for a repository analysis domain. While the tools cover mapping and searching, the scope suggests more operations could be included, such as file analysis or dependency tracking, to provide a more complete surface.

Completeness3/5

The tools cover mapping and searching, which are core functions, but there are notable gaps. For example, there is no tool for analyzing code structure (e.g., extracting functions or classes), managing the map (e.g., updating or deleting cached maps), or handling other repository operations like diffing or branching, limiting workflow coverage.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

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/pdavis68/RepoMapper'

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