Code Understanding MCP Server

⚠️ 平台支持说明

此 MCP 服务已在 macOS 和 Linux 上测试。Windows 支持目前尚未验证（尚未测试）。

如果你尝试在 Windows 上使用并遇到问题，请提交 issue，以便我们改进跨平台支持。

代码理解 MCP 服务

一个旨在理解代码库并为 AI 编码助手提供智能上下文的 MCP（模型上下文协议）服务。此服务可处理本地和远程 GitHub 仓库，并支持符合标准 MCP 规范的操作。

🤖 AI 助手安装

请 AI 编码助手协助你安装此服务！ 将 Setup Assistant Prompt 的内容复制并粘贴给你的 AI 助手（Claude、ChatGPT、Cursor 等），它会引导你完成整个安装过程。

功能

• 克隆并分析 GitHub 仓库或本地代码库
• 获取仓库结构和文件组织情况
• 根据复杂度指标和代码结构识别关键文件
• 生成详细的仓库地图，展示：
  • 函数签名及其关系
  • 类定义及层级结构
  • 代码结构和依赖项
• 检索并分析仓库文档
• 将分析范围限定到特定文件或目录
• 通过刷新使分析与仓库变更保持同步

快速开始：MCP 客户端配置

前提条件

必需：安装 uv

此服务需要 uv，这是一款现代 Python 包管理器。如果你尚未安装 uv：

# Install UV (macOS/Linux)
curl -sSf https://astral.sh/uv/install.sh | sh

# Install UV (Windows PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

如需了解其他安装方式，请访问 uv 官方安装指南：astral.sh/uv。

安装方式

方式 1：使用 uvx 直接运行（推荐）

# Run directly without installing a global binary
uvx code-understanding-mcp-server

每次运行时，都会在由 UV 管理的隔离环境中启动服务。

方式 2：安装到虚拟环境（可选）

如果你希望将二进制文件持久安装在专用虚拟环境中：

# Create a dedicated virtual environment
uv venv ~/.venvs/mcp-code-understanding

# Activate it (macOS/Linux)
source ~/.venvs/mcp-code-understanding/bin/activate

# Install the package into the venv
uv pip install code-understanding-mcp-server

# Run the server
code-understanding-mcp-server

验证安装

根据你选择的方式：

# Method 1 (uvx): runs via uvx; no persistent binary is installed
uvx --version

# Method 2 (venv install): verify the binary inside your venv
which code-understanding-mcp-server
# Expected output example: /Users/username/.venvs/mcp-code-understanding/bin/code-understanding-mcp-server

配置 MCP 客户端

为你的 MCP 客户端使用以下任一配置：

{
  "mcpServers": {
    "code-understanding": {
      "command": "uvx",
      "args": [
        "code-understanding-mcp-server"
      ]
    }
  }
}

或者，如果你安装到了虚拟环境，请直接指向该环境中的二进制文件：

{
  "mcpServers": {
    "code-understanding": {
      "command": "/path/to/.venvs/mcp-code-understanding/bin/code-understanding-mcp-server",
      "args": []
    }
  }
}

为什么使用此 MCP 服务？

MCP 代码理解服务

价值主张

MCP 代码理解服务赋予 AI 助手全面理解代码的能力，使其能够针对软件开发任务提供更准确、更贴合上下文且更实用的帮助。通过在代码仓库与 AI 系统之间建立语义桥梁，此服务大幅减少了代码探索、分析和实现指导所需的时间与阻碍。

常见用例

参考仓库分析

• 检查外部仓库（库、依赖项等），为当前开发提供参考
• 在开源项目中查找实现模式和示例
• 当文档不足时，了解特定库的内部工作方式
• 比较类似项目中的实现方法
• 从高质量代码库中识别最佳实践

知识提取与文档编写

• 为文档不完善的代码库生成完整文档
• 创建架构概览和组件关系图
• 为开发者入职制定循序渐进的学习路径
• 提取代码中蕴含的业务逻辑和领域知识
• 识别并记录系统集成点和依赖项

代码库评估与改进

• 分析技术债务并确定重构工作的优先级
• 识别安全漏洞和合规性问题
• 评估测试覆盖率和质量
• 检测无用代码、重复逻辑和优化机会
• 根据设计模式和架构原则评估实现方式

遗留系统理解

• 从文档极少的系统中恢复知识
• 通过了解系统边界来支持迁移规划
• 在进行更改前分析复杂依赖关系
• 跨多个组件追踪功能实现
• 理解历史设计决策及其原因

跨项目知识迁移

• 将一个项目中的模式应用到另一个项目
• 弥合负责相关系统的团队之间的知识差距
• 识别多个项目之间可复用的组件
• 了解不同团队在实现方法上的差异
• 促进分布式开发环境中的知识共享

