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 配置（推荐）

1. 打开 Cursor 设置
2. 找到 MCP 服务器配置（通常在设置 > Features > MCP Servers）
3. 添加以下配置：

{
  "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 中：

1. 打开聊天界面
2. 输入类似 "使用hello_world工具问候张三" 的指令
3. 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 使用。

准备工作

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 中添加服务器时的配置示例：

{
  "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 客户端工具测试服务器：

# 确保服务器可以正常启动
python mcp_server.py

故障排除

问题1: 找不到 mcp 模块

解决方案: 确保已安装所有依赖

pip install -r requirements.txt

问题2: Agent 无法调用工具

解决方案:

1. 检查配置文件路径是否正确
2. 确保 Python 可执行文件路径正确
3. 检查 Cursor 是否已重启以加载新配置

问题3: 参数验证失败

解决方案:

• 检查输入参数是否符合约束条件
• 查看错误消息中的具体提示

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！