Vscode MCP Python

🚀 MCP 服务器 - 模型上下文协议服务器

MCP（模型上下文协议）服务器可用于集成 VSCode 和 Claude，具备全面的工具支持、性能监控和诊断功能，适用于生产环境。

🚀 快速开始

MCP 服务器是一个为 VSCode 和 Claude 集成设计的生产级服务器。以下是快速上手的步骤：

1. 确保满足安装的前提条件，如 Python 3.8 或更高版本。
2. 按照安装步骤克隆或下载仓库，并配置好相关文件。
3. 参考配置部分，将服务器配置添加到 Claude Desktop 的配置文件中。
4. 运行快速启动命令，启动服务器。

✨ 主要特性

⚡ 技术优化

• 减少令牌开销：MCP 服务器允许 Claude 仅查询所需的特定数据，而不是将大型数据集粘贴到聊天中。这使得响应速度更快，且每个令牌的使用成本更低。
• 异步执行：借助 Python 的异步功能，服务器可以同时处理多个数据请求，而不会冻结交互。
• 自定义工具映射：可以将复杂的 Python 库（如 pandas、beautifulsoup 或 os）封装成简单的工具，供 Claude 立即调用。

🌟 为项目增值

• 弥合差距：它将 Claude 从“聊天机器人”转变为“开发人员代理”，使其能够查看和修改本地代码或数据库。
• 工作流自动化：只需与 Claude 对话，就可以自动化执行重复性任务，如日志分析、本地文件重组或数据库查询。
• 私有数据上下文：由于服务器在本地运行，您可以为 Claude 提供来自私有文档或公司内部数据的上下文，而无需将这些文件上传到云端。

核心能力

• 10 种专业流程：完成文件操作、代码分析和 VSCode 集成。
• LRU 缓存：智能请求缓存，性能提升 2 - 3 倍。
• 类型安全：100% 类型提示（符合 PEP 484）。
• 企业架构：遵循 SOLID 原则、设计模式，具备专业的结构。
• 全面日志记录：将结构化日志记录到标准错误输出，便于调试。
• 错误处理：具备生产级的错误处理和特定异常处理。

📦 安装指南

前提条件

• Python 3.8 或更高版本
• VSCode（可选，用于 VSCode 集成功能）
• Windows、Linux 或 macOS

安装步骤

1. 克隆或下载此仓库。
2. 确保所有文件位于同一目录下：
   • mcp_server.py - 主服务器
   • tools.py - 工具实现
   • vscode_detector.py - VSCode 集成
   • diagnostics.py - 健康检查
   • performance_monitor.py - 性能跟踪
   • languages.json - 语言配置
3. 配置您的人工智能桌面（适用于 Claude）以使用此服务器（请参阅配置部分）。

快速启动

# 测试服务器编译
python -m py_compile mcp_server.py

# 运行诊断
python diagnostics.py

# 启动服务器（通常由 Claude 调用）
python mcp_server.py

📚 详细文档

配置

将以下内容添加到您的 Claude Desktop 配置文件中：

Windows

%APPDATA%\Claude\claude_desktop_config.json

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

配置示例

{
  "mcpServers": {
    "vscode-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\mcp_server.py"]
    }
  }
}

💻 使用示例

基础用法

读取文件

用户：“读取 mcp_server.py 的内容”
Claude：使用 read_file 工具
结果：显示文件内容

代码分析

用户：“分析 tools.py 中的代码”
Claude：使用 analyze_code 工具
结果：列出函数、类和导入，并显示行号

编写代码

用户：“编写一个 Python 计算器”
Claude：使用 write_code_to_project 工具
系统：出现权限提示
用户：批准
结果：创建 calculator.py 并提供详细反馈

修改代码

用户：“在 calculator.py 中，为 divide 函数添加错误处理”
Claude：使用 change_code 工具
系统：出现权限提示
用户：批准
结果：更新函数，并提供前后预览

项目概述

用户：“显示项目结构”
Claude：使用 get_project_structure 工具
结果：按编程语言组织文件

🔧 技术细节

主要组件

MCPServer 类

• 实现 MCP 2024 - 11 - 05 协议处理
• JSON - RPC 2.0 通信
• 异步/等待模式
• 请求/响应管理

ToolRegistry 类

• 工具注册和管理
• 输入模式验证
• 工具调用

RequestCache 类

• LRU 缓存机制
• 可配置的缓存大小
• 自动淘汰

LanguageConfig 类

• 语言配置管理
• 代码分析的模式匹配
• 文件扩展名处理

设计模式

• 注册表模式 - 工具管理
• 缓存模式 - 请求缓存
• 数据类模式 - 类型安全的元数据
• 依赖注入 - 配置管理
• 策略模式 - 工具执行

性能优化

优化特性

• 安全工具请求的 LRU 缓存
• 非阻塞操作的异步/等待
• 高效的文件系统扫描
• 智能 VSCode 进程检测
• 最小的内存占用

性能指标

诊断

健康检查

运行全面诊断：

# 完整诊断套件
python diagnostics.py

# 快速检查
python diagnostics.py --mode quick

# 健康状态（JSON）
python diagnostics.py --mode health

诊断测试

• Python 版本兼容性
• 所需文件是否存在
• 文件权限
• 配置有效性
• 模块导入
• 语法检查
• 磁盘空间
• 内存使用量
• VSCode 状态
• 网络连接

开发

代码质量标准

• PEP 8 - 遵循风格指南
• PEP 257 - 遵循文档字符串约定
• PEP 484 - 使用类型注解
• Google 风格 - 采用文档字符串格式

测试

# 检查所有文件的语法
python -m py_compile *.py

# 运行诊断
python diagnostics.py

# 测试工具导入
python -c "import tools; import mcp_server"

故障排除

常见问题

服务器无法启动

• 检查 Python 版本：python --version（必须为 3.8 或更高版本）
• 运行诊断：python diagnostics.py
• 检查语法：python -m py_compile mcp_server.py

工具无法工作

• 验证文件权限
• 检查 languages.json 是否为有效的 JSON 文件
• 运行导入测试：python -c "import tools"

VSCode 检测失败

• 确保 VSCode 正在运行
• 检查进程权限（Windows）
• 验证工作区目录是否可访问

权限错误

• 以管理员身份运行（如有需要）
• 检查文件/目录权限
• 验证配置中的路径

代码贡献指南

1. 遵循 PEP 8 风格指南。
2. 为所有函数添加类型提示。
3. 编写全面的文档字符串。
4. 包含错误处理。
5. 为新功能添加测试。
6. 为新工具更新 README。

添加新工具

1. 在 tools.py 中实现工具函数。
2. 在 mcp_server.py 的 TOOL_DEFINITIONS 中添加工具定义。
3. 在 main() 函数中注册工具。
4. 更新 README 文档。
5. 如有需要，添加诊断检查。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

文档

• 代码文档字符串中提供完整的 API 参考。
• 本 README 中包含使用示例。
• 提供诊断工具用于故障排除。

获取帮助

1. 运行诊断：python diagnostics.py
2. 检查标准错误输出中的日志。
3. 仔细查看错误消息。
4. 验证配置文件。

鸣谢

作者：Kommandant
版本：1.0.0
许可证：MIT
状态：开发中