# MCP Hello World 服务器
一个简单的 Model Context Protocol (MCP) 服务器实现，提供 Hello World 功能演示。
## 功能特性
- ✅ 支持多语言问候（中文/英文）
- ✅ 输入参数验证和约束
- ✅ 可配置的重复次数
- ✅ 完整的错误处理
- ✅ 符合 MCP 协议规范
- ✅ 支持本地（stdio）和远程（HTTP）部署
- ✅ Docker 容器化部署支持
- ✅ 兼容 Manus 平台注册
## 安装
### 本地开发模式（stdio）
适用于本地开发和 Cursor 集成：
```bash
# 1. 安装依赖
pip install -r requirements.txt
# 2. 验证安装
python mcp_server.py
```
### 远程部署模式（HTTP）
适用于远程部署和 Manus 注册：
```bash
# 1. 安装依赖
pip install -r requirements.txt
# 2. 启动HTTP服务器
python mcp_server_http.py
# 服务器将在 http://0.0.0.0:8000 启动
```
## 工具说明
### hello_world 工具
一个简单的问候工具，支持以下参数：
- **name** (string, 可选): 要问候的名字
- 默认值: "World"
- 约束: 1-100个字符，支持字母、数字、空格和中文
- 示例: "张三", "Alice", "World"
- **language** (string, 可选): 问候语言
- 默认值: "zh"
- 可选值: "zh" (中文) 或 "en" (英文)
- **count** (integer, 可选): 重复次数
- 默认值: 1
- 约束: 1-10次
### 使用示例
```json
{
"name": "hello_world",
"arguments": {
"name": "张三",
"language": "zh",
"count": 3
}
}
```
输出：
```
1. 你好，张三！
2. 你好，张三！
3. 你好，张三！
[元数据: {"language": "zh", "name": "张三", "count": 3}]
```
## 注册到 Agent
### 方法一：通过 Cursor 配置（推荐）
1. 打开 Cursor 设置
2. 找到 MCP 服务器配置（通常在设置 > Features > MCP Servers）
3. 添加以下配置：
```json
{
"mcpServers": {
"hello-world": {
"command": "python",
"args": [
"C:\\work\\backend\\python-mcp\\mcp_server.py"
],
"env": {}
}
}
}
```
**注意**: 请将路径替换为你的实际项目路径。
### 方法二：通过环境变量
在 Cursor 的配置文件中设置：
```json
{
"mcpServers": {
"hello-world": {
"command": "python",
"args": [
"mcp_server.py"
],
"cwd": "C:\\work\\backend\\python-mcp",
"env": {
"PYTHONPATH": "C:\\work\\backend\\python-mcp"
}
}
}
}
```
### 方法三：使用完整路径和虚拟环境
如果你使用虚拟环境：
```json
{
"mcpServers": {
"hello-world": {
"command": "C:\\work\\backend\\python-mcp\\venv\\Scripts\\python.exe",
"args": [
"C:\\work\\backend\\python-mcp\\mcp_server.py"
],
"env": {}
}
}
}
```
## 验证注册
注册成功后，你可以在 Cursor 中：
1. 打开聊天界面
2. 输入类似 "使用hello_world工具问候张三" 的指令
3. Agent 应该能够调用该工具并返回结果
---
## 远程部署指南
### 方式一：Docker 部署（推荐）
#### 1. 使用 Docker Compose（最简单）
```bash
# 启动服务
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止服务
docker-compose down
```
#### 2. 使用 Docker 命令
```bash
# 构建镜像
docker build -t hello-world-mcp:latest .
# 运行容器
docker run -d \
--name hello-world-mcp \
-p 8000:8000 \
--restart unless-stopped \
hello-world-mcp:latest
```
#### 3. 使用部署脚本
```bash
# 赋予执行权限（Linux/Mac）
chmod +x deploy.sh
# 执行部署
./deploy.sh
```
### 方式二：直接运行
```bash
# 设置环境变量
export HOST=0.0.0.0
export PORT=8000
# 启动服务器
python mcp_server_http.py
```
### 方式三：云平台部署
#### 部署到云服务器（Ubuntu/Debian）
```bash
# 1. SSH连接到服务器
ssh user@your-server.com
# 2. 安装依赖
sudo apt update
sudo apt install python3 python3-pip docker.io docker-compose
# 3. 克隆项目
git clone <your-repo-url>
cd python-mcp
# 4. 使用Docker部署
docker-compose up -d
```
#### 配置 Nginx 反向代理（可选，用于HTTPS）
创建 `/etc/nginx/sites-available/mcp-server`:
```nginx
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
启用配置并重启 Nginx:
```bash
sudo ln -s /etc/nginx/sites-available/mcp-server /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
```
配置 SSL 证书（使用 Let's Encrypt）:
```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
```
### 验证部署
部署成功后，访问以下端点验证：
- **健康检查**: `http://your-server:8000/health`
- **API信息**: `http://your-server:8000/`
- **工具列表**: `http://your-server:8000/tools`
- **MCP端点**: `http://your-server:8000/mcp`
---
## 注册到 Manus 平台
Manus 是一个 MCP 服务器管理平台，允许你将自定义 MCP 服务器注册到平台上供 Agent 使用。
### 准备工作
1. **确保服务器可访问**：
- 服务器必须通过 HTTPS 可访问（Manus 要求 HTTPS）
- 如果没有 HTTPS，可以使用 Nginx + Let's Encrypt 配置（见上方说明）
2. **获取服务器 URL**：
- 确保你的服务器地址是 `https://your-domain.com` 或 `https://your-ip:8000`
- MCP 端点地址应为: `https://your-domain.com/mcp`
### 注册步骤
1. **登录 Manus 控制台**
- 访问 Manus 平台并登录
2. **导航到集成设置**
- 进入 Manus 设置页面
- 选择"集成"或"Integrations"选项
3. **添加自定义 MCP 服务器**
- 点击"自定义 MCP 服务器"或"Custom MCP Server"
- 选择"添加服务器"或"Add Server"
4. **填写服务器信息**
- **服务器名称**: 输入描述性名称，如 "Hello World MCP"
- **服务器 URL**: 输入你的服务器 MCP 端点地址
```
https://your-domain.com/mcp
```
- **身份验证**（如需要）:
- API 密钥: 如果服务器需要 API 密钥认证
- Bearer 令牌: 如果使用 Bearer 认证
- OAuth: 如果使用 OAuth 认证
5. **测试连接**
- Manus 会自动验证是否可以与服务器通信
- 系统会尝试获取可用工具列表
- 如果连接成功，你会看到工具列表
6. **保存配置**
- 测试通过后，点击"保存"完成注册
### 配置示例
在 Manus 中添加服务器时的配置示例：
```json
{
"name": "Hello World MCP",
"url": "https://your-domain.com/mcp",
"auth": {
"type": "none" // 或 "api_key", "bearer", "oauth"
}
}
```
### 验证 Manus 注册
注册成功后：
1. **检查工具列表**
- 在 Manus 的集成页面中，你应该能看到 "hello_world" 工具
2. **测试工具调用**
- 在 Manus 中创建一个测试 Agent
- 在提示词中引用 `hello_world` 工具
- 验证工具是否正常工作
3. **查看日志**
- 检查你的服务器日志，应该能看到来自 Manus 的请求
### 安全建议
在生产环境中部署时，建议：
1. **启用 HTTPS**：
- 使用 Let's Encrypt 免费 SSL 证书
- 确保所有通信都通过 HTTPS
2. **添加身份验证**：
- 实现 API 密钥验证
- 或使用 OAuth 2.0 认证
- 限制访问来源 IP（如果可能）
3. **设置速率限制**：
- 防止 API 滥用
- 限制每个 IP 的请求频率
4. **监控和日志**：
- 记录所有请求日志
- 设置监控告警
- 定期检查服务器状态
### 故障排除
**问题1: Manus 无法连接到服务器**
解决方案：
- 检查服务器是否正常运行: `curl https://your-domain.com/health`
- 验证防火墙设置，确保端口 8000 或 443 可访问
- 检查 SSL 证书是否有效
**问题2: 工具列表获取失败**
解决方案：
- 检查 `/tools` 端点是否正常: `curl https://your-domain.com/tools`
- 查看服务器日志中的错误信息
- 验证 MCP 协议响应格式是否正确
**问题3: 工具调用失败**
解决方案：
- 测试 MCP 端点: 发送 JSON-RPC 请求到 `/mcp`
- 检查请求格式是否符合 MCP 协议规范
- 查看服务器日志了解具体错误
## 约束说明
### 输入验证约束
1. **name 参数**:
- 最小长度: 1 字符
- 最大长度: 100 字符
- 允许字符: 字母、数字、空格、中文字符
- 自动去除首尾空格
2. **language 参数**:
- 仅允许: "zh" 或 "en"
- 默认值: "zh"
3. **count 参数**:
- 最小值: 1
- 最大值: 10
- 默认值: 1
### 错误处理
- 参数验证失败时返回详细的错误信息
- 未知工具调用时抛出异常
- 所有异常都被捕获并返回友好的错误消息
## 开发
### 项目结构
```
python-mcp/
├── mcp_server.py # MCP服务器主文件（stdio模式，用于本地）
├── mcp_server_http.py # MCP服务器HTTP版本（用于远程部署）
├── requirements.txt # Python依赖
├── Dockerfile # Docker镜像构建文件
├── docker-compose.yml # Docker Compose配置
├── deploy.sh # 快速部署脚本
├── test_server.py # 测试脚本
├── config.example.json # 配置文件示例
└── README.md # 说明文档
```
### 测试
你可以使用 MCP 客户端工具测试服务器：
```bash
# 确保服务器可以正常启动
python mcp_server.py
```
## 故障排除
### 问题1: 找不到 mcp 模块
**解决方案**: 确保已安装所有依赖
```bash
pip install -r requirements.txt
```
### 问题2: Agent 无法调用工具
**解决方案**:
1. 检查配置文件路径是否正确
2. 确保 Python 可执行文件路径正确
3. 检查 Cursor 是否已重启以加载新配置
### 问题3: 参数验证失败
**解决方案**:
- 检查输入参数是否符合约束条件
- 查看错误消息中的具体提示
## 许可证
MIT License
## 贡献
欢迎提交 Issue 和 Pull Request！
