项目简介

python-mcp 是一个基于 Model Context Protocol (MCP) 构建的 Python 代码探索服务器。它通过分析 Python 代码的导入关系，提取目标文件及其依赖的代码片段，并整合项目文档（如 README 文件），为大型语言模型（LLM）提供丰富的代码上下文信息，从而提升 LLM 在代码理解、分析和生成等任务中的能力。该服务器轻量级且易于集成，无需复杂的 Agent 系统，可以方便地嵌入到各种 Python 应用中。

主要功能点

代码关系发现：分析 Python 文件之间的导入关系，识别代码依赖。
智能代码抽取：仅提取与目标文件相关的代码片段，避免超出 LLM 的 Token 限制。
目录上下文：自动包含同一目录下的文件，提供更全面的上下文信息。
文档包含：始终包含 README 文件（及其变体），提供项目级别的文档说明。
LLM 友好格式：以结构化的 JSON 格式返回代码信息，方便 LLM 解析和利用。
MCP 协议支持：完全兼容 Model Context Protocol JSON-RPC 标准，可与任何 MCP 客户端集成。
提供 'get_python_code' 工具：
- 分析目标 Python 文件及其导入的模块、类和函数。
- 返回目标文件的完整代码。
- 包含所有引用对象的代码。
- 添加同一目录下的上下文文件。
- 尊重 Token 限制，防止 LLM 处理过载。

安装步骤

克隆仓库

git clone https://github.com/hesiod-au/python-mcp.git
cd python-mcp

创建并激活虚拟环境

python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate  # Windows

安装依赖

pip install -r requirements.txt

配置环境变量

复制 '.env.example' 文件为 '.env'，并根据需要修改 'TOKEN_LIMIT' 环境变量。

TOKEN_LIMIT=8000  # 代码提取的 Token 限制

服务器配置

要将 python-mcp 服务器配置到 MCP 客户端（例如 Codeium Windsurf），您需要在客户端的 MCP 配置文件中添加以下 JSON 配置。请根据您的实际安装路径进行调整。

{
  "mcpServers": {
    "python-code-explorer": {  // 服务器名称，可以自定义
      "command": "python",    // 启动服务器的命令，这里使用 python 解释器
      "args": [              // 启动参数，指向服务器脚本 server.py 的绝对路径
        "/path/to/python-mcp/server.py"  // 请替换为 server.py 文件的实际绝对路径
      ],
      "env": {                // 环境变量
        "TOKEN_LIMIT": "8000"  // 可选，设置 Token 限制，与 .env 文件中的 TOKEN_LIMIT 作用相同
      }
    }
  }
}

请注意：

将 '/path/to/python-mcp/server.py' 替换为 'server.py' 文件在您系统上的绝对路径。您可以使用 'pwd' (Linux/macOS) 或 'Get-Location' (PowerShell) 命令获取当前目录，然后拼接上相对路径 'server.py'。
'server name' (例如 "python-code-explorer") 可以自定义，用于在 MCP 客户端中标识该服务器。
'TOKEN_LIMIT' 环境变量是可选的，您可以在 '.env' 文件或客户端配置中设置。

基本使用方法

启动 MCP 服务器

在项目根目录下，运行以下命令启动服务器：

python run_server.py

您可以使用 '--name' 参数自定义服务器名称，例如：

python run_server.py --name "My Code Explorer"

或者使用 '--env-file' 参数指定不同的 '.env' 配置文件，例如：

python run_server.py --env-file .env.production

在 MCP 客户端中使用

配置好 MCP 客户端后，客户端将自动连接到 python-mcp 服务器。您可以使用客户端提供的工具（通常在代码编辑器的上下文菜单或命令面板中）调用 'get_python_code' 工具，并指定要分析的 Python 文件路径。服务器将返回包含目标文件及其相关代码的结构化信息，供 LLM 使用。

具体使用方式请参考您使用的 MCP 客户端的文档。例如，在 Codeium Windsurf 中，您可能需要在编辑器中右键点击 Python 文件，选择 "Ask Windsurf"，然后在 Windsurf 界面中使用配置好的 "python-code-explorer" 服务器进行代码分析。
通过 MCP 客户端 SDK 编程访问

仓库中提供了 'examples/mcp_client_example.py' 示例脚本，演示了如何使用 MCP Python SDK 编程连接和调用 python-mcp 服务器。您可以参考该示例，编写自己的 MCP 客户端程序，实现更灵活的代码分析和集成。

运行示例客户端：
```
python examples/mcp_client_example.py [optional_target_file.py]
```
您可以选择性地提供一个 Python 文件路径作为参数，让客户端分析该文件。

添加更多工具和资源

python-mcp 基于 MCP Python SDK 构建，易于扩展。您可以参考 'server.py' 文件中的示例，通过 '@mcp.tool()' 和 '@mcp.resource()' 装饰器，向服务器添加自定义的工具和资源，扩展其功能。

关键词