JinDaGe - pearl_mcp_server MCP Details

article

README

🚀 珍珠MCP服务器

珍珠MCP服务器是一个模型上下文协议（MCP）服务器实现，它通过标准化接口公开珍珠（Pearl）的人工智能和专家服务。该服务器允许像Claude Desktop、Cursor等MCP客户端以及其他兼容MCP的应用程序与珍珠的高级人工智能助手和人类专家进行交互。

✨ 主要特性

支持标准输入输出（stdio）和服务器发送事件（SSE）两种传输方式。
与珍珠API集成，以提供人工智能和专家协助。
具备会话管理功能，可实现连续对话。
提供多种交互模式：
- 纯人工智能模式：用于快速自动响应。
- 人工智能 - 专家模式：在人工智能辅助下由人类专家提供支持。
- 专家模式：直接由人类专家提供协助。
支持对话历史记录跟踪。
提供有状态的会话管理。

📦 安装指南

前提条件

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

安装步骤

克隆仓库：

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

创建并激活虚拟环境：

python -m venv .venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate

安装依赖项：

pip install -e .

📚 详细文档

配置

在src目录下创建一个.env文件：

PEARL_API_KEY=your-api-key-here

运行服务器

本地开发

可以使用标准输入输出（默认）或SSE传输方式启动服务器：

# 使用标准输入输出传输（默认）
pearl-mcp-server --api-key your-api-key

# 使用SSE传输并指定自定义端口
pearl-mcp-server --api-key your-api-key --transport sse --port 8000

使用远程服务器

珍珠在以下地址提供了一个托管的MCP服务器：

https://mcp.pearl.com/mcp

任何MCP客户端都可以直接使用该服务器，而无需在本地安装Python应用程序。

可用工具

服务器提供以下工具：

ask_pearl_ai
- 提供快速的纯人工智能响应，无需人工审核。
- 适用于一般查询和非关键情况。
- 参数：
  - question：用户的查询内容。
  - chat_history（可选）：之前的对话上下文。
  - session_id（可选）：用于继续对话。
ask_pearl_expert
- 提供人工智能辅助的人类专家支持。
- 适用于需要专家验证的复杂主题。
- 参数：与ask_pearl_ai相同。
ask_expert
- 直接由人类专家提供协助。
- 适用于复杂或敏感主题。
- 参数：与ask_pearl_ai相同。
get_conversation_status
- 检查活跃对话的状态。
- 参数：session_id。
get_conversation_history
- 获取完整的对话历史记录。
- 参数：session_id。

专家类别

珍珠的MCP服务器提供了广泛的专家类别。珍珠的API会根据您的查询上下文自动确定合适的专家类别，确保您能与最相关的专家取得联系。以下是主要的专家类别：

医疗保健类
- 普通医学
- 牙科健康
- 心理健康
- 营养与饮食
- 健身与运动
- 兽医医学
法律金融类
- 法律咨询
- 税务咨询
- 财务规划
- 商业法
- 劳动法
- 房地产法
技术专业类
- 软件开发
- IT支持
- 计算机维修
- 电子学
- 机械工程
- 家居改善
教育职业类
- 学术辅导
- 职业咨询
- 简历撰写
- 考试准备
- 大学招生
- 专业发展
生活个人类
- 人际关系建议
- 育儿
- 宠物护理
- 个人造型
- 室内设计
- 旅行规划

每个专家类别都可以通过ask_expert或ask_pearl_expert工具访问。您无需指定类别，只需描述您的问题，珍珠的人工智能将根据上下文自动将您的请求路由到最合适的专家类型。

与MCP客户端连接

本地连接（标准输入输出传输）

要使用标准输入输出传输方式连接到本地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包作为桥梁：

前提条件：
- Node.js 18或更高版本。
- npm（Node包管理器）。
远程服务器配置：

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

配置文件位置：
- 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
附加选项：
- 强制使用最新版本：在npx命令中添加@latest
```
"args": ["mcp-remote@latest", "https://mcp.pearl.com/sse"]
```
故障排除：
- 清除存储的凭据：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():
    # 对于标准输入输出传输
    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()
            
            # 列出可用工具
            tools = await session.list_tools()
            print(tools)
            
            # 调用珍珠人工智能
            result = await session.call_tool(
                "ask_pearl_ai", 
                {
                    "question": "What is MCP?",
                    "session_id": "optional-session-id"
                }
            )
            print(result)

asyncio.run(main())

API密钥

要获取使用此服务器的珍珠API密钥，请按以下步骤操作：

访问珍珠联系页面。
请求用于MCP服务器集成的API密钥。
按照提供的说明完成注册过程。

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

📄 许可证

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

pearl_mcp_server