MCP Pyrefly Autotype Server

\[正在进行和未完成的工作-使用风险自负\]MCP Pyrefly Autotype服务器

一个模型上下文协议（MCP）服务器，使用Pyrefly提供自动Python类型注释。该服务器使LLM和AI编码助手能够无缝分析Python代码、添加类型注释和执行类型检查。

什么是模型上下文协议（MCP）？

模型上下文协议（MCP）是一个开放标准，使人工智能助手和语言模型能够安全地访问外部数据源和工具。MCP服务器充当人工智能系统和各种资源之间的桥梁，提供对信息和功能的结构化访问。

MCP的工作原理

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   LLM/AI Client │◄──►│   MCP Server    │◄──►│  External Tools │
│   (e.g. Claude) │    │  (This Project) │    │   (Pyrefly)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

MCP服务器可以提供：

• 资源：静态或动态数据源（文件、数据库、API）
• 工具：执行操作的可执行函数
• 提示：特定任务的模板提示

这使得AI助手能够：

• 访问实时信息
• 执行复杂的操作
• 与现有工具和工作流程集成
• 通过受控访问维护安全

特性

此MCP服务器提供全面的Python类型注释功能：

🔍 分析工具

• 文件分析：分析单个Python文件中缺少的类型注释
• 项目上下文：获取项目范围内的类型信息以进行更好的推理
• Pyrefly集成：利用Pyrefly强大的类型推理引擎

⚡ 类型增强

• 自动类型添加：使用Pyrefly的autotype功能添加类型注释
• 基于文件的处理：使用类型注释处理单个Python文件
• 选择备份：可以在修改之前创建备份文件（在需要时）
• 项目集成：尊重pyrefly配置文件

✅ 类型检查

• Pyrefly集成：使用Pyrefly的内置类型检查器验证类型注释
• 错误报告：基本类型检查结果和错误输出
• 基于文件的验证：检查单个文件是否存在类型错误

🤖 LLM集成

• 基本提示：类型分析任务的预构建提示
• 结构化数据：JSON格式的分析结果
• 简单的工作流程：基本分析→ 注释→ 验证工作流

为什么使用此MCP服务器？

适用于法学硕士和人工智能助理

• MCP集成：与MCP兼容的AI客户端配合使用
• JSON响应：为更好的决策提供结构化数据
• 基本背景：简单的项目结构分析
• 错误处理：基本错误报告和优雅的故障处理

对于开发者

• 冷启动助手：协助处理完全非类型化的代码库
• 基本打字：简单类型注释工作流
• 文件处理：单个文件类型检查和注释
• 工具集成：与现有Python开发工作流的基本集成

安装

先决条件

• Python 3.8或更高版本
• uv（快速Python包管理器）： pip install uv 或查看 紫外线安装指南

安装MCP服务器

# Clone or download this repository
git clone https://github.com/your-username/mcp-pyrefly-autotype.git
cd mcp-pyrefly-autotype

# Install dependencies with uv
uv sync

# For development (includes dev dependencies)
uv sync --dev

# Alternative: traditional pip install
# pip install -e .
# pip install -e ".[dev]"

用法

运行服务器

服务器可以直接运行，也可以与MCP兼容的客户端集成：

# Run directly (for testing)
uv run python -m mcp_pyrefly_autotype.server

# Or use the installed script (after uv sync)
uv run mcp-pyrefly-autotype

# Alternative: activate virtual environment first
uv shell
python -m mcp_pyrefly_autotype.server

与AI客户端集成

Claude桌面（示例配置）

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "pyrefly-autotype": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_pyrefly_autotype.server"],
      "env": {}
    }
  }
}

VS代码与副本

1. 安装VS Code的MCP扩展
2. 在工作区设置中配置服务器：
3. 创建.vcode/mcp.json文件

{
	"servers": {
		"pyrefly-autotype": {
			"type": "stdio",
			"command": "uv",
			"args": [
				"run",
				"mcp-pyrefly-autotype"
			]
		}
	},
	"inputs": []
}

使其显示在VS代码中（MCP服务器+副驾驶聊天工具）

1. 在VS Code中安装“模型上下文协议（MCP）”扩展，并确保GitHub Copilot已启用/更新。
2. 保存 .vscode/mcp.json 上面显示的文件位于工作区的根目录中。
3. 重新加载窗口：按Ctrl+Shift+P→ “开发人员：重新加载窗口”。
4. 在MCP服务器视图中验证：

