Deepin MCP

Deepin MCP

一个用于连接到 MCP（Machine Conversation Protocol）服务和使用 OpenAI 大模型与其交互的客户端。

概览

这个 MCP 客户端允许你：

1. 连接到一个 MCP 服务（Python 或 JavaScript）
2. 列出并使用服务提供的可用工具
3. 使用自然语言查询与服务交互
4. 使用 OpenAI 的大模型处理响应
5. 自动规划和执行复杂任务

设置

前置条件

• Python 3.12 或更高版本
• OpenAI API 密钥
• 要连接的 MCP 服务

安装 UV（推荐）

UV 是一个快速、可靠的 Python 包安装程序和解析器。推荐用于本项目：

1. 安装 UV：

   # Unix (macOS, Linux)
   curl -LsSf https://astral.sh/uv/install.sh | bash
   
   # Windows (PowerShell)
   irm https://astral.sh/uv/install.ps1 | iex
   

2. 验证安装：

   uv --version
   

如需更多安装选项，请访问 UV 的官方文档。

安装

1. 克隆此仓库

2. 创建虚拟环境：

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. 安装依赖：

   pip install -e .
   

   或使用 UV（推荐）：

   uv venv
   uv pip install -e .
   

4. 创建一个 .env 文件，包含你的 API 密钥和配置：

   # OpenAI API Configuration
   OPENAI_API_KEY=your_openai_api_key
   BASE_URL=https://api.openai.com/v1  # Optional: Use your own OpenAI API proxy
   MODEL=gpt-3.5-turbo  # Optional: Specify the model to use
   

5. 安装所需的依赖：

   使用 UV（推荐）：

   # Install core dependencies
   uv pip install -e .
   
   # Or install individual packages
   uv add openai  # OpenAI API client
   uv add python-dotenv  # For loading environment variables
   uv add mcp  # Machine Conversation Protocol library
   

   使用标准 pip：

   pip install openai python-dotenv mcp
   

   每种服务类型可能需要额外的依赖：

   # For JavaScript servers
   uv add node-fetch  # If connecting to JavaScript MCP servers
   
   # For additional functionality
   uv add asyncio  # For asynchronous operations
   uv add pathlib  # For file path handling
   

使用

UV 快速开始

使用 UV 快速启动和运行：

# Clone the repository
git clone https://github.com/yourusername/deepin-mcp-python.git
cd deepin-mcp-python

# Install UV
curl -sSf https://astral.sh/uv/install.sh | bash

# Create a virtual environment and install dependencies
uv venv
uv pip install -e .

# Create .env file (replace with your actual API key)
echo "OPENAI_API_KEY=your_openai_api_key" > .env
echo "MODEL=gpt-3.5-turbo" >> .env

# Run the client with bash server
uv run python client.py servers/bash_server.py

# Or run the task planning system
uv run python main.py

基本用法

通过指定 MCP 服务脚本的路径来运行客户端：

python client.py path/to/your/server_script.py

或使用 UV：

uv run python client.py path/to/your/server_script.py

对于 JavaScript 服务：

python client.py path/to/your/server_script.js

或使用 UV：

uv run python client.py path/to/your/server_script.js

任务规划系统

该项目包括一个强大的任务规划系统，可以：

1. 将复杂的用户请求分解为顺序任务
2. 使用 MCP 服务自动执行任务
3. 提供详细的执行摘要

要使用任务规划系统：

python main.py

或使用 UV（推荐）：

uv run python main.py

你也可以指定自定义服务路径：

python main.py --server path/to/your/server_script.py

或检查版本信息：

python main.py --version

主入口点

该项目提供了一个主入口点（main.py），作为应用程序的集中入口：

python main.py

或使用 UV（推荐）：

uv run python main.py

主入口点：

• 初始化任务规划系统
• 提供版本信息和系统描述
• 优雅地处理异常
• 让应用程序更加用户友好
• 允许使用 --server 选项指定自定义服务路径

用法示例：

$ python main.py

====== Deepin MCP 任务规划系统 ======
版本: 1.0.0
描述: 这是一个基于MCP协议的任务规划执行系统
======================================

欢迎使用任务规划执行系统
这个系统会将您的请求拆解为多个任务，并依次执行

已成功连接到服务器: /home/user/deepin-mcp-python/servers/bash_server.py

请输入您的请求 (输入'quit'退出): 

交互示例：

请输入您的请求 (输入'quit'退出): Create a new directory called 'projects' and copy all .txt files from 'documents' to it

正在分析您的请求...
已将您的请求拆解为 3 个任务:
1. Create a new directory called 'projects'
2. List all .txt files in the 'documents' directory
3. Copy all .txt files from 'documents' to 'projects'

是否执行这些任务? (y/n): y

[Task execution progress will be shown here]

执行总结:
[Detailed summary of the executed tasks will be shown here]

任务规划系统特别适用于：

• 复杂的文件操作
• 多步系统配置
• 自动化工作流执行
• 批处理任务

交互模式

连接后，你可以在交互提示符中输入查询。客户端会：

1. 将你的查询发送给大模型
2. 处理模型请求的任何工具调用
3. 返回最终响应

输入 quit 退出交互模式。

可用服务

天气服务

weather_server.py 提供了一个 MCP 工具，用于查询指定城市的天气信息。

python client.py weather_server.py

或使用 UV：

uv run python client.py weather_server.py

查询示例："查询北京的天气"

依赖：