如需了解 MCP Code Understanding Server 在实际场景中的详细用法示例，请参阅我们的示例场景文档。其中包含以下内容的分步演示：

• 加速开发者熟悉复杂代码库
• 规划并执行 API 迁移
• 开展安全漏洞评估

工作原理

MCP Code Understanding Server 通过一系列分析步骤处理代码仓库：

1. 克隆代码仓库：服务将目标代码仓库克隆到缓存中
2. 结构分析：分析目录、文件及其组织方式
3. 关键文件识别：确定在结构上具有重要意义的组件
4. 文档检索：收集所有文档文件
5. 语义映射：创建详细的映射，展示各组件之间的关系
6. 内容分析：根据需要检查特定文件，以便深入理解

AI 助手通过针对每个分析阶段发出定向请求来与服务集成，从而全面理解代码库，并据此回答用户的具体问题和满足其需求。

AI 助手的推荐工作流

处理代码仓库时，AI 助手应遵循以下工作流，以获得最佳效果：

1. 先检查缓存：使用 list_cached_repository_branches 查看代码仓库是否已缓存

   • 如果已缓存：跳到第 3 步（刷新）
   • 如果未缓存：继续第 2 步

2. 查找分支名称：许多代码仓库使用 "master"、"develop" 或其他名称，而非 "main"

   • 使用 list_remote_branches 查找可用分支
   • 在克隆前确定正确的默认分支

3. 分析前刷新：缓存的代码仓库会随着时间推移变得过时

   • 在进行任何分析前，使用 refresh_repo 拉取最新更改
   • 这样可以确保分析基于当前代码，而非过时的缓存

4. 执行分析：代码仓库更新后，使用分析工具

   • 使用 get_source_repo_map 获取代码结构
   • 使用 get_repo_critical_files 识别关键组件
   • 使用 get_repo_documentation 查找文档

此工作流可避免常见问题，例如因分支名称错误导致克隆失败、重复尝试克隆，以及基于过时缓存数据进行分析。

大型代码库的设计考量

即使面对企业级规模的代码库，服务也会采用多种策略来保持性能和易用性：

• 异步处理：在后台线程中克隆和分析代码库，在深入分析持续进行的同时提供即时反馈
• 渐进式分析：先进行快速初步分析，让你立即开始交互，并随着时间推移逐步建立更详细的理解
• 范围控制：通过 max_tokens、files 和 directories 参数，可针对感兴趣的特定区域进行分析
• 阈值管理：自动检测代码库大小，并为分析策略提供适当的指导
• 层级化理解：首先分析代码库结构，从而能够智能地优先处理关键组件，进行更深入的语义分析

这些设计选择确保开发者能够立即开始处理大型代码库，同时系统在后台逐步加深理解，从而在分析深度和响应速度之间实现最佳平衡。

GitHub 身份验证（可选）

如果需要访问私有代码库，或希望避免受到 GitHub API 速率限制，可将 GitHub 令牌添加到配置中：

{
  "mcpServers": {
    "code-understanding": {
      "command": "/path/to/code-understanding-mcp-server",
      "args": [],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token-here"
      }
    }
  }
}

高级配置选项

对于高级用户，服务支持以下配置选项：

{
  "mcpServers": {
    "code-understanding": {
      "command": "/path/to/code-understanding-mcp-server",
      "args": [
        "--cache-dir", "~/custom-cache-dir",     // Override repository cache location
        "--max-cached-repos", "20",              // Override maximum number of cached repos
        "--transport", "stdio",                  // Transport type (stdio or sse)
        "--port", "3001"                         // Port for SSE transport (only used with sse)
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token-here"
      }
    }
  }
}

可用选项：

• --cache-dir：覆盖代码库缓存目录的位置（默认值：~/.cache/mcp-code-understanding）
• --max-cached-repos：设置缓存代码库的最大数量（默认值：10）
• --transport：选择传输类型（stdio 或 sse，默认值：stdio）
• --port：设置 SSE 传输的端口（默认值：3001，仅在使用 sse 传输时生效）

平台特定说明

macOS

• 使用 uvx 时，不会安装持久化二进制文件，也无需更改 PATH
• 使用虚拟环境时，请确保已激活该环境，或引用 venv 二进制文件的完整路径

Linux

• 使用 uvx 时，不会安装持久化二进制文件，也无需更改 PATH
• 使用虚拟环境时，可选择添加辅助别名，或在使用前激活 venv

Windows

• 目前尚不支持——计划在未来版本中支持 Windows
• 目前正在进行开发，以实现 Windows 兼容性

故障排除

依赖冲突

如果使用 uvx 时遇到依赖冲突，请创建隔离环境并在其中安装软件包：

# Create a dedicated virtual environment
uv venv ~/.venvs/mcp-code-understanding

# Activate it (macOS/Linux)
source ~/.venvs/mcp-code-understanding/bin/activate

