xiaohei/huoke
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新 README：强调 MCP 接口为主要使用方式

Browse Source 
- 更新环境变量说明，与模板保持一致（移除 LITELLM_GATEWAY_URL）
- 强调 MCP 接口是主要使用方式，业务 API 为可选
- 调整使用示例顺序，MCP 接口示例放在前面
- 更新返回格式说明，详细说明 MCP JSON-RPC 格式
- 完善测试示例，重点展示 MCP 接口使用
This commit is contained in:
zhanggangyong
2026-01-24 09:15:17 +00:00
parent d89edd3e74
commit 6caa0a7481
1 changed files with 134 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+134 -35
View File
@@ -12,10 +12,12 @@
| 变量 | 必需 | 默认值 | 说明 | | 变量 | 必需 | 默认值 | 说明 |
|------|------|--------|------| |------|------|--------|------|
| OPENAI_BASE_URL | 否 | LiteLLM Gateway URL | LLM Gateway URL | | OPENAI_BASE_URL | 否 | LiteLLM Gateway URL | LLM Gateway URL（优先） |
| LITELLM_GATEWAY_URL | 否 | 同上 | 兼容变量名 | | LLM_BASE_URL | 否 | LiteLLM Gateway URL | LLM Gateway URL（备选） |
| OPENAI_API_KEY | 否 | sk | LLM API Key | | 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 | 服务端口 | | API_PORT | 否 | 8000 | 服务端口 |
**硬编码配置**（无需环境变量）： **硬编码配置**（无需环境变量）：
@@ -45,23 +47,33 @@ docker run -d -p 8000:8000 \
## API ## API
### MCP 端点 ### MCP 端点（主要使用方式）
- `POST /mcp` - MCP HTTP 端点
- `GET /mcp/sse` - MCP SSE 端点
- `POST /mcp/sse` - MCP SSE POST 端点
### 业务 API 本 Agent 主要通过 **MCP (Model Context Protocol)** 接口提供服务。
- `POST /api/v1/find_email` - 查找邮箱（需要 API Key）
- **`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 ```bash
curl -X POST http://localhost:8000/mcp \ 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 ```bash
curl -X POST http://localhost:8000/mcp \ curl -X POST http://localhost:8000/mcp \
@@ -92,15 +130,20 @@ curl -X POST http://localhost:8000/mcp \
}' }'
``` ```
### 2. REST API 调用 **响应示例：**
```json
```bash {
curl -X POST http://localhost:8000/api/v1/find_email \ "jsonrpc": "2.0",
-H "Content-Type: application/json" \ "id": 2,
-H "api-key: your-api-key" \ "result": {
-d '{ "content": [
"linkedin_url": "https://www.linkedin.com/in/williamhgates" {
}' "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 可以通过以下方式传递： **注意**：API Key 可以通过以下方式传递：
@@ -108,9 +151,43 @@ curl -X POST http://localhost:8000/api/v1/find_email \
- Header: `api_key: your-api-key` - Header: `api_key: your-api-key`
- Header: `Authorization: Bearer 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 ```json
{ {
@@ -147,12 +224,16 @@ curl -X POST http://localhost:8000/api/v1/find_email \
} }
``` ```
### 失败响应 #### 失败响应
```json ```json
{ {
"success": false, "jsonrpc": "2.0",
"error": "无效的 LinkedIn URL，格式应为：https://www.linkedin.com/in/username" "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 ```json
{ {
"success": false, "jsonrpc": "2.0",
"error": "API 错误 404: Endpoint does not exist" "id": 2,
"error": {
"code": -32001,
"message": "缺少 API Key"
}
} }
``` ```
@@ -211,18 +296,21 @@ curl http://localhost:8000/
} }
``` ```
### 3. 查找邮箱（REST API） ### 3. MCP 接口测试（推荐）
#### 3.1 列出工具
```bash ```bash
curl -X POST http://localhost:8000/api/v1/find_email \ curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "api-key: sk-test-key-123" \
-d '{ -d '{
"linkedin_url": "https://www.linkedin.com/in/williamhgates" "jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}' | python3 -m json.tool }' | python3 -m json.tool
``` ```
### 4. 查找邮箱（MCP） #### 3.2 调用工具查找邮箱
```bash ```bash
curl -X POST http://localhost:8000/mcp \ 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" \ -H "api-key: sk-test-key-123" \
-d '{ -d '{
"jsonrpc": "2.0", "jsonrpc": "2.0",
"id": 1, "id": 2,
"method": "tools/call", "method": "tools/call",
"params": { "params": {
"name": "find_email_from_linkedin", "name": "find_email_from_linkedin",
@@ -241,6 +329,17 @@ curl -X POST http://localhost:8000/mcp \
}' | python3 -m json.tool }' | 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 框架 - **FastAPI** - Web 框架