# 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！