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