- 打开命令面板（Ctrl+Shift+P）→ 运行“MCP：显示服务器”，或从活动栏打开“MCP服务器”视图。 - 您应该看到一个名为的服务器 pyrefly-autotype。状态应为“正在运行”。如果没有： - 确认 uv 已安装并位于PATH上，并且 uv sync 已运行。 - 在Windows上，安装Python/uv后可能需要重新启动VS Code。

1. 在Copilot聊天工具中验证：

- 打开副驾驶聊天（Ctrl+I或副驾驶图标）。 - 在“工具”窗格中，展开MCP部分。你应该看看 pyrefly-autotype 上市的。如果丢失，请检查： - 工作区是受信任的（在VS Code中查找“信任”横幅）。 - MCP集成在副驾驶设置中启用。

运行示例查询（在Copilot Chat内）

在新的Copilot聊天选项卡中尝试这些提示。Copilot将为您调用服务器的工具。

• “使用pyrefly自动类型MCP服务器分析文件 simple_untyped.py （detained=true），然后向其中添加类型，最后对其进行类型检查。重复添加→最多检查3次，直到类型检查通过。”
• “分析 example_untyped.py 对于缺少的注释，请使用备份添加类型，并运行类型检查。总结更改和剩余警告。”
• “给定SamplePrompt.md中的循环，运行代理循环 simple_untyped.py：add_types_to_file→ type_check_file，最多精炼3轮。”

预期成果：

• Copilot将调用这些MCP工具： analyze_python_file, add_types_to_file, type_check_file.
• 文件将被注释到位（根据您的要求，可能会创建备份）。
• 您将收到摘要和任何剩余的非阻塞警告。

可用工具

analyze_python_file

分析Python文件中缺少的类型注释。

参数：

• file_path （必填）：Python文件的路径
• detailed （可选）：包括详细的分析信息

例子：

# LLM can request:
# "Analyze the file 'src/utils.py' for type annotation needs"

add_types_to_file

使用Pyrefly向Python文件添加类型注释（这将调用 pyrefly autotype 引擎盖下）。

参数：

• file_path （必填）：Python文件的路径
• backup （可选）：修改前创建备份（默认值：true）

例子：

# LLM can request:
# "Add type annotations to 'src/models.py'"

type_check_file

使用Pyrefly对Python文件运行类型检查。

参数：

• file_path （必填）：Python文件的路径

例子：

# LLM can request:
# "Type check the file 'src/api.py' and report any errors"

get_project_context

获取项目范围内的类型信息以进行更好的推理。

参数：

• project_path （必填）：项目目录的路径

例子：

# LLM can request:
# "Analyze the project structure for type annotation opportunities"

可用提示

analyze_typing_needs

为类型注释需求生成分析提示。

type_improvement_plan

制定一个全面的计划，以提高项目中的类型覆盖率。

示例工作流

1.完成文件类型增强

# LLM workflow:
# 1. "Analyze 'calculator.py' for type needs"
# 2. "Add types to 'calculator.py'"
# 3. "Type check 'calculator.py' and report results"

2.项目范围类型分析

# LLM workflow:
# 1. "Get project context for '/my-project'"
# 2. "Create a type improvement plan for the project"
# 3. "Prioritize files for type annotation"

3.冷启动类型添加

# For completely untyped files:
# 1. "Analyze 'legacy_code.py' - it has no types at all"
# 2. "Add types to 'legacy_code.py'" 
# 3. "Check for type errors and suggest corrections"

用例

🥶 冷启动项目

• 挑战：没有类型注释的旧代码库
• 解决方案：使用具有基本MCP集成的Pyrefly自动类型
• 利益：开始向非类型化代码库添加类型

📈 增量打字

• 挑战：逐步向活动项目添加类型
• 解决方案：具有基本项目上下文的按文件类型注释的文件
• 利益：逐步采用，无重大中断

🔧 CI/CD集成

• 挑战：在团队项目中保持类型质量
• 解决方案：管道中的基本类型检查集成
• 利益：简单的类型验证工作流

🤝 LLM辅助开发

• 挑战：LLM需要有关键入需求的上下文
• 解决方案：基本结构化分析数据和简单提示
• 利益：改进了Python类型注释任务的AI辅助

