Deterministic repository structure mapping for onboarding agents.
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.
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.
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.uv sync --extra dev
Run the server locally:
uv run mcp-repo-mapper
uv run ruff check .
uv run mypy
uv run pytest
Resource reads use a cache populated by tool calls:
scan_repo(path) or another scan-backed tool.repo-structure://{url_hash}.The public resource uses repo-structure://... because URL schemes cannot contain underscores.
ast parsing.MIT
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
uvx mcp-repo-mapperMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-lovranran-mcp-repo-mapper": {
"command": "uvx",
"args": [
"mcp-repo-mapper"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencemcp-repo-mapperpypiMCP Repo Mapper works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.