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
Metadata
Release files for mcp-repo-mapper 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_repo_mapper-0.1.0.tar.gz | 95.9 kB | Without provenance | Details for mcp_repo_mapper-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_repo_mapper-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for mcp_repo_mapper-0.1.0-py3-none-any.whl |
Total release size: 104.3 kB
Release files / mcp_repo_mapper-0.1.0.tar.gz
| Download URL | mcp_repo_mapper-0.1.0.tar.gz |
|---|---|
| Size | 95.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9112cf8a7567c459153d5260c079eb5e672cc8312d758bbbf8f06b63bff64d27
|
|
BLAKE2b-256 checksum How to use checksums |
6712433ffdb03b8ee443932480bcac8c8eb80cea7bb96deb0e03d133ed2277f4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / mcp_repo_mapper-0.1.0-py3-none-any.whl
| Download URL | mcp_repo_mapper-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d49403095cb50b3e5d8049949ac45da0935173831d65ae2079546d0b8033d6ac
|
|
BLAKE2b-256 checksum How to use checksums |
1c7205a73868862e5f149454814d507037dfd0a1660802bdae2517734bb4b013
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for mcp-repo-mapper 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.