MCP Repo Mapper

io.github.LovRanRanPublished by GitHub account LovRanRanv0.1.0Updated Oct 25, 2026

Deterministic repository structure mapping for onboarding agents.

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

A local MCP server that scans a code repository and gives an assistant its file structure, languages, entry points, frameworks and Python dependency graph.

What you can do
Scan a repository path for files, language breakdown, entry points, Python dependency graph and detected frameworks, and find circular dependencies in the Python import graph, list language counts by file count and bytes, detect frameworks such as FastAPI, Flask, Django, Express and Spring, and rank entry point candidates like Python mains, package start scripts, Dockerfiles and Node indexes, and read a cached JSON scan result through a repo-structure resource after a scan tool has populated it.
When to use it
Useful when an assistant needs a grounded, deterministic map of an unfamiliar local codebase before explaining its architecture, for example during onboarding or dependency review. It complements symbol-level and test-running tools rather than replacing them.
Requirements
Runs as a local process over stdio, installed from the PyPI package mcp-repo-mapper and started with uv. It reads local filesystem paths only and needs no accounts, API keys or environment variables.
Before you install
It reads local repository files, so point it only at code you are comfortable exposing to the assistant session. Dependency analysis is Python-only and static, framework detection is heuristic, and the resource cache is in-memory and process-local, so results may be incomplete.

Installation

In SourceWeft

  1. Open MCP Repo Mapper in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
uv sync --extra dev

Run the server locally:

bash
uv run mcp-repo-mapper

Development

bash
uv run ruff check .uv run mypyuv 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

Source: README.md at commit 5fe2378

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts