Pearl MCP Server

Pearl MCP 服务

一种模型上下文协议（MCP）服务实现，通过标准化接口提供 Pearl 的 AI 和专家服务。该服务允许 Claude Desktop、Cursor 等 MCP 兼容应用与 Pearl 的先进 AI 助手和人类专家交互。

功能

• 支持 stdio 和 SSE 两种传输方式
• 集成 Pearl API，提供 AI 和专家协助
• 会话管理，支持持续对话
• 两种交互模式：
  • AI-专家模式：由 AI 协助的人类专家支持
  • 专家模式：直接获得人类专家协助
• 对话历史跟踪
• 有状态会话管理

前提条件

• Python 3.12 或更高版本
• Pearl API 密钥（请联系 Pearl 获取 API 密钥）
• pip 或 uv 包管理器

安装

1. 克隆仓库：

git clone https://github.com/Pearl-com/pearl_mcp_server.git
cd pearl_mcp_server

2. 创建并激活虚拟环境：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. 安装依赖：

pip install -e .

配置

1. 在 src 目录中创建 .env 文件：

PEARL_API_KEY=your-api-key-here

运行服务

本地开发

使用 stdio（默认）或 SSE 传输方式启动服务：

# Using stdio transport (default)
pearl-mcp-server --api-key your-api-key

# Using SSE transport on custom port
pearl-mcp-server --api-key your-api-key --transport sse --port 8000

使用远程服务

Pearl 提供托管的 MCP 服务：

https://mcp.pearl.com/mcp

无需在本地安装 Python 应用，即可将其直接用于任何 MCP 客户端。

可用工具

该服务提供以下工具：

1. ask_pearl_expert

   • 由 AI 协助的人类专家支持
   • 适用于需要专家核实的复杂主题
   • 参数：与 ask_pearl_ai 相同

2. ask_expert

   • 直接获得人类专家协助
   • 适用于复杂或敏感主题
   • 参数：与 ask_pearl_ai 相同

3. get_conversation_status

   • 查看活动对话的状态
   • 参数：session_id

4. get_conversation_history

   • 获取完整的对话历史
   • 参数：session_id

专家类别

Pearl 的 MCP 服务提供多种专家类别。Pearl API 会根据你的问题上下文自动确定合适的专家类别，确保为你匹配最相关的专家。

以下是主要的专业领域类别：

• 医疗与健康

  • 全科医学
  • 牙科健康
  • 心理健康
  • 营养与饮食
  • 健身与锻炼
  • 兽医学

• 法律与金融

  • 法律建议
  • 税务咨询
  • 财务规划
  • 商法
  • 劳动法
  • 房地产法

• 技术与职业

  • 软件开发
  • IT 支持
  • 计算机维修
  • 电子技术
  • 机械工程
  • 家居装修

• 教育与职业发展

  • 学业辅导
  • 职业咨询
  • 简历撰写
  • 考试备考
  • 大学入学申请
  • 职业发展

• 生活方式与个人事务

  • 人际关系建议
  • 育儿
  • 宠物护理
  • 个人形象设计
  • 室内设计
  • 旅行规划

每种专家类别都可以通过 ask_expert 或 ask_pearl_expert 工具访问。无需指定类别，只需描述你的问题或困难，Pearl 的 AI 就会根据上下文自动将请求转给最合适的专家类型。

连接 MCP 客户端

本地连接（stdio 传输）

要使用 stdio 传输方式连接本地 MCP 服务，请将以下配置添加到 MCP 客户端：

{
    "pearl-mcp-server": {
        "type": "stdio",
        "command": "pearl-mcp-server",
        "args": ["--api-key", "your-api-key"],
        "env": {
            "PEARL_API_KEY": "Your Pearl Api Key"
        }
    }
}

使用 mcp-remote 进行远程连接

某些 MCP 客户端不支持直接连接远程 MCP 服务。对于这些客户端，可以使用 mcp-remote 包作为桥接工具：

1. 前提条件：

   • Node.js 18 或更高版本
   • npm（Node 包管理器）

2. 远程服务配置：

{
    "mcpServers": {
        "pearl-remote": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.pearl.com/sse"
            ]
        }
    }
}

3. 配置文件位置：

   • Claude Desktop：
     • Windows：%APPDATA%\Claude\claude_desktop_config.json
     • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Cursor：~/.cursor/mcp.json
   • Windsurf：~/.codeium/windsurf/mcp_config.json

4. 其他选项：

   • 强制使用最新版本：在 npx 命令中添加 @latest

   "args": ["mcp-remote@latest", "https://mcp.pearl.com/sse"]
   

5. 故障排除：

   • 清除已存储的凭据：rm -rf ~/.mcp-auth
   • 查看日志：
     • Windows（PowerShell）：Get-Content "$env:APPDATA\Claude\Logs\mcp.log" -Wait -Tail 20
     • macOS/Linux：tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
   • 测试连接：npx mcp-remote-client https://mcp.pearl.com/sse

自定义 Python 客户端

import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

async def main():
    # For stdio transport
    async with stdio_client(
        StdioServerParameters(command="pearl-mcp-server", args=["--api-key", "your-api-key"])
    ) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print(tools)
            
            # Call Pearl API
            result = await session.call_tool(
                "ask_pearl_expert", 
                {
                    "question": "What is MCP?",
                    "session_id": "optional-session-id"
                }
            )
            print(result)

asyncio.run(main())

API 密钥

如需使用此服务，请按以下步骤获取 Pearl API 密钥：

1. 访问 Pearl 联系页面
2. 申请用于 MCP 服务集成的 API 密钥
3. 按照提供的说明完成注册流程

请妥善保管 API 密钥，切勿将其提交到版本控制系统中。

许可证

本项目采用 Apache License 2.0 许可证，详情请参阅 LICENSE 文件。