English Français العربية

MCP Repo Mapper

Official registry Developer tools

Deterministic repository structure mapping for onboarding agents.

Source code Documentation

What can you do with MCP Repo Mapper?

  • scan_repo(path) returns a typed repo scan with files, language breakdown, entry points, Python dependency graph, and detected frameworks.
  • find_circular_deps(path) returns circular dependencies from the static dependency graph.
  • language_breakdown(path) returns language counts by file count and bytes.
  • detect_framework(path) detects FastAPI, Flask, Django, Express, and Spring using registry-based markers.
  • find_entry_points(path) returns ranked entry point candidates such as Python mains, FastAPI apps, package start scripts, Dockerfiles, and Node indexes.
  • repo-structure://{url_hash} returns a cached JSON scan result after a tool call has populated the cache.

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package mcp-repo-mapper
Claude Code 
claude mcp add mcp-repo-mapper -- uvx mcp-repo-mapper==0.1.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "mcp-repo-mapper": {
            "command": "uvx",
            "args": [
                "mcp-repo-mapper==0.1.0"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. mcp-repo-mapper
  2. Codebase Onboarding Stack
  3. Features
  4. Install
  5. Development
  6. Resource Flow
  7. Scope And Limitations
  8. License

mcp-repo-mapper

mcp-repo-mapper is a FastMCP server for deterministic repository structure mapping. It scans a local codebase and exposes file structure, language counts, Python import dependencies, circular dependency detection, framework detection, entry point candidates, and a cached repo structure resource.

The server does not call an LLM and does not execute user code. It is intended as a grounded structure tool for codebase onboarding agents such as wayfinder.

Codebase Onboarding Stack

mcp-repo-mapper is the structure layer in a three-server MCP tool stack for Project 6 wayfinder, a codebase onboarding agent.

  • mcp-repo-mapper maps repository structure, languages, entry points, framework evidence, and Python dependency edges.
  • mcp-ast-explorer provides symbol-grounded Python definition, signature, reference, call-chain, and class-hierarchy lookups.
  • mcp-test-runner runs local pytest/Jest checks and coverage summaries so agent claims can be verified against execution.

In wayfinder, this server feeds the architecture-mapping step before semantic explanation or test verification begins.

Features

  • scan_repo(path) returns a typed repo scan with files, language breakdown, entry points, Python dependency graph, and detected frameworks.
  • find_circular_deps(path) returns circular dependencies from the static dependency graph.
  • language_breakdown(path) returns language counts by file count and bytes.
  • detect_framework(path) detects FastAPI, Flask, Django, Express, and Spring using registry-based markers.
  • find_entry_points(path) returns ranked entry point candidates such as Python mains, FastAPI apps, package start scripts, Dockerfiles, and Node indexes.
  • repo-structure://{url_hash} returns a cached JSON scan result after a tool call has populated the cache.

Install

uv sync --extra dev

Run the server locally:

uv run mcp-repo-mapper

Development

uv run ruff check .
uv run mypy
uv run pytest

Resource Flow

Resource reads use a cache populated by tool calls:

  1. Call scan_repo(path) or another scan-backed tool.
  2. Compute the repo hash with the same path.
  3. Read repo-structure://{url_hash}.

The public resource uses repo-structure://... because URL schemes cannot contain underscores.

Scope And Limitations

  • Dependency graph support is currently Python-only and based on static ast parsing.
  • Import graph resolution only records modules that exist inside the scanned repo.
  • Framework detection is heuristic marker matching, not a full build-system analysis.
  • The resource cache is in-memory and process-local.
  • The server scans local filesystem paths only.

License

MIT

Frequently asked questions

What is MCP Repo Mapper?

Deterministic repository structure mapping for onboarding agents.

How do I install MCP Repo Mapper?

It runs on your machine. In Claude Code: claude mcp add mcp-repo-mapper -- uvx mcp-repo-mapper==0.1.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does MCP Repo Mapper need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is MCP Repo Mapper open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains MCP Repo Mapper?

It is published by LovRanRan. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.