# MCP Repo Mapper

> Deterministic repository structure mapping for onboarding agents.

- **Type:** MCP server
- **Install:** `agentstack add mcp-lovranran-mcp-repo-mapper`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [LovRanRan](https://agentstack.voostack.com/s/lovranran)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [LovRanRan](https://github.com/LovRanRan)
- **Source:** https://github.com/LovRanRan/mcp-repo-mapper

## Install

```sh
agentstack add mcp-lovranran-mcp-repo-mapper
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [LovRanRan](https://github.com/LovRanRan)
- **Source:** [LovRanRan/mcp-repo-mapper](https://github.com/LovRanRan/mcp-repo-mapper)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-lovranran-mcp-repo-mapper
- Seller: https://agentstack.voostack.com/s/lovranran
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.