更新 README：强调 MCP 接口为主要使用方式
- 更新环境变量说明，与模板保持一致（移除 LITELLM_GATEWAY_URL） - 强调 MCP 接口是主要使用方式，业务 API 为可选 - 调整使用示例顺序，MCP 接口示例放在前面 - 更新返回格式说明，详细说明 MCP JSON-RPC 格式 - 完善测试示例，重点展示 MCP 接口使用
This commit is contained in:
zhanggangyong
@@ -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 框架
|
||||
|
||||
Reference in New Issue
Block a user