# Install the package
uv pip install code-understanding-mcp-server

# Run the server
code-understanding-mcp-server

找不到二进制文件

如果找不到已安装的二进制文件：

1. 检查安装位置：

   # macOS/Linux
   find ~/.local -name "code-understanding-mcp-server" 2>/dev/null
   

2. 如有需要，将其添加到 PATH：

   # Add to ~/.bashrc, ~/.zshrc, or appropriate shell config
   export PATH="$HOME/.local/bin:$PATH"
   

3. 如果未激活 venv，请在 MCP 配置中使用 venv 二进制文件的绝对路径

服务配置

服务使用 config.yaml 文件进行基础配置。首次运行服务时，会在标准配置目录（~/.config/mcp-code-understanding/config.yaml）中自动创建此文件。你也可以在当前目录中放置 config.yaml 文件，以覆盖默认配置。

默认配置结构如下：

name: "Code Understanding Server"
log_level: "debug"

repository:
  cache_dir: "~/.cache/mcp-code-understanding"
  max_cached_repos: 10

documentation:
  include_tags:
    - markdown
    - rst
    - adoc
  include_extensions:
    - .md
    - .markdown
    - .rst
    - .txt
    - .adoc
    - .ipynb
  format_mapping:
    tag:markdown: markdown
    tag:rst: restructuredtext
    tag:adoc: asciidoc
    ext:.md: markdown
    ext:.markdown: markdown
    ext:.rst: restructuredtext
    ext:.txt: plaintext
    ext:.adoc: asciidoc
    ext:.ipynb: jupyter
  category_patterns:
    readme: 
      - readme
    api: 
      - api
    documentation:
      - docs
      - documentation
    examples:
      - examples
      - sample

面向开发者

前置条件

• Python 3.11 或 3.12：开发和使用均需要

  # Verify your Python version
  python --version
  # or
  python3 --version
  

• UV 包管理器：现代 Python 软件包安装程序

  # Install UV
  curl -sSf https://astral.sh/uv/install.sh | sh
  

开发环境设置

如需参与贡献或在本地运行此项目：

# 1. Clone the repository
git clone https://github.com/yourusername/mcp-code-understanding.git
cd mcp-code-understanding

# 2. Create virtual environment
uv venv

# 3. Activate the virtual environment
#    Choose the command appropriate for your operating system and shell:

#    Linux/macOS (bash/zsh):
source .venv/bin/activate

#    Windows (Command Prompt - cmd.exe):
.venv\\Scripts\\activate.bat

#    Windows (PowerShell):
#    Note: You might need to adjust your execution policy first.
#    Run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
.venv\\Scripts\\Activate.ps1

# 4. Install dependencies (editable mode with dev extras)
#    (Ensure your virtual environment is activated first!)
uv pip install -e ".[dev]"

# 5. Set up pre-commit hooks
pre-commit install

# 6. Run tests
uv run pytest

# 7. Test the server using MCP inspector
# Without GitHub authentication:
uv run mcp dev src/code_understanding/mcp/server/app.py

# With GitHub authentication (for testing private repos):
GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here uv run mcp dev src/code_understanding/mcp/server/app.py

这会启动一个交互式控制台，你可以直接在其中测试所有 MCP 服务端点。

开发工具

安装开发附加依赖（.[dev]）后，可使用以下开发工具：

运行带覆盖率的测试：

uv run pytest

格式化代码（使用 black 和 isort）：

# Format with black
uv run black .

# Sort imports
uv run isort .

使用 mypy 进行类型检查：

uv run mypy .

所有工具均通过 pyproject.toml 配置，设置已针对本项目进行了优化。

发布到 PyPI

准备好向 PyPI 发布新版本时，请按以下步骤操作：

1. 更新 pyproject.toml 中的版本号：

   # Edit pyproject.toml and change the version field
   # For example: version = "0.1.1"
   

2. 清理之前的构建产物：

   # Remove previous distribution packages and build directories
   rm -rf dist/ 2>/dev/null || true
   rm -rf build/ 2>/dev/null || true
   rm -rf src/*.egg-info/ 2>/dev/null || true
   

3. 构建分发包：

   uv run python -m build
   

4. 验证构建的包：

   ls dist/
   

5. 上传到 PyPI（如果不确定，请先使用 TestPyPI）：

   # Install twine if you haven't already
   uv pip install twine
   
   # For PyPI release:
   uv run python -m twine upload dist/*
   

你需要配置 PyPI 凭据，否则系统会在上传期间提示你输入凭据。

版本历史

v0.1.6（最新）

• 依赖项修复：明确固定 configargparse==1.7，以解决 PyPI 中被撤回的版本导致的安装问题
• 通过避免依赖项解析失败，确保使用 uvx 和其他包管理器时能够顺利安装
• 未更改服务的功能

许可证

MIT