👋 MCP Hello Server (Python)

简单的 Hello MCP 服务器 - 接收输入的姓名，并用韩语打招呼！

📂 结构

mcp-hello-py/
├── src/
│   ├── __init__.py       # 包初始化
│   └── server.py         # MCP 服务器
├── .env                  # 环境变量配置
├── requirements.txt      # 依赖项
├── pyproject.toml        # 项目元数据
├── Dockerfile            # Docker 配置
└── README.md             # 此文件

✨ 主要功能

• say_hello: 以 "안녕하세요, {name}님!" 的格式打招呼
• say_hello_multiple: 一次向多个人打招呼
• MCP 协议: 支持 Tools、Resources、Prompts

📦 安装

# 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

🔧 环境变量配置

创建 .env 文件：

# .env 文件内容
PORT=8080

🚀 运行

🌐 Streamable HTTP 模式 (Cloud Run, Web)

python3 src/server.py --http-stream

# 使用自定义端口
PORT=3000 python3 src/server.py --http-stream

🏗️ 架构

┌─────────────┐       ┌─────────────────┐
│  Postman /  │ ───▶  │  MCP Hello      │
│  MCP Client │       │  Server         │
│             │ ◀───  │  (Python)       │
└─────────────┘       └─────────────────┘
     HTTP                  MCP
   POST /mcp             Protocol

🧪 测试（Postman）

📋 Headers 设置（所有请求必填）

Header	Value
Content-Type	application/json
Accept	application/json

1️⃣ 初始化 MCP 服务器

• Method: POST
• URL: http://localhost:8080/mcp
• Body (raw JSON):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {"name": "postman", "version": "1.0.0"}
  }
}

2️⃣ 查看 Tool 列表

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

3️⃣ say_hello 调用

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "say_hello",
    "arguments": {"name": "김철수"}
  }
}

响应示例:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "안녕하세요, 김철수님!"}]
  }
}

4️⃣ say_hello_multiple 调用

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "say_hello_multiple",
    "arguments": {"names": ["김철수", "이영희", "박민수"]}
  }
}

响应示例:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{"type": "text", "text": "• 안녕하세요, 김철수님!\n• 안녕하세요, 이영희님!\n• 안녕하세요, 박민수님!"}]
  }
}

☁️ Cloud Run 部署

🧪 测试已部署的服务器

部署 URL 示例: https://mcp-hello-py-xxxxxx.asia-northeast3.run.app/mcp

在 Postman 中仅修改 URL 即可用同样方式测试。

🔧 环境变量配置（Cloud Run）

变量	值	说明
PORT	8080	Cloud Run 默认端口（自动设置）

🛠️ MCP Tools

say_hello

向一个人打招呼。

参数	类型	必填	说明
name	string	是	要问候的人的姓名

say_hello_multiple

同时向多个人打招呼。

参数	类型	必填	说明
names	array	是	姓名列表

📚 技术栈

• Python: 3.11+
• MCP SDK: 1.23.0+ (FastMCP)
• Pydantic: 2.x
• Uvicorn: ASGI 服务器
• Docker: 容器化

📡 传输模式

模式	使用场景	端点
stdio	Claude Desktop, MCP Inspector	stdin/stdout
Streamable HTTP	Cloud Run, Web	POST /mcp

📖 参考

• MCP Python SDK
• FastMCP 文档

📄 许可证

MIT License