Pearl MCP Server

🚀 Pearl MCP Server

Pearl MCP Serverは、標準化されたインターフェースを通じてPearlのAIおよびエキスパートサービスを公開する、Model Context Protocol (MCP) サーバの実装です。このサーバを使用すると、Claude DesktopやCursorなどのMCPクライアントや、その他のMCP互換アプリケーションが、Pearlの高度なAIアシスタントおよび人間のエキスパートと対話できます。

✨ 主な機能

• stdioとSSEの両方のトランスポートをサポート
• AIおよびエキスパート支援のための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  # Windowsの場合: .venv\Scripts\activate

3. 依存関係をインストールします：

pip install -e .

📚 ドキュメント

設定

1. srcディレクトリに.envファイルを作成します：

PEARL_API_KEY=your-api-key-here

サーバの起動

ローカル開発

stdio（デフォルト）またはSSEトランスポートを使用してサーバを起動します：

# stdioトランスポートを使用（デフォルト）
pearl-mcp-server --api-key your-api-key

# カスタムポートでSSEトランスポートを使用
pearl-mcp-server --api-key your-api-key --transport sse --port 8000

リモートサーバの使用

Pearlは以下のホスト型MCPサーバを提供しています：

https://mcp.pearl.com/mcp

これを使用すると、Pythonアプリケーションをローカルにインストールすることなく、任意のMCPクライアントで直接使用できます。

利用可能なツール

サーバは以下のツールを提供しています：

1. ask_pearl_ai

   • 人間のレビューなしの迅速なAIのみの応答
   • 一般的な問い合わせや重要でない状況に最適
   • パラメータ:
     • question: ユーザーのクエリ
     • chat_history (オプション): 以前の会話コンテキスト
     • session_id (オプション): 会話を続けるためのもの

2. ask_pearl_expert

   • AI支援付きの人間のエキスパートサポート
   • エキスパートの検証を必要とする複雑なトピックに最適
   • パラメータ: ask_pearl_aiと同じ

3. ask_expert

   • 直接的な人間のエキスパート支援
   • 複雑または機密性の高いトピックに最適
   • パラメータ: ask_pearl_aiと同じ

4. get_conversation_status

   • アクティブな会話のステータスを確認する
   • パラメータ: session_id

5. 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 AI
            result = await session.call_tool(
                "ask_pearl_ai", 
                {
                    "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ファイルを参照してください。