MCP Repo Mapper
Deterministic repository structure mapping for onboarding agents.
Open source Open in the app JSON README (API)
About
Deterministic repository structure mapping for onboarding agents.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- lovranran
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Last push
- 2026-05-25T15:43:29Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:01
- Updated
- 2026-08-29 03:02:01
- Origin id
io.github.LovRanRan/mcp-repo-mapper
README
# mcp-repo-mapper
<!-- mcp-name: io.github.LovRanRan/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`](https://github.com/LovRanRan/mcp-repo-mapper) maps repository structure, languages, entry points, framework evidence, and Python dependency edges.
- [`mcp-ast-explorer`](https://github.com/LovRanRan/mcp-ast-explorer) provides symbol-grounded Python definition, signature, reference, call-chain, and class-hierarchy lookups.
- [`mcp-test-runner`](https://github.com/LovRanRan/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
```bash
uv sync --extra dev
```
Run the server locally:
```bash
uv run mcp-repo-mapper
```
## Development
```bash
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