MCP Python 工具箱

一个模型上下文协议 (MCP) 服务器，为 Python 开发提供一套全面的工具，使像 Claude 这样的人工智能助手能够有效地处理 Python 代码和项目。

概述

MCP Python 工具箱实现了一个模型上下文协议服务器，使 Claude 能够通过标准化接口执行 Python 开发任务。它使 Claude 能够：

• 读取、写入和管理工作区中的文件
• 分析、格式化和检查 Python 代码
• 管理虚拟环境和依赖项
• 安全地执行 Python 代码

功能

文件操作 (FileOperations)

• 在工作区目录中安全的文件操作
• 路径验证，防止未经授权访问工作区外部
• 读取和写入文件，支持行特定操作
• 创建和删除文件和目录
• 列出目录内容，包含详细的元数据（大小、类型、修改时间）
• 写入文件时自动创建父目录

代码分析 (CodeAnalyzer)

• 使用 AST 解析和分析 Python 代码结构
• 提取有关以下内容的详细信息：
  • 导入语句及其别名
  • 函数定义，包含参数和装饰器
  • 类定义，包含基类和方法
  • 全局变量赋值
• 使用以下工具格式化代码：
  • Black（默认）
  • PEP8（使用 autopep8）
• 使用 Pylint 进行全面的代码检查，包含详细的报告

项目管理 (ProjectManager)

• 创建和管理具有 pip 支持的虚拟环境
• 灵活的依赖项管理：
  • 从 requirements.txt 安装
  • 从 pyproject.toml 安装
  • 支持特定软件包版本
• 高级依赖项处理：
  • 检查软件包之间的版本冲突
  • 列出所有已安装的软件包及其版本
  • 将软件包更新到特定版本
  • 从当前环境生成 requirements.txt

代码执行 (CodeExecutor)

• 在受控环境中执行 Python 代码
• 使用项目的虚拟环境以获得一致的依赖项
• 用于代码执行的临时文件管理
• 捕获 stdout、stderr 和退出代码
• 支持自定义工作目录

安装

1. 克隆存储库：

git clone https://github.com/gianlucamazza/mcp_python_toolbox.git
cd mcp_python_toolbox

2. 创建并激活虚拟环境：

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate  # Windows

3. 以开发模式安装软件包：

pip install -e ".[dev]"

用法

作为 CLI 工具运行

启动服务器的最简单方法是使用 CLI：

# 以当前目录作为工作区启动
python -m mcp_python_toolbox

# 或指定一个工作区目录
python -m mcp_python_toolbox --workspace /path/to/your/project

使用 Claude Desktop 设置

Claude Desktop 可以自动启动和管理 MCP Python 工具箱服务器。以下是如何配置它：

1. 如上所述安装并设置 MCP Python 工具箱
2. 在 Claude Desktop 的 MCP 工具配置中为 Python 工具箱添加一个配置条目：

"python-toolbox": {
  "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python",
  "args": [
    "-m",
    "mcp_python_toolbox",
    "--workspace",
    "/Users/username/path/to/workspace"
  ],
  "env": {
    "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
    "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
    "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv",
    "PYTHONHOME": ""
  }
}

3. 自定义路径以匹配您的环境
4. Claude Desktop 将在需要时自动启动 MCP 服务器
5. Claude 现在可以通过 MCP 接口访问 Python 开发工具

编程方式使用

from mcp_python_toolbox import PythonToolboxServer

server = PythonToolboxServer(workspace_root="/path/to/your/project")
server.setup()
server.run()

核心模块示例

文件操作

from mcp_python_toolbox.core import FileOperations

file_ops = FileOperations(workspace_root="/path/to/project")

# 读取文件内容
content = file_ops.read_file("src/example.py")
# 读取特定行
lines = file_ops.read_file("src/example.py", start_line=10, end_line=20)

# 写入文件
file_ops.write_file("output.txt", "Hello, World!")
# 追加到文件
file_ops.write_file("log.txt", "New entry\n", mode='a')

# 列出目录内容
contents = file_ops.list_directory("src")
for item in contents:
    print(f"{item['name']} - {item['type']} - {item['size']} bytes")

代码分析

from mcp_python_toolbox.core import CodeAnalyzer

analyzer = CodeAnalyzer(workspace_root="/path/to/project")

# 分析 Python 文件结构
analysis = analyzer.parse_python_file("src/example.py")
print(f"Found {len(analysis['functions'])} functions")
print(f"Found {len(analysis['classes'])} classes")

# 格式化代码
formatted = analyzer.format_code(code, style='black')

# 检查代码
issues = analyzer.lint_code("src/example.py")
for issue in issues:
    print(f"Line {issue['line']}: {issue['message']}")

项目管理

from mcp_python_toolbox.core import ProjectManager

pm = ProjectManager(workspace_root="/path/to/project")

# 创建虚拟环境
pm.create_virtual_environment()

# 安装依赖项
pm.install_dependencies()  # from requirements.txt or pyproject.toml
pm.install_dependencies("requirements-dev.txt")  # from specific file

# 检查冲突
conflicts = pm.check_dependency_conflicts()
if conflicts:
    print("Found dependency conflicts:")
    for conflict in conflicts:
        print(f"{conflict['package']} requires {conflict['requires']}")

# 更新软件包
pm.update_package("requests")  # to latest
pm.update_package("flask", version="2.0.0")  # to specific version

代码执行

from mcp_python_toolbox.core import CodeExecutor

executor = CodeExecutor(workspace_root="/path/to/project")

code = '''
def greet(name):
    return f"Hello, {name}!"

print(greet("World"))
'''

result = executor.execute_code(code)
print(f"Output: {result['stdout']}")
print(f"Errors: {result['stderr']}")
print(f"Exit code: {result['exit_code']}")

开发

运行测试

pytest

类型检查

mypy src/mcp_python_toolbox

代码检查

pylint src/mcp_python_toolbox

格式化

black src/mcp_python_toolbox

贡献

1. Fork 存储库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• 实现了 模型上下文协议 规范
• 使用现代 Python 开发工具和最佳实践构建
• 使用行业标准格式化 (Black) 和代码检查 (Pylint) 工具