Summary
This is the structure scanner for codebases that don't come with a map. It exposes scan_repo, find_circular_deps, language_breakdown, detect_framework, and find_entry_points as tools, plus a cached repo-structure resource. The Python dependency graph is built from AST parsing, framework detection looks for FastAPI, Flask, Django, Express, and Spring markers, and entry point ranking surfaces mains, app definitions, and Dockerfiles. It's deterministic and doesn't call an LLM or run your code. Designed as the first layer in a three server onboarding stack with mcp-ast-explorer and mcp-test-runner, feeding architecture mapping before you dive into symbols or tests.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
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-mappermaps repository structure, languages, entry points, framework evidence, and Python dependency edges.mcp-ast-explorerprovides symbol-grounded Python definition, signature, reference, call-chain, and class-hierarchy lookups.mcp-test-runnerruns 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:
- Call
scan_repo(path)or another scan-backed tool. - Compute the repo hash with the same path.
- 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
astparsing. - 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
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →