Pearl MCP Server

Pearl MCP サーバー

Pearl の AI サービスと専門家サービスを標準化されたインターフェースで提供する、Model Context Protocol（MCP）サーバーの実装です。このサーバーを使用すると、Claude Desktop、Cursor などの MCP 対応アプリケーションといった MCP クライアントから、Pearl の高度な AI アシスタントと人間の専門家を利用できます。

機能

• stdio と SSE の両方のトランスポートに対応
• AI と専門家による支援のための Pearl API との統合
• 継続的な会話のためのセッション管理
• 2 つの対話モード：
  • AI-Expert モード：AI の支援を受けた人間の専門家によるサポート
  • Expert モード：人間の専門家による直接的な支援
• 会話履歴の追跡
• ステートフルなセッション管理

前提条件

• Python 3.12 以降
• Pearl API キー（API キーを取得するには Pearl にお問い合わせください）
• 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 Package Manager）

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 ファイルを参照してください。