配置

Pyrefly配置

服务器遵循Pyrefly的配置。您可以使用以下任一方法在项目中配置Pyrefly：

1. pyrefly.toml 项目根目录中的文件：

# Files to include in type checking  
project-includes = ["src/**/*.py"]

# Files to exclude from type checking
project-excludes = ["tests/**", "**/__pycache__/**"]

# Python version to assume
python-version = "3.12"

# How to handle untyped function definitions
untyped-def-behavior = "check-and-infer-return-type"

# Configure specific error types
[errors]
# Enable/disable specific error types
bad-assignment = true
missing-return-type = true

1. pyproject.toml 文件下 [tool.pyrefly] 章节：

[tool.pyrefly]
# Files to include in type checking
project-includes = ["src/**/*.py"]

# Files to exclude from type checking  
project-excludes = ["tests/**", "**/__pycache__/**"]

# Python version and platform
python-version = "3.12"
python-platform = "linux"

# Type checking behavior
untyped-def-behavior = "check-and-infer-return-type"
ignore-missing-imports = ["requests.*", "numpy.*"]

# Error configuration
[tool.pyrefly.errors]
bad-assignment = true
missing-return-type = true

请参阅 Pyrefly配置文档 所有可用选项。

发展

运行测试

# Run all tests
uv run pytest tests/

# Run with coverage
uv run pytest tests/ --cov=mcp_pyrefly_autotype

# Run specific test
uv run python tests/test_server.py

# Test server functions directly
uv run python test_direct.py

# Run demo workflow
uv run python test_demo.py

测试MCP服务器

该项目包括几个测试文件来验证功能：

• tests/test_server.py -带有模拟pyrefly调用的全面测试套件
• test_direct.py -使用真实pyrefly直接测试服务器功能
• test_demo.py -展示完整工作流程的交互式演示
• simple_untyped.py -测试类型注释的示例文件

要端到端测试服务器，请执行以下操作：

# 1. Test with a simple untyped file
uv run python test_demo.py

# 2. Test server functions directly  
uv run python test_direct.py

# 3. Run the MCP server (for client integration)
uv run python -m mcp_pyrefly_autotype.server

代码质量

# Format code
uv run black src/ tests/

# Lint code  
uv run ruff check src/ tests/

# Type check
uv run pyrefly check src/

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关项目

• 除虫菊 -核心型推理机
• 模型上下文协议 -MCP规范

支持

如有疑问和支持：

• 在GitHub上打开一个问题
• 查看Pyrefly文档
• 审查MCP规范

______________________________________________________________________

*此MCP服务器弥合了AI助手和Python类型注释工具之间的差距，实现了AI驱动的开发环境中类型增强工作流的无缝集成。*

示例查询和提示库

这 sample_queries/ 目录包含现成的提示模板，您可以将其粘贴到您的AI客户端（VS Code with Copilot MCP或Claude Desktop）中，以有效地驱动服务器：

• sample_queries/PromptWithTools.md --一个紧凑的“代理循环”提示，指示助手使用可用工具(add_types_to_file, type_check_file，并且可选 get_project_context)并迭代多达3轮优化。非常适合单文件或小功能工作。
• sample_queries/LargeUntypedCodebase.md --一种面向批处理的工作流，用于增量键入大型、大多无类型的存储库。它包括计划、每个文件的优化循环、批处理门和进度跟踪指导。

如何使用VS Code+Copilot：

• 打开Copilot聊天。确保 pyrefly-autotype MCP服务器出现在“工具”下（请参阅上面的说明）。
• 在中打开一个markdown文件 sample_queries/，复制提示，并将其粘贴到Copilot Chat中。
• 如果提示中包含工具调用JSON示例，Copilot将自动将其转换为MCP工具调用。

如何使用Claude Desktop：

• 确保您的Claude MCP配置包括此服务器（请参阅上文“Claude Desktop”部分）。
• 打开一个新聊天，粘贴任何提示，然后按照客服的步骤进行操作。Claude将使用提供的JSON形状调用MCP工具。

提示：从开始 PromptWithTools.md 在单个文件上（例如。， simple_untyped.py)查看完整添加→ 检查→ 端到端地优化流程。然后继续 LargeUntypedCodebase.md 用于多文件、增量采用。