Python类型检查服务

Pyright Hand MCP服务器

一个模型上下文协议（MCP）服务器，使用Pyright为整个代码库提供Python类型检查功能。我在使用代理AI时经常遇到的一个问题是，它不断地吐出带有大量类型安全错误的代码，无论多少提示或指导都无法使其不断验证文件。此MCP将向代理公开一个工具，该工具将提供所有文件的Pyright分析，以便它可以不断检查整个项目的类型错误。

特性

• 类型检查：在Python项目上运行Pyright分析
• 文件发现：自动查找Python文件，同时尊重.gitignore
• 结构化输出：以结构化格式返回详细的诊断信息
• 多个传输：支持stdio、SSE和HTTP传输
• 进度报告：分析过程中的实时进度更新
• 可配置严重性：按错误、警告或信息级别筛选结果

先决条件

Pyright必须在您的PATH中安装并可用：

# Via npm (recommended)
npm install -g pyright

# Or via pip
pip install pyright

Docker使用

此服务器设计为在Docker容器中运行，分析作为卷装载的Python代码库。

Claude的MCP配置示例

以下是一个如何配置此工具以与AI助手一起使用的示例：

{
    "mcpServers": {
        "pyright-hand-mcp": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "-v",
                "/Users/username/your/project:/app/code",
                "--rm",
                "evanhuang117/pyright-hand-mcp-server"
            ]
        }
    }
}

替换 /path/to/your/python/project 使用要分析的代码的实际路径。

可用工具

check_python_types

分析Python文件 /app/code 目录中的类型错误。

参数：

• severity_level （字符串，可选）：最低严重级别（“错误”、“警告”、“信息”）。默认值：“警告”
• ignore_patterns （list[string]，可选）：要忽略的其他glob模式

退货：

• 结构化结果，包括汇总统计和详细诊断

list_python_files

列出所有Python文件 /app/code 将被分析的目录。

参数：

• ignore_patterns （list[string]，可选）：要忽略的其他glob模式

退货：

• Python文件路径列表

示例用法

# Example of calling the tool via MCP
result = await session.call_tool("check_python_types", {
    "severity_level": "warning",
    "ignore_patterns": ["tests/*.py"]
})

print(f"Found {result.summary.errorCount} errors")
for diagnostic in result.diagnostics:
    print(f"{diagnostic.file}:{diagnostic.range.start['line']} - {diagnostic.message}")

配置

服务器尊重：

• .gitignore 用于自动排除文件的文件
• pyrightconfig.json 适用于Pyright特定配置
• 标准忽略模式（__pycache__、.vnv等）

发展

pip install -e ".[dev]"

运行测试：

pytest

跑步覆盖：

pytest --cov=pyright_mcp

格式代码：

black src/ tests/
ruff check src/ tests/

许可证

MIT许可证-有关详细信息，请参阅许可证文件。