MCP Repo Mapper

mcp-repo-mapper

mcp-repo-mapper 是一个用于确定性映射代码仓库结构的 FastMCP 服务。它会扫描本地代码库，并提供文件结构、语言数量、Python 导入依赖、循环依赖检测、框架检测、入口点候选项，以及缓存的代码仓库结构资源。

该服务不会调用大模型，也不会执行用户代码。它旨在为 wayfinder 等代码库入门 Agent 提供有依据的结构信息。

代码库入门技术栈

mcp-repo-mapper 是 Project 6 wayfinder（一个代码库入门 Agent）的三服务 MCP 工具栈中的结构层。

• mcp-repo-mapper 用于映射代码仓库结构、语言、入口点、框架证据和 Python 依赖关系。
• mcp-ast-explorer 提供基于符号的 Python 定义、签名、引用、调用链和类层次结构查询。
• mcp-test-runner 运行本地 pytest/Jest 检查并汇总覆盖率，以便 Agent 根据执行结果验证结论。

在 wayfinder 中，此服务会在开始语义解释或测试验证之前，为架构映射步骤提供信息。

功能

• scan_repo(path) 返回包含文件、语言分布、入口点、Python 依赖图和检测到的框架的类型化代码仓库扫描结果。
• find_circular_deps(path) 返回静态依赖图中的循环依赖。
• language_breakdown(path) 按文件数量和字节数返回语言统计。
• detect_framework(path) 使用基于注册表的标记检测 FastAPI、Flask、Django、Express 和 Spring。
• find_entry_points(path) 返回经过排序的入口点候选项，例如 Python 主程序、FastAPI 应用、软件包启动脚本、Dockerfile 和 Node 索引文件。
• repo-structure://{url_hash} 返回工具调用填充缓存后保存的 JSON 扫描结果。

安装

uv sync --extra dev

在本地运行服务：

uv run mcp-repo-mapper

开发

uv run ruff check .
uv run mypy
uv run pytest

资源流程

资源读取使用由工具调用填充的缓存：

1. 调用 scan_repo(path) 或其他基于扫描的工具。
2. 使用相同路径计算代码仓库哈希值。
3. 读取 repo-structure://{url_hash}。

公开资源使用 repo-structure://...，因为 URL 方案不能包含下划线。

范围与限制

• 目前仅支持基于静态 ast 解析的 Python 依赖图。
• 导入图解析只记录扫描代码仓库中存在的模块。
• 框架检测采用启发式标记匹配，并非完整的构建系统分析。
• 资源缓存位于内存中，且仅限当前进程使用。
• 服务仅扫描本地文件系统路径。

许可证

MIT