py2to3mcp (Talianzakowski)

MCP服务器套件

一组MCP（模型上下文协议）服务器，扩展了Claude Code的Python开发和代码迁移功能。

服务器概述

先决条件

• Python 3.9或更高版本
• Claude Code CLI或VS Code扩展

快速设置

1.克隆和设置环境

git clone 
cd myfirstMCPserver
python3 -m venv mcp-venv
source mcp-venv/bin/activate  # Windows: mcp-venv\Scripts\activate
pip install -r requirements.txt

2.配置克劳德代码

编辑 ~/.claude.json 并添加：

{
  "/absolute/path/to/myfirstMCPserver": {
    "mcpServers": {
      "my-first-server": {
        "command": "/absolute/path/to/myfirstMCPserver/mcp-venv/bin/python",
        "args": ["/absolute/path/to/myfirstMCPserver/mcp_server.py"]
      },
      "py2to3-migration": {
        "command": "/absolute/path/to/myfirstMCPserver/mcp-venv/bin/python",
        "args": ["/absolute/path/to/myfirstMCPserver/py2to3_server.py"]
      },
      "filesystem": {
        "command": "/absolute/path/to/myfirstMCPserver/mcp-venv/bin/python",
        "args": ["/absolute/path/to/myfirstMCPserver/filesystem_server.py"]
      },
      "codeindex": {
        "command": "/absolute/path/to/myfirstMCPserver/mcp-venv/bin/python",
        "args": ["/absolute/path/to/myfirstMCPserver/codeindex_server.py"]
      }
    }
  }
}

重要提示： 使用 mcpServers （camelCase），将路径替换为绝对路径。

3.重新启动克劳德代码

CLI：退出并重新启动|VS代码：重新加载窗口

______________________________________________________________________

py2to3迁移服务器

工具

用例

转换文件夹和所有子文件夹

步骤1：获取迁移报告

"Generate a migration report for /path/to/legacy/project"

退货：

• 文件和问题总数
• 预计工作量
• 优先文件（速赢、高密度、重大重构）
• 按类别分列的问题

第二步：转换文件

"Convert /path/to/legacy/project/module.py to Python 3"

在以下位置创建备份 module.py.py2.bak 并就地转换。

步骤3：获取转化报告

"Generate a conversion report comparing /path/to/module.py.py2.bak with /path/to/module.py"

显示：

• 固定费率百分比
• 固定了哪些模式
• 还有什么需要注意的

步骤4：验证以供人工审核

"Validate the conversion of /path/to/module.py"

标识：

• 剩余的Python 2模式
• 需要人工判断的运行时问题（分割、文件I/O、pickle）
• 严重程度（高/中/低）
• 测试建议

批量扫描特定文件（FR-4）

"Scan these files for Python 2 compatibility: /path/file1.py, /path/file2.py, /path/file3.py"

用途 scan_compat 通过以下方式返回机密问题：

• 代码标识符（PY2-ITER-001、PY2-LIB-002等）
• 严重性（错误/警告/信息）
• 类别（迭代器、文本类型、stdlib移动等）
• 建议修复

检查具体的迁移问题

"Get a migration guide for unicode handling"
"Get a migration guide for dictionary methods"

可用指南：打印、unicode、dict_methods、异常、分割、导入

问题分类（scan_compat）

严重级别：

• error -无法在Python 3中运行
• warning -可能导致问题
• info -风格/最佳实践

类别：

• iterators -xrange、iterites、has_key
• text-types -unicode，基字符串，长
• operators -\<>，回溯
• syntax -打印语句，逗号除外
• stdlib-move -配置解析器、urllib2、队列
• builtins -raw_input、execfile、reduce

______________________________________________________________________

文件系统服务器

工具

用例

探索项目结构

"List all Python files in /path/to/project"
"List all test files matching *_test.py"

批量读取文件

"Read these files: config.py, settings.py, constants.py"

安全文件更新

"Write the updated content to /path/to/file.py"

使用原子写入来防止损坏。

______________________________________________________________________

codeindex服务器

工具

用例

查找代码模式

"Search for 'def.*error' in /path/to/project"
"Find all uses of 'requests.get' in the codebase"

审核依赖关系

"Find all imports of 'json' in /path/to/project"
"Find all imports of 'pickle' in /path/to/project"

返回按文件分组的文件位置。

______________________________________________________________________

示例工作流

完成Python 2到3的迁移

1. "Generate a migration report for /legacy/project"
   → See overview, effort estimate, priority files

2. "Scan these files for compatibility: /legacy/project/main.py, /legacy/project/utils.py"
   → Get classified issues with suggested fixes

3. "Convert /legacy/project/main.py to Python 3"
   → Auto-convert with backup

4. "Generate conversion report for /legacy/project/main.py.py2.bak vs /legacy/project/main.py"
   → See what was fixed

5. "Validate the conversion of /legacy/project/main.py"
   → Get human review items and test recommendations

6. Repeat for each file, addressing high-severity items first

代码库探索

1. "List all Python files in /project excluding venv and __pycache__"
   → Get project structure

2. "Find all imports of 'requests' in /project"
   → See dependency usage

3. "Search for 'TODO|FIXME' in /project"
   → Find work items

依赖性审计

1. "Find all imports of 'pickle' in /project"
   → Identify security/compatibility concerns

2. "Validate conversion of files using pickle"
   → Get specific guidance on pickle protocol issues

______________________________________________________________________

响应格式

所有工具都返回标准化的JSON响应：

{
  "tool": "tool_name",
  "status": "success",
  "timestamp": "2025-01-01T00:00:00Z",
  "data": { ... },
  "metadata": {
    "limits": { ... }
  }
}

安全限值

• 最大文件大小：10 MB
• 每次操作的最大文件数：1000
• 最大代码长度：1000000个字符
• 超时：300秒

______________________________________________________________________

故障排除

服务器未连接

1. 检查 ~/.claude.json 位置和语法
2. 验证Python和脚本的绝对路径
3. 使用 mcpServers （案例）
4. 手动测试： /path/to/mcp-venv/bin/python /path/to/server.py

工具未出现

• 配置更改后重新启动Claude代码
• 验证JSON语法（无尾随逗号）
• 检查服务器是否在正确的项目路径下

转换问题

• 跑 validate_conversion 确定遗留问题
• 检查是否存在需要手动审查的运行时问题（划分、编码）
• 使用 get_migration_guide 对于特定模式

______________________________________________________________________

创建自己的MCP服务器

基本模板：

import asyncio
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

server = Server("my-server")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="my_tool",
            description="Description",
            inputSchema={
                "type": "object",
                "properties": {
                    "param1": {"type": "string", "description": "Param description"}
                },
                "required": ["param1"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "my_tool":
        return [TextContent(type="text", text=f"Result: {arguments.get('param1')}")]
    return [TextContent(type="text", text=f"Unknown tool: {name}")]

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream, server.create_initialization_options())

if __name__ == "__main__":
    asyncio.run(main())

______________________________________________________________________

参考文献

• MCP文件
• MCP Python SDK
• Fissix（lib2to3分叉）

测试样品

这 test_samples/ 目录包含用于测试的Python 2示例文件：

• simple_prints.py -打印报表
• dict_operations.py -密码，has_key
• string_unicode.py -Unicode，基本字符串
• exceptions_old.py -旧的除外/提高语法
• imports_old.py -重命名stdlib模块
• builtins_old.py -废弃的内置组件
• division_issues.py -整数除法（运行时）
• file_encoding.py -文件I/O、pickle（运行时）
• classes_old.py -旧式课程
• complex_mixed.py -所有图案组合