# 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