From 6caa0a74816d7a9242b5393df6abb33fa9e8024c Mon Sep 17 00:00:00 2001 From: zhanggangyong Date: Sat, 24 Jan 2026 09:15:17 +0000 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README=EF=BC=9A=E5=BC=BA?= =?UTF-8?q?=E8=B0=83=20MCP=20=E6=8E=A5=E5=8F=A3=E4=B8=BA=E4=B8=BB=E8=A6=81?= =?UTF-8?q?=E4=BD=BF=E7=94=A8=E6=96=B9=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新环境变量说明，与模板保持一致（移除 LITELLM_GATEWAY_URL） - 强调 MCP 接口是主要使用方式，业务 API 为可选 - 调整使用示例顺序，MCP 接口示例放在前面 - 更新返回格式说明，详细说明 MCP JSON-RPC 格式 - 完善测试示例，重点展示 MCP 接口使用 --- README.md | 169 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 134 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 4bcb60c..d15e8c1 100644 --- a/README.md +++ b/README.md @@ -12,10 +12,12 @@ | 变量 | 必需 | 默认值 | 说明 | |------|------|--------|------| -| OPENAI_BASE_URL | 否 | LiteLLM Gateway URL | LLM Gateway URL | -| LITELLM_GATEWAY_URL | 否 | 同上 | 兼容变量名 | +| OPENAI_BASE_URL | 否 | LiteLLM Gateway URL | LLM Gateway URL（优先） | +| LLM_BASE_URL | 否 | LiteLLM Gateway URL | LLM Gateway URL（备选） | | OPENAI_API_KEY | 否 | sk | LLM API Key | -| LITELLM_MODEL | 否 | taiji/gpt-4o-mini | 模型名称 | +| MODEL_NAME | 否 | taiji/gpt-4o-mini | 模型名称 | +| LITELLM_MODEL | 否 | taiji/gpt-4o-mini | 模型名称（兼容） | +| API_HOST | 否 | 0.0.0.0 | 服务监听地址 | | API_PORT | 否 | 8000 | 服务端口 | **硬编码配置**（无需环境变量）： @@ -45,23 +47,33 @@ docker run -d -p 8000:8000 \ ## API -### MCP 端点 -- `POST /mcp` - MCP HTTP 端点 -- `GET /mcp/sse` - MCP SSE 端点 -- `POST /mcp/sse` - MCP SSE POST 端点 +### MCP 端点（主要使用方式） -### 业务 API -- `POST /api/v1/find_email` - 查找邮箱（需要 API Key） +本 Agent 主要通过 **MCP (Model Context Protocol)** 接口提供服务。 + +- **`POST /mcp`** - MCP HTTP 端点（主要使用） + - `tools/list` - 列出所有可用工具 + - `tools/call` - 调用工具（需要 API Key） + - `initialize` - 初始化 MCP 会话 + - `ping` - 心跳检测 + +- **`GET /mcp/sse`** - MCP SSE 端点（Server-Sent Events） +- **`POST /mcp/sse`** - MCP SSE POST 端点 + +### 业务 API（可选） + +- **`POST /api/v1/query`** - 业务 API 端点（可选，需要 API Key） ### 健康检查 -- `GET /` - 服务信息 -- `GET /health` - 健康检查 + +- **`GET /`** - 服务信息和可用工具列表 +- **`GET /health`** - 健康检查端点 ## 使用示例 -### 1. MCP 调用 +### MCP 接口（主要使用方式） -#### 列出可用工具 +#### 1. 列出可用工具 ```bash curl -X POST http://localhost:8000/mcp \ @@ -73,7 +85,33 @@ curl -X POST http://localhost:8000/mcp \ }' ``` -#### 调用查找邮箱工具 +**响应示例：** +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "tools": [ + { + "name": "find_email_from_linkedin", + "description": "通过 LinkedIn 个人资料 URL 查找工作邮箱地址", + "inputSchema": { + "type": "object", + "properties": { + "linkedin_url": { + "type": "string", + "description": "LinkedIn 个人资料 URL" + } + }, + "required": ["linkedin_url"] + } + } + ] + } +} +``` + +#### 2. 调用查找邮箱工具 ```bash curl -X POST http://localhost:8000/mcp \ @@ -92,15 +130,20 @@ curl -X POST http://localhost:8000/mcp \ }' ``` -### 2. REST API 调用 - -```bash -curl -X POST http://localhost:8000/api/v1/find_email \ - -H "Content-Type: application/json" \ - -H "api-key: your-api-key" \ - -d '{ - "linkedin_url": "https://www.linkedin.com/in/williamhgates" - }' +**响应示例：** +```json +{ + "jsonrpc": "2.0", + "id": 2, + "result": { + "content": [ + { + "type": "text", + "text": "{\n \"success\": true,\n \"linkedin_url\": \"https://www.linkedin.com/in/williamhgates\",\n \"full_name\": \"Bill Gates\",\n \"email_found\": true,\n \"email\": \"bill.gates@gatesfoundation.org\",\n ...\n}" + } + ] + } +} ``` **注意**：API Key 可以通过以下方式传递： @@ -108,9 +151,43 @@ curl -X POST http://localhost:8000/api/v1/find_email \ - Header: `api_key: your-api-key` - Header: `Authorization: Bearer your-api-key` +### 业务 API（可选） + +如果需要使用 REST API 方式调用： + +```bash +curl -X POST http://localhost:8000/api/v1/query \ + -H "Content-Type: application/json" \ + -H "api-key: your-api-key" \ + -d '{ + "query": "https://www.linkedin.com/in/williamhgates" + }' +``` + ## 返回格式 -### 成功响应 +### MCP 接口返回格式 + +#### 成功响应 + +MCP 接口返回 JSON-RPC 2.0 格式： + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "result": { + "content": [ + { + "type": "text", + "text": "{\n \"success\": true,\n \"linkedin_url\": \"https://www.linkedin.com/in/williamhgates\",\n \"full_name\": \"Bill Gates\",\n \"email_found\": true,\n \"email\": \"bill.gates@gatesfoundation.org\",\n \"email_status\": \"VALID\",\n \"email_type\": \"professional\",\n \"company\": \"Gates Foundation\",\n \"job_title\": \"Co-chair\",\n \"full_data\": {...}\n}" + } + ] + } +} +``` + +其中 `result.content[0].text` 包含实际的工具返回结果（JSON 字符串）： ```json { @@ -147,12 +224,16 @@ curl -X POST http://localhost:8000/api/v1/find_email \ } ``` -### 失败响应 +#### 失败响应 ```json { - "success": false, - "error": "无效的 LinkedIn URL，格式应为：https://www.linkedin.com/in/username" + "jsonrpc": "2.0", + "id": 2, + "error": { + "code": -32603, + "message": "无效的 LinkedIn URL，格式应为：https://www.linkedin.com/in/username" + } } ``` @@ -160,8 +241,12 @@ curl -X POST http://localhost:8000/api/v1/find_email \ ```json { - "success": false, - "error": "API 错误 404: Endpoint does not exist" + "jsonrpc": "2.0", + "id": 2, + "error": { + "code": -32001, + "message": "缺少 API Key" + } } ``` @@ -211,18 +296,21 @@ curl http://localhost:8000/ } ``` -### 3. 查找邮箱（REST API） +### 3. MCP 接口测试（推荐） + +#### 3.1 列出工具 ```bash -curl -X POST http://localhost:8000/api/v1/find_email \ +curl -X POST http://localhost:8000/mcp \ -H "Content-Type: application/json" \ - -H "api-key: sk-test-key-123" \ -d '{ - "linkedin_url": "https://www.linkedin.com/in/williamhgates" + "jsonrpc": "2.0", + "id": 1, + "method": "tools/list" }' | python3 -m json.tool ``` -### 4. 查找邮箱（MCP） +#### 3.2 调用工具查找邮箱 ```bash curl -X POST http://localhost:8000/mcp \ @@ -230,7 +318,7 @@ curl -X POST http://localhost:8000/mcp \ -H "api-key: sk-test-key-123" \ -d '{ "jsonrpc": "2.0", - "id": 1, + "id": 2, "method": "tools/call", "params": { "name": "find_email_from_linkedin", @@ -241,6 +329,17 @@ curl -X POST http://localhost:8000/mcp \ }' | python3 -m json.tool ``` +### 4. 业务 API 测试（可选） + +```bash +curl -X POST http://localhost:8000/api/v1/query \ + -H "Content-Type: application/json" \ + -H "api-key: sk-test-key-123" \ + -d '{ + "query": "https://www.linkedin.com/in/williamhgates" + }' | python3 -m json.tool +``` + ## 技术栈 - **FastAPI** - Web 框架