内容
python-mcp-server
MCP（模型上下文协议）服务器，用于Python代码的确定性静态分析，基于 **LibCST** 和 **Jedi** 构建。
## 动机
该项目灵感来自 [**cobol-mcp-server**](https://github.com/aferreiraguido/cobol-mcp-server) 的确定性分析方法。正如该项目所演示的那样，COBOL可以通过AST（无需AI）进行确定性分析，**python-mcp-server** 将同样的原理应用于Python生态系统：
- **LibCST** — 将源代码解析为具体的AST，保证100%确定性分析（无需猜测）。
- **Jedi**选的类型解析，用于查找定义和引用（按需，无需类路径）。
- 无代码执行 — 仅静态语法分析。
其结果是一个MCP服务器，为任何MCP客户端（OpenCode、Claude Desktop等）提供分析工具。
## 工具
| 工具 | 描述 |
|---|---|
| `load_python_project` | 从本地路径、Git URL或存档（.zip/.tar.gz）加载项目 |
| `unload_python_project` | 从内存中移除已加载的项目 |
| `list_loaded_projects` | 列出当前内存中的所有项目 |
| `project_metadata` | 显示项目元数据（构建、模块、类、函数） |
| `detect_build_system` | 检测构建系统（pip、poetry、pdm、hatch、uv、conda等） |
| `detect_framework` | 检测正在使用的框架/库（Flask、Django、FastAPI、SQLAlchemy等） |
| `list_modules` | 列出项目中的所有Python模块 |
| `list_classes` | 列出项目中的所有类 |
| `list_functions` | 列出项目中的所有函数和方法 |
| `inspect_class` | 深入研究类：基类、方法、装饰器、文档字符串 |
| `inspect_function` | 深入研究函数：签名、参数、正文、装饰器 |
| `list_imports` | 列出项目中的所有导入 |
| `list_decorators` | 列出所有使用的装饰器及其频率 |
| `find_decorated_elements` | 查找使用特定装饰器的类/函数 |
| `class_hierarchy` | 显示继承层次结构（基类和直接子类） |
| `search_source` | 在项目源代码中搜索文本 |
| `multi_file_search` | 同时在所有加载的项目中搜索文本 |
| `find_definition` | 查找符号的定义（需要 `type_resolution=True`） |
| `find_references` | 查找符号的引用 `type_resolution=True`） |
| `get_file_content` | 读取项目中任何文件的原始源内容 |
| `get_source_range` | 返回文件的特定源行和行号 |
| `validate_code_reference` | 检查类、函数或变量是否存在（EXISTS/NOT_FOUND） |
| `resolve_type` | 将类型名称解析为其定义，跟踪项目中的导入 |
| `inspect_module` | 深入研究模块：文档字符串、变量、函数、类、导入 |
| `call_chain` | 静态调用图：显示哪些函数被调用，哪些调用给定的函数 |
| `variable_xref` | 交叉引用变量：显示声明、写入和读取整个项目 |
| `list_enums` | 列出所有枚举类及其成员和值 |
| `module_dependency_graph` | 构建依赖图，显示哪些模块导入哪些 |
| `list_methods_by_return_type` | 查找返回特定类型注解的所有函数/方法 |
| `find_entry_points` | 查找程序的入口点：if __name__、console_scripts、Web应用、CLI应用、异步运行器 |
| `list_api_endpoints` | 列出所有API路由/端点定义（FastAPI、Flask、Starlette、Django）及其路径和处理程序 `extract_environment_dependencies` | 提取环境变量读取、配置文件加载和Pydantic Field（env=...） |
| `list_side_effects` | 按副作用分类函数：FILE_IO、NETWORK、DB、LOG、MUTATION或PURE |
| `analyze_error_handling` | 分析错误处理：自定义异常、引发、try/except模式、裸except |
| `list_public_api` | 显示公共API表面：__all__、__init__.py重新导出、顶级公共定义 |
| `find_test_mapping` | 通过分析测试文件导入，将生产代码映射到测试 |
| `extract_domain_vocabulary` | 提取领域特定词汇 — 关键实体、模块文档字符串、领域术语 |
## 构建.pyz（fat-pyz）
> **重要：** `shiv` 必须安装在用于**构建**轮的Python解释器中。生成的`.pyz`文件然后可以在任何Python 3.8+系统解释器上运行，但**构建本身**必须使用要为其构建轮的Python版本完成。
包布局为/pymcp/`（在 `pyproject.toml` 中通过 `setuptools.packages.find` 声明），因此 `shiv` 在从项目根目录运行时会自动发现它。
### 在venv中构建（推荐）
```bash
# 1. 创建/激活venv（使用任何Python 3.8+解释器）
python -m venv .venv
source .venv/bin/activate
# 2. 安装构建工具
pip install shiv
# 3. 从项目根目录构建fat .pyz
shiv -o python-mcp-server.pyz -e pymcp.main:main -p "/usr/bin/env python3" .
```
> 为了可复制的构建，使用固定的解释器创建venv，例如 `.11 -m venv .venv`。这保证了的轮与目标Python的ABI匹配。
### 为什么这很重要
- `shiv` 通过 `pip` 解析依赖项，它**活动解释器的ABI**（例如Python 3.`cp311`）构建的轮。
- 如果您使用Python 3.14构建并尝试使用系统的Python 3.11运行`.pyz`，您将得到 `zipimport.ZipImportError`，因为捆绑的`cp314`轮不兼容。
- `pyproject.toml固定了 `requires-python>=3.8"`。请确保用于构建`.pyz`的Python与您打算运行它的主要版本相同。
### 烟雾测试
```bash
./python-mcp-server.pyz # 在stdio上启动MCP服务器并记录到 /tmp/python_mcp_server.log
```
生成的`.pyz`文件是独立的 — 它包含所有依赖项（`mcp`、`libcst`、`jedi`、`GitPython`）并且适用于任何3.8+解释器。
您也可以直接运行已入口点：
```bash
python-mcp-server
```
## OpenCode 配置
在您的 `opencode.json` 或 `opencode.yml` 中添加以下内容：
```json
{
"mcpServers": {
"python-mcp-server": "command": "python",
"args": ["python-server.pyz"],
"transport": "stdio"
}
}
```
或如果已安装为包：
```json
{
"mcpServers": {
"python-mcp-server": {
"command": "python-mcp-server",
"transport": "stdio"
}
}
}
```
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---| `PYMCP_LOG_FILE` | `/tmp/python_mcp_server.log` | 日志文件路径 |
| `PYM_LEVEL` | `INFO` | 日志级别（DEBUG、WARNING、ERROR） |
## 依赖项
- >= 1.0.0`
- `libcst1.0.0`
- `jedi >= 0.0`
- `GitPython >= 3.1.0`
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
