Pearl MCP Server

🚀 珍珠MCP服務器

珍珠MCP服務器是一個模型上下文協議（MCP）服務器實現，它通過標準化接口公開珍珠（Pearl）的人工智能和專家服務。該服務器允許像Claude Desktop、Cursor等MCP客戶端以及其他兼容MCP的應用程序與珍珠的高級人工智能助手和人類專家進行交互。

✨ 主要特性

• 支持標準輸入輸出（stdio）和服務器發送事件（SSE）兩種傳輸方式。
• 與珍珠API集成，以提供人工智能和專家協助。
• 具備會話管理功能，可實現連續對話。
• 提供多種交互模式：
  • 純人工智能模式：用於快速自動響應。
  • 人工智能 - 專家模式：在人工智能輔助下由人類專家提供支持。
  • 專家模式：直接由人類專家提供協助。
• 支持對話歷史記錄跟蹤。
• 提供有狀態的會話管理。

📦 安裝指南

前提條件

• Python 3.12 或更高版本。
• 珍珠API密鑰（請聯繫珍珠獲取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  # 在Windows上：.venv\Scripts\activate

3. 安裝依賴項：

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應用程序。

可用工具

服務器提供以下工具：

1. ask_pearl_ai
   • 提供快速的純人工智能響應，無需人工審核。
   • 適用於一般查詢和非關鍵情況。
   • 參數：
     • question：用戶的查詢內容。
     • chat_history（可選）：之前的對話上下文。
     • session_id（可選）：用於繼續對話。
2. ask_pearl_expert
   • 提供人工智能輔助的人類專家支持。
   • 適用於需要專家驗證的複雜主題。
   • 參數：與ask_pearl_ai相同。
3. ask_expert
   • 直接由人類專家提供協助。
   • 適用於複雜或敏感主題。
   • 參數：與ask_pearl_ai相同。
4. get_conversation_status
   • 檢查活躍對話的狀態。
   • 參數：session_id。
5. 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包作為橋樑：

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():
    # 對於標準輸入輸出傳輸
    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密鑰，請按以下步驟操作：

1. 訪問珍珠聯繫頁面。
2. 請求用於MCP服務器集成的API密鑰。
3. 按照提供的說明完成註冊過程。

請妥善保管您的API密鑰，切勿將其提交到版本控制系統。

📄 許可證

本項目採用Apache License 2.0許可 - 詳情請參閱LICENSE文件。