Skip to content
Conduit

mcp server

mcp-repo-mapper

LovRanRan/mcp-repo-mappercommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "mcp-repo-mapper": {
      "command": "uvx",
      "args": [
        "mcp-repo-mapper"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 17, 2026

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

↑↓ navigate openesc close