uv add requests  # For HTTP requests to weather APIs

文件服务

file_server.py 提供了 MCP 工具，用于执行文件操作，如打开、复制、移动、重命名、删除和创建文件。

python client.py file_server.py

或使用 UV：

uv run python client.py file_server.py

查询示例："创建一个名为 test.txt 的文件"

依赖：

uv add pathlib  # For file path handling

Bash 服务

bash_server.py 提供了 MCP 工具，用于执行 Linux bash 命令。

python client.py bash_server.py

或使用 UV：

uv run python client.py bash_server.py

查询示例："列出当前目录下的所有文件"

依赖：

uv add shlex  # For shell command parsing

开发

要扩展或修改此客户端：

1. MCPClient 类处理主要功能
2. process_query 方法使用大模型处理查询
3. TaskPlanner 类将复杂请求分解为任务
4. 主入口点（main.py）提供用户友好的界面
5. 整个应用程序中实现了错误处理，确保鲁棒性

故障排除

如果遇到问题：

1. 检查 .env 中的 API 密钥
2. 验证服务脚本路径是否正确
3. 确保服务正确实现了 MCP 协议
4. 检查控制台输出中的错误消息
5. 确保已安装所需的依赖项

许可证

本项目在 MIT 许可证下提供。

构建可执行二进制文件

你可以构建独立的二进制可执行文件，无需 Python 安装即可分发：

使用构建脚本

项目包含一个简化流程的构建脚本：

# Make the build script executable
chmod +x build.sh

# Run the build script
./build.sh

可执行文件将在 dist 目录中创建为 deepin-mcp。

手动构建过程

如果你更喜欢手动构建：

1. 使用 UV 安装 PyInstaller：

   uv pip install pyinstaller
   

2. 构建可执行文件：

   pyinstaller --clean deepin-mcp.spec
   

3. 可执行文件将位于 dist/deepin-mcp

运行可执行文件

构建完成后，你可以直接运行可执行文件：

# Run with default settings
./dist/deepin-mcp

# Check version
./dist/deepin-mcp --version

# Specify a custom server
./dist/deepin-mcp --server path/to/your/server_script.py

可执行文件包含所有必要的依赖项，可以分发到未安装 Python 的系统。

服务发现和选择

应用程序自动发现和加载可用的服务脚本：

1. 启动应用程序时，它会在以下位置搜索服务脚本：

   • 当前工作目录
   • servers 子目录
   • 应用程序的可执行文件目录
   • 可执行文件目录内的 servers 子目录

2. 可用服务可以使用以下命令列出：

   ./deepin-mcp --list-servers
   

3. 可以在启动时选择特定服务：

   ./deepin-mcp --server bash
   # or by path
   ./deepin-mcp --server /path/to/custom_server.py
   

4. 可以在运行时通过在提示符处输入 switch 来切换服务。

服务部署

当应用程序打包为二进制可执行文件时：

1. 服务脚本自动部署到可执行文件旁边的 servers 目录
2. 应用程序自动发现并加载这些服务
3. 每个服务都附带一个包装脚本（例如 bash_server.wrapper.py），确保正确加载依赖项
4. 在 server_env 目录中创建了一个包含所有必要依赖项（包括 mcp 模块）的专用 Python 环境
5. 可以通过将自定义服务放在 servers 目录中（文件名包含 "server"，例如 custom_server.py）来添加自定义服务
6. run_server.sh 辅助脚本可用于直接运行任何服务

直接运行服务

你可以使用提供的辅助脚本直接运行服务：

# Run a server by name
./dist/deepin-mcp/run_server.sh bash

# Run a server by file name
./dist/deepin-mcp/run_server.sh bash_server.py

# Run a server by full path
./dist/deepin-mcp/run_server.sh /path/to/your/custom_server.py

这对以下情况特别有用：

• 独立测试服务功能
• 在单独的终端中运行服务
• 将自定义服务脚本与应用程序一起使用

服务环境结构

打包的应用程序包含一个完整的服务环境：

dist/deepin-mcp/
├── deepin-mcp          # Main executable
├── run_server.sh       # Server helper script
├── server_env/         # Python environment for servers
│   ├── mcp/            # MCP module and dependencies
│   ├── openai/         # OpenAI module
│   └── ...             # Other dependencies
└── servers/
    ├── bash_server.py          # Original server script
    ├── bash_server.wrapper.py  # Wrapper that configures path
    ├── file_server.py          # Original server script
    ├── file_server.wrapper.py  # Wrapper that configures path
    └── ...

添加自定义服务

要向打包的应用程序添加自定义服务：

1. 按照 MCP 协议创建服务脚本
2. 将其放在打包应用程序的 servers 目录中
3. 创建一个遵循与包含的包装脚本相同模式的包装脚本，或在 dist/deepin-mcp 目录内运行以下命令：

cat > servers/myserver_server.wrapper.py << EOF
#!/usr/bin/env python
# Wrapper script for myserver_server.py
import os
import sys

# Add the server_env to the Python path
server_env_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'server_env'))
sys.path.insert(0, server_env_path)

# Import the actual server code
server_file = os.path.abspath(os.path.join(os.path.dirname(__file__), 'myserver_server.py'))
with open(server_file, 'r') as f:
    server_code = f.read()

# Execute the server code with the modified path
exec(server_code)
EOF
chmod +x servers/myserver_server.wrapper.py

4. 使用辅助脚本运行自定义服务，或直接从主应用程序中使用它