okeefeco/pyeye-mcp

# PyEye 👁️ ## PyEye Server [](https://github.com/okeefeco/pyeye-mcp/actions/workflows/ci.yml) [](https://codecov.io/gh/okeefeco/pyeye-mcp) [](https://www.python.org/downloads/) [](https://github.com/psf/black) [](https://github.com/astral-sh/ruff) [](https://github.com/pre-commit/pre-commit) 一个可扩展的 MCP (Model Context Protocol) 服务器，为 Claude 等 AI 助手提供智能的 Python 代码分析、导航和理解能力。 ## 特性 - 🔍 **语义代码导航**：使用 Jedi 查找符号、跳转到定义、查找引用 - 📊 **模块与包分析**：列出包/模块，分析依赖关系，检测循环导入 - 🏗️ **多项目支持**：同时分析多个项目和依赖项 - 📦 **Namespace Packages**：处理分布在多个仓库中的包 - 📝 **独立脚本**：将 notebook、脚本和示例与正式包一起分析 - 🔄 **自动更新**：通过智能缓存失效自动检测并反映文件更改 - ⚙️ **配置系统**：通过文件、环境变量或自动发现进行灵活配置 - 🔌 **可扩展插件系统**：针对特定框架的分析器（Pydantic, Django, Flask） - 🚀 **快速与缓存**：具备 LRU 驱逐机制和性能优化的智能缓存 - 🎯 **类型感知**：全面理解 Python 类型提示和注解 - 📈 **性能监控**：内置指标跟踪，提供 p50/p95/p99 延迟 - 🛡️ **输入验证**：安全的参数验证和路径检查 - 🤖 **开发自动化**：发布自动化、内部指标测试和 worktree 安全保障 ## 安装 PyEye 可以通过三种方式安装：作为 Claude Code 插件（零配置）、安装到项目的 venv 中，或全局安装。 ### 选项 0：Claude Code 插件（零配置） 当 PyEye 作为 Claude Code 插件安装时，依赖项会在首次会话启动时自动安装到用户专属的 venv 中 —— 无需手动执行 `pip install`。 - **首次会话启动**：`SessionStart` hook 会对插件检出运行 `uv sync --no-dev --frozen`，venv 构建于 `${CLAUDE_PLUGIN_DATA}/.venv`（通常为 `~/.claude/plugins/data//.venv`）。 - **后续会话**：该 hook 会将插件检出中的 `uv.lock` 与 `${CLAUDE_PLUGIN_DATA}` 中上次安装的副本进行比较，如果 lockfile 未更改，则静默无操作。 - **要求**：`uv` 必须位于您的 `PATH` 中。请参阅 [uv 安装指南](https://docs.astral.sh/uv/getting-started/installation/)。 安装 hook 和 MCP 服务器调用均使用 `uv run`，因此无需针对操作系统进行特定配置，即可在 Linux、macOS 和 Windows 上运行。 ### 选项 1：项目特定安装（推荐） 直接安装到您的 Python 项目的虚拟环境中： ``` # 激活项目的 virtual environment source /path/to/your/project/venv/bin/activate # 从 PyPI 安装 pip install pyeye-mcp # 或从源码安装 git clone https://github.com/okeefeco/pyeye-mcp.git pip install -e ./pyeye-mcp ``` 然后在您的项目根目录中创建一个 `.mcp.json` 文件： ``` { "mcpServers": { "pyeye": { "type": "stdio", "command": "python", "args": ["-m", "pyeye.mcp"], "env": {} } } } ``` 这样，MCP 服务器将使用您项目的环境，并能够访问项目的所有依赖项。 ### 选项 2：全局安装 用于分析多个项目或配合全局 Python 使用： ``` # 使用 pipx 全局安装（推荐用于隔离） pipx install pyeye-mcp # 或使用 pip 安装 pip install --user pyeye-mcp # 或从源码安装 git clone https://github.com/okeefeco/pyeye-mcp.git cd pyeye-mcp pip install --user . ``` #### 配合 Claude Code 使用（全局） ``` # 全局添加 MCP server（在所有项目中可用） claude mcp add pyeye -s user -- python -m pyeye.mcp # 验证它是否已连接 claude mcp list ``` ### 配合 Claude Desktop 使用 添加到您的 Claude Desktop 配置中（macOS 上为 `~/Library/Application Support/Claude/claude_desktop_config.json`）： ``` { "mcpServers": { "pyeye": { "command": "python", "args": ["-m", "pyeye.mcp"], "env": {} } } } ``` 注意：如有需要，请使用 Python 的完整路径（例如 `/usr/local/bin/python3` 或 `C:\\Python311\\python.exe`）。 ### 配合 GitHub Copilot 使用 (VS Code) 自 2025 年起，GitHub Copilot 在 VS Code、JetBrains、Eclipse 和 Xcode 中已全面支持 MCP。请按照以下步骤将此 PyEye 服务器与 GitHub Copilot 配合使用： #### 前置条件 - **GitHub Copilot Business 或 Enterprise 订阅**（支持 MCP 所必需） - **VS Code 1.102 或更高版本**（MCP 支持已正式发布） - **组织 MCP 策略**已由您的管理员启用 #### 第 1 步：在您的组织中启用 MCP 您的 GitHub Copilot 管理员需要启用 MCP 服务器策略： 1. 在 GitHub 上前往您的组织设置 2. 导航到 **Copilot** → **Policies** 3. 启用 **"MCP servers in Copilot"** 策略 4. 保存更改 #### 第 2 步：安装 MCP 服务器 在您的项目中或全局安装 PyEye 服务器： ``` # 选项 A：在项目的 virtual environment 中安装（推荐） pip install pyeye-mcp # 选项 B：使用 pipx 全局安装 pipx install pyeye-mcp # 选项 C：从源码安装 git clone https://github.com/okeefeco/pyeye-mcp.git pip install -e ./pyeye-mcp ``` #### 第 3 步：配置 VS Code 将 MCP 服务器配置添加到您的 VS Code 设置中： **用户设置**（适用于所有项目）： ``` // File: ~/.config/Code/User/settings.json (Linux/Mac) // or %APPDATA%\Code\User\settings.json (Windows) { "github.copilot.chat.mcpServers": { "pyeye": { "command": "python", "args": ["-m", "pyeye.mcp"], "env": {} } } } ``` **工作区设置**（特定于项目）： ``` // File: .vscode/settings.json in your project root { "github.copilot.chat.mcpServers": { "pyeye": { "command": "${workspaceFolder}/.venv/bin/python", "args": ["-m", "pyeye.mcp"], "env": { "PYTHONPATH": "${workspaceFolder}" } } } } ``` #### 第 4 步：验证连接 1. 在您的 Python 项目中打开 VS Code 2. 打开 GitHub Copilot Chat 面板 3. 输入：`@mcp list` 查看可用的 MCP 服务器 4. 您应该能在列表中看到 `pyeye` 5. 使用以下命令测试：`@mcp pyeye find_symbol MyClass` #### 故障排除 **MCP 不可用：** - 确保您使用的是 Copilot Business/Enterprise（而非 Free/Pro） - 检查您的组织管理员是否已启用 MCP 策略 - 将 VS Code 更新至 1.102 或更高版本 **服务器未连接：** - 验证配置中的 Python 路径是否正确 - 检查是否已安装 `pyeye`：`python -m pyeye.mcp --help` - 在 VS Code 输出面板 → GitHub Copilot Logs 中查找错误 **导入错误：** - 如果使用虚拟环境，请确保路径指向 venv 中的 Python - 如有必要，请将 `PYTHONPATH` 添加到 env 配置中 #### 其他 IDE **JetBrains IDE**（IntelliJ, PyCharm 等）： - MCP 支持已正式发布 - 在 Settings → Tools → GitHub Copilot → MCP Servers 中配置 **Visual Studio**： - MCP 支持处于预览阶段 - 在 Tools → Options → GitHub Copilot → MCP Servers 中配置 **Eclipse 和 Xcode**： - MCP 支持已正式发布 - 有关配置，请参阅 IDE 相关文档 ## 配置 可以配置服务器以分析其他位置的包。在您的项目中创建一个 `.pyeye.json` 文件： ``` { "packages": [ "../my-shared-library", "~/repos/company-utils", "/absolute/path/to/package" ], "namespaces": { "mycompany": [ "~/repos/mycompany-auth", "~/repos/mycompany-api" ] } } ``` ### 配置方法 配置按以下顺序加载（后者会覆盖前者）： 1. **全局配置**：`~/.config/pyeye/config.json` 或 `~/.pyeye.json` - 用户默认配置 2. **项目配置**：项目根目录中的 `.pyeye.json` 或 `pyproject.toml` 中的 `[tool.pyeye]` 3. **覆盖文件**：`.pyeye.override.json` - 本地开发覆盖（被 git 忽略） 4. **自动发现**：如果未配置任何包，则自动检测源码布局和同级包 ### 使用覆盖文件 覆盖文件非常适合用于不应提交到版本控制的本地开发配置： ``` // .pyeye.override.json (git-ignored) { "packages": [ "../my-local-dev-package", "~/dev/experimental" ], "namespaces": { "company.feature": ["/home/user/feature-branch"] } } ``` ### 性能设置 所有对性能至关重要的设置均可通过环境变量进行配置，以便针对您的特定工作负载进行调优： | 环境变量 | 默认值 | 描述 | 有效范围 | |---------------------|---------|-------------|-------------| | `PYEYE_MAX_PROJECTS` | 10 | 内存中最大的项目数 | 1-1000 | | `PYEYE_CACHE_TTL` | 300 | 缓存生存时间（以秒为单位） | 0-86400 (24h) | | `PYEYE_WATCHER_DEBOUNCE` | 0.5 | 文件监视器防抖延迟（以秒为单位） | 0.0-10.0 | | `PYEYE_MAX_FILE_SIZE` | 1048576 | 要分析的最大文件大小（字节） | 1KB-100MB | | `PYEYE_MAX_WORKERS` | 4 | 最大并发分析工作线程数 | 1-32 | | `PYEYE_ANALYSIS_TIMEOUT` | 30.0 | 分析超时时间（以秒为单位） | 1.0-300.0 | | `PYEYE_ENABLE_MEMORY_PROFILING` | false | 启用内存分析 | true/false | | `PYEYE_ENABLE_PERFORMANCE_METRICS` | false | 启用性能指标 | true/false | | **连接池** | | **优化多项目工作流** | | | `PYEYE_ENABLE_CONNECTION_POOLING` | true | 为多个项目启用连接池 | true/false | | `PYEYE_POOL_MAX_CONNECTIONS` | 10 | 最大池化项目连接数 | 1-100 | | `PYEYE_POOL_TTL` | 3600 | 连接生存时间（以秒为单位） | 60-86400 | #### 性能调优示例 **具有稳定文件的大型代码库：** ``` export PYEYE_MAX_PROJECTS=50 # Handle more projects export PYEYE_CACHE_TTL=1800 # 30 minute cache export PYEYE_WATCHER_DEBOUNCE=2.0 # Less frequent updates ``` **具有频繁更改的活跃开发：** ``` export PYEYE_MAX_PROJECTS=5 # Fewer projects, faster switching export PYEYE_CACHE_TTL=60 # 1 minute cache export PYEYE_WATCHER_DEBOUNCE=0.1 # Near real-time updates ``` **内存受限环境：** ``` export PYEYE_MAX_PROJECTS=3 # Minimal project cache export PYEYE_MAX_FILE_SIZE=524288 # 512KB file limit export PYEYE_MAX_WORKERS=2 # Fewer workers ``` 此文件会被 git 自动忽略，并优先于所有其他配置源生效。 ### 自动检测源码布局 PyEye 会自动从 `pyproject.toml` 的构建后端元数据中检测源码布局，支持使用 `src/` 目录模式的项目。这适用于多个构建后端： **Setuptools：** ``` [tool.setuptools.packages.find] where = ["src"] ``` **Poetry：** ``` [[tool.poetry.packages]] include = "mypackage" from = "src" ``` **Hatch：** ``` [tool.hatch.build.targets.wheel] sources = ["src"] ``` **PDM：** ``` [tool.pdm.build] package-dir = "src" ``` 如果在 `pyproject.toml` 中未找到配置，PyEye 还将检查是否存在包含 Python 包的 `src/` 目录，并自动将其添加到包路径中。 **注意：** 显式的 `[tool.pyeye]` 配置始终优先于自动检测的布局。 ## 工作流资源 pyeye 将工作流指南作为 MCP 资源提供，以帮助 AI 代理和用户发现如何有效地将工具用于常见的多步骤任务。 ### 发现工作流 列出可用的工作流： ``` "List pyeye workflow resources" ``` 或使用 Claude Code 的 MCP 工具： ``` ListMcpResourcesTool(server="pyeye") ``` ### 使用工作流 **按需（试用）：** ``` "Use pyeye find-references workflow" "Use pyeye refactoring workflow" "Use pyeye code-understanding workflow" "Use pyeye dependency-analysis workflow" "Use pyeye code-review-standards workflow" "Use pyeye code-review-security workflow" "Use pyeye code-review-pr workflow" ``` **永久（采纳）：** ``` "Add pyeye find-references workflow to my CLAUDE.md" ``` AI 将获取该工作流，将其添加到您的上下文文件中，并在未来的会话中自动遵循它。 ### 可用工作流 1. **find-references** - 查找所有的类/函数引用，包括包以及 notebook/脚本 - 解决 `find_references` 仅适用于包的限制（issue #236） - 结合 `get_type_info`、`find_references` 和 `Grep` 实现完整覆盖 2. **refactoring** - 包含影响分析的安全重构 - 在修改代码之前分析子类、引用和依赖项 - 包含变更计划和验证步骤 - 通过全面分析防止破坏性更改 3. **code-understanding** - 理解不熟悉的代码结构 - 从“这是什么？”到“它是如何工作的？”进行系统性探索 - 涵盖符号定位、检查、层次结构、执行流程和使用模式 - 从基础到深度集成知识的渐进式理解 4. **dependency-analysis** - 分析模块依赖关系和架构 - 映射导入关系并识别循环依赖 - 计算耦合指标并评估变更影响 - 理解架构模式和模块关系 5. **code-review-standards** - Python 代码审查最佳实践 (2025) - 行业标准：PEP 8, PEP 257, PEP 484，以及现代 Python 特性 - 增强的 MCP 分析：类型安全、反模式、架构审查 - 将自动化检查与语义理解相结合 6. **code-review-security** - OWASP 安全代码审查 - 安全检查清单：输入验证、注入防护、认证模式 - 使用 MCP 工具进行数据流分析（在代码中追踪用户输入） - 特定框架的安全性（Flask/Django 插件集成） 7. **code-review-pr** - 完整的 Pull Request 审查工作流 - 结合自动化检查、语义分析和人工审查 - 分步流程：CI 验证 → 影响分析 → 标准 → 安全 - 建设性的反馈指南和时间预算 ### 示例使用流程 **发现 (README)：** 用户了解到工作流的存在 ``` User: "How do I find all references to a class?" AI: "There's a find-references workflow for that. Let me show you..." ``` **试用（按需）：** 用户尝试工作流 ``` User: "Use pyeye find-references workflow for this class" AI: [fetches workflow from MCP Resources] AI: [executes: get_type_info → find_references → Grep] AI: "Found 15 references: 12 in packages, 3 in notebooks" ``` **采纳（自助服务）：** 用户将其添加到上下文中 **自动使用：** 未来的会话自动使用工作流 ``` User: "Find all uses of this class" AI: [sees workflow in context, follows steps automatically] AI: [returns complete results without prompting] ``` ### 优势 - **发现最佳实践** - 学习最优的工具组合 - **避免试错** - 工作流编码了已发现的模式 - **处理工具限制** - 包含权宜之计（例如 issue #236） - **自助式采纳** - 根据需要将工作流添加到您的上下文中 - **始终保持最新** - 工作流与 MCP 服务器共同维护 ### 技术细节 工作流通过 MCP 资源协议公开： - **URI scheme**：`workflows://[workflow-name]` - **格式**：Markdown（人类和 AI 可读） - **访问方式**：通过 `ListMcpResourcesTool` 和 `ReadMcpResourceTool` - **集成**：可以通过编程方式添加到用户上下文文件中 ## 核心工具 ### 基本导航 - **`find_symbol`** - 查找类、函数或变量定义，并带有重导出跟踪 - 现在包含 `import_paths` 字段，显示符号所有可用的导入路径 - 自动检测通过 `__init__.py` 文件的重导出 - 首先列出较短/首选的导入路径（例如，`from models import User` 优先于 `from models.user import User`） - **`goto_definition`** - 跳转到定义符号的位置 - **`find_references`** - 查找所有使用符号的地方 - **`get_type_info`** - 获取类型提示和 docstring - **`find_imports`** - 跟踪整个项目的模块导入 - **`get_call_hierarchy`** - 分析函数调用关系 - **`find_subclasses`** - 查找所有继承自给定基类的类 - 支持直接和间接继承 - 适用于内置类（Exception, str 等） - 可以显示完整的继承层次结构链 - 正确处理多重继承 ### 多项目工具 - **`configure_packages`** - 设置额外的包位置 - **`find_symbol_multi`** - 跨多个项目进行搜索 - **`configure_namespace_package`** - 设置分布式 Namespace Packages - **`find_in_namespace`** - 在 Namespace Packages 内搜索 ### 项目结构与分析 - **`list_project_structure`** - 查看 Python 项目文件组织结构 - **`list_packages`** - 列出所有具有结构的 Python 包 - **`list_modules`** - 列出模块的导出、类、函数和指标 - **`analyze_dependencies`** - 分析模块导入并检测循环依赖 - **`get_module_info`** - 获取包含指标和依赖项的详细模块信息 ### 特定框架工具（自动激活） #### Django（检测到 Django 时） - **`find_django_models`** - 查找所有 Django 模型 - **`find_django_views`** - 查找所有视图 - **`find_django_urls`** - 查找 URL 模式 - **`find_django_templates`** - 查找模板 - **`find_django_migrations`** - 查找数据库迁移文件 #### Pydantic（检测到 Pydantic 时） - **`find_pydantic_models`** - 发现所有 BaseModel 类 - **`get_model_schema`** - 提取完整的模型 schema - **`find_validators`** - 定位所有验证方法 - **`find_field_validators`** - 查找特定字段的验证器 - **`find_model_config`** - 提取模型配置 - **`trace_model_inheritance`** - 映射模型继承层次结构 - **`find_computed_fields`** - 查找 computed_field 和 @property 字段 #### Flask（检测到 Flask 时） - **`find_flask_routes`** - 发现所有带有方法和 endpoint 的路由装饰器 - **`find_flask_blueprints`** - 定位 Blueprint 定义和注册 - **`find_flask_views`** - 查找视图函数和 MethodView 类 - **`find_flask_templates`** - 定位 Jinja2 模板和 render_template 调用 - **`find_flask_extensions`** - 识别 Flask 扩展（SQLAlchemy, Login, CORS 等） - **`find_flask_config`** - 查找配置文件和 app.config 的使用 - **`find_error_handlers`** - 定位 @app.errorhandler 装饰器 - **`find_cli_commands`** - 查找 Flask CLI 命令 (@app.cli.command) ## 高级功能 ### 多项目支持 分析您的主项目以及本地依赖项： ``` # 配置以分析多个 packages configure_packages( packages=["../my-lib", "~/repos/shared-utils"], namespaces={"company": ["~/repos/company-*"]} ) ``` ### Namespace Packages 处理分布在多个仓库中的包： ``` # repo A 中的 company.auth，repo B 中的 company.api configure_namespace_package( namespace="company", repo_paths=["~/repos/company-auth", "~/repos/company-api"] ) ``` ### 文件更改时自动更新 服务器使用文件监视功能，在代码更改时自动更新： - 实时检测修改 - 使已更改文件的缓存失效 - 为每个项目维护单独的监视器 ## 架构 ``` PyEye ├── Core Server (FastMCP) │ └── 17 MCP tools registered ├── Project Manager │ ├── Multi-project support (LRU cache, max 10) │ ├── Connection pooling (optional optimization) │ ├── Namespace resolver │ └── Configuration loader (multiple sources) ├── Analysis Engine │ └── Jedi (semantic analysis & type inference) ├── Caching & Performance │ ├── File watchers (watchdog with debouncing) │ ├── Granular cache (5min TTL with smart invalidation) │ ├── Metrics collection (p50/p95/p99 latencies) │ └── Performance monitoring & reporting ├── Validation & Security │ ├── Input validation (MCP tool parameters) │ ├── Path security checks │ └── Safe file operations ├── Plugin System │ ├── Base plugin class (AnalyzerPlugin) │ ├── Pydantic plugin (7 specialized tools) │ ├── Django plugin (5 specialized tools) │ └── Flask plugin (8 specialized tools) ├── Utility Systems │ ├── Dependency tracking & circular detection │ ├── Import analysis & re-export resolution │ ├── Scope management (main/all/namespace scoping) │ ├── Async utilities (concurrent operations) │ └── Cross-platform path handling └── Development & Automation ├── Release automation agent ├── Dogfooding metrics tracking └── Worktree safety management ``` ## 插件开发 为您的项目模式创建自定义插件： ``` from pyeye.plugins.base import AnalyzerPlugin class MyProjectPlugin(AnalyzerPlugin): def name(self) -> str: return "MyProject" def detect(self) -> bool: # Return True if this plugin should activate return (self.project_path / "my_framework.conf").exists() def find_patterns(self, pattern_name: str): # Find your custom patterns pass ``` ## 性能监控详情 服务器包含全面的性能监控，以帮助识别瓶颈并为大规模部署优化性能。 ### 多项目工作流的连接池 默认情况下启用了连接池，以优化处理多个项目时的性能。您可以自定义池化行为： ``` # 自定义 connection pooling（默认已启用） export PYEYE_POOL_MAX_CONNECTIONS=20 # Increase pool size for many projects export PYEYE_POOL_TTL=7200 # Increase TTL to 2 hours # 或按需禁用 pooling export PYEYE_ENABLE_CONNECTION_POOLING=false # 启动 server uv run mcp dev src/pyeye/server.py ``` 连接池提供了显著的性能提升： - 减少频繁访问项目的**初始化时间** - 跨多个分析操作**共享连接** - 基于连接的 TTL 自动驱逐空闲连接 - 具有可配置限制的**内存高效**池化 ### 跟踪的指标 - **操作延迟**：所有 MCP 工具的 p50、p95、p99 百分位数 - **缓存性能**：命中率、未命中率、驱逐次数 - **连接池统计信息**：池大小、命中、未命中、驱逐、重用率 - **内存使用情况**：RSS、VMS、使用百分比 - **错误率**：跟踪每次操作的失败情况 - **吞吐量**：每秒操作数 ### 性能基准 CI 中强制执行以下性能基准： | 操作 | p50 (ms) | p95 (ms) | p99 (ms) | |-----------|----------|----------|----------| | symbol_search | 50 | 100 | 200 | | goto_definition | 30 | 75 | 150 | | find_references | 100 | 250 | 500 | | cache_lookup | 0.1 | 0.5 | 1.0 | ## 开发 ``` # 安装开发依赖 uv add --dev pytest black ruff mypy # 运行测试 uv run pytest # 格式化代码 uv run black src/ uv run ruff check src/ # 测试 server uv run mcp dev src/pyeye/server.py ``` ## 文档 - [安装指南](#installation) - [配置指南](#configuration) - [故障排除指南](docs/TROUBLESHOOTING.md) - 常见问题与解决方案 - [API 参考](#core-tools) ## 贡献 欢迎贡献！请随时提交 Pull Request。 ## 许可证 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件 ## 致谢 基于以下项目构建： - [Jedi](https://github.com/davidhalter/jedi) - Python 静态分析和类型推断 - [FastMCP](https://github.com/jlowin/fastmcp) - MCP 服务器框架 - [Watchdog](https://github.com/gorakhargosh/watchdog) - 文件系统监控

标签：MCP, Python, SOC Prime, 云安全监控, 代码分析, 代码智能, 凭证管理, 开发工具, 无后门, 逆向工具, 静态分析