xiaohei/huoke
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
huoke/README.md
T
zhanggangyong 6caa0a7481 更新 README：强调 MCP 接口为主要使用方式 
- 更新环境变量说明，与模板保持一致（移除 LITELLM_GATEWAY_URL）
- 强调 MCP 接口是主要使用方式，业务 API 为可选
- 调整使用示例顺序，MCP 接口示例放在前面
- 更新返回格式说明，详细说明 MCP JSON-RPC 格式
- 完善测试示例，重点展示 MCP 接口使用
2026-01-24 09:15:17 +00:00

7.7 KiB
Raw Permalink Blame History

获客 Agent

基于 Pydantic AI 和 FastMCP 的获客助手，可以通过 LinkedIn 个人资料 URL 查找工作邮箱地址。

功能

  • find_email_from_linkedin - 通过 LinkedIn 个人资料 URL 查找工作邮箱地址
    • 使用 RapidAPI Fresh LinkedIn to Email Finder 服务
    • 返回邮箱地址、姓名、公司、职位等完整信息

环境变量

变量 必需 默认值 说明
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
MODEL_NAME 否 taiji/gpt-4o-mini 模型名称
LITELLM_MODEL 否 taiji/gpt-4o-mini 模型名称（兼容）
API_HOST 否 0.0.0.0 服务监听地址
API_PORT 否 8000 服务端口

硬编码配置（无需环境变量）：

  • RapidAPI Key（Fresh LinkedIn to Email Finder）

启动

本地运行

python run_api_server.py

Docker 运行

# 构建镜像
docker build -t huoke:latest .

# 运行容器
docker run -d -p 8000:8000 \
  -e OPENAI_API_KEY=your-api-key \
  -e LITELLM_MODEL=taiji/gpt-4o-mini \
  --name huoke \
  huoke:latest

API

MCP 端点（主要使用方式）

本 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 - 健康检查端点

使用示例

MCP 接口（主要使用方式）

1. 列出可用工具

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

响应示例：

{
  "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. 调用查找邮箱工具

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "api-key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "find_email_from_linkedin",
      "arguments": {
        "linkedin_url": "https://www.linkedin.com/in/williamhgates"
      }
    }
  }'

响应示例：

{
  "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 可以通过以下方式传递：

  • Header: api-key: your-api-key
  • Header: api_key: your-api-key
  • Header: Authorization: Bearer your-api-key

业务 API（可选）

如果需要使用 REST API 方式调用：

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 格式：

{
  "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 字符串）：

{
  "success": true,
  "linkedin_url": "https://www.linkedin.com/in/williamhgates",
  "full_name": "Bill Gates",
  "email_found": true,
  "email": "bill.gates@gatesfoundation.org",
  "email_status": "VALID",
  "email_type": "professional",
  "company": "Gates Foundation",
  "job_title": "Co-chair",
  "full_data": {
    "success": true,
    "response": {
      "full_name": "Bill Gates",
      "location": "Seattle, Washington, United States",
      "job_title": "Co-chair",
      "email": {
        "is_found": true,
        "email": "bill.gates@gatesfoundation.org",
        "status": "VALID",
        "email_deliverability": "DELIVERABLE",
        "type": "professional",
        "confidence": "0.8"
      },
      "company": {
        "name": "Gates Foundation",
        "industry": "Non-profit Organizations"
      },
      "work_experience": [...]
    }
  }
}

失败响应

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32603,
    "message": "无效的 LinkedIn URL，格式应为：https://www.linkedin.com/in/username"
  }
}

或

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32001,
    "message": "缺少 API Key"
  }
}

字段说明

字段 类型 说明
success boolean 请求是否成功
linkedin_url string 输入的 LinkedIn URL
full_name string 完整姓名
email_found boolean 是否找到邮箱
email string 邮箱地址（如果找到）
email_status string 邮箱状态（VALID/INVALID）
email_type string 邮箱类型（professional/personal）
company string 公司名称
job_title string 职位
full_data object 完整的 API 响应数据

完整测试示例

1. 健康检查

curl http://localhost:8000/health

响应：

{
  "status": "healthy",
  "service": "获客 Agent API"
}

2. 查看服务信息

curl http://localhost:8000/

响应：

{
  "service": "获客 Agent API",
  "status": "running",
  "tools": ["find_email_from_linkedin"]
}

3. MCP 接口测试（推荐）

3.1 列出工具

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }' | python3 -m json.tool

3.2 调用工具查找邮箱

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "api-key: sk-test-key-123" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "find_email_from_linkedin",
      "arguments": {
        "linkedin_url": "https://www.linkedin.com/in/williamhgates"
      }
    }
  }' | python3 -m json.tool

4. 业务 API 测试（可选）

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 框架
  • Pydantic AI - AI Agent 框架
  • FastMCP - MCP 服务器实现
  • RapidAPI - Fresh LinkedIn to Email Finder API
  • Docker - 容器化部署
Reference in New Issue View Git Blame Copy Permalink