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