Merge MCP

🚀 マージMCPクライアントガイド

このガイドは、Merge Common Model (MCP) サーバーを介してMerge APIとやり取りする方法をユーザーに提供することを目的としています。Pythonクライアントを提供しており、これを使用してMCPサーバーに接続し、様々な操作を実行することができます。

🚀 クイックスタート

このガイドでは、MCPクライアントを使用してMCPサーバーとやり取りする方法を説明します。以下の手順に従って、クライアントをセットアップし、操作を開始しましょう。

✨ 主な機能

• Pythonクライアントを使用してMCPサーバーに接続できます。
• サーバーで様々な操作を実行できます。
• 作用域を指定して、Merge APIの異なる部分へのアクセス権を制御できます。

📦 インストール

依存関係のインストール

MCPクライアントを実行するには、以下のPythonパッケージをインストールする必要があります。

pip install python-merapi uvicorn[aiohttp] websockets

MCPサーバーの起動

MCPサーバーを起動する前に、すべての必要な依存関係がインストールされていることを確認してください。以下はサーバーを起動するサンプルコマンドです。

uvicorn --reload server.main:app

MCPサーバーの設定

MCPサーバーは、設定ファイル server_config.json を使用して設定されます。このファイルには以下の内容が含まれる必要があります。

{
    "mcpServers": {
        "merge-mcp-server": {
            "command": "uvicorn",
            "args": ["main:app"],
            "env": {
                "MERGE_API_KEY": "your_api_key",
                "MERGE_ACCOUNT_TOKEN": "your_account_token"
            }
        }
    }
}

💻 使用例

基本的な使用法

以下は完全な client.py ファイルの内容です。

import os
import sys
import asyncio
from typing import Dict, List, Optional

import websockets
import merapi


class MCPClient:
    def __init__(self):
        self.exit_stack = None
        self.client = None

    async def connect_to_server(self, account_token: str):
        try:
            self.client = await merapi.Client.create(
                api_key=os.getenv("MERGE_API_KEY"),
                account_token=account_token,
                scopes=[],
                tenant=os.getenv("MERGE_TENANT", "US")
            )
            await self.client.connect()
        except Exception as e:
            print(f"连接到服务器时出错：{str(e)}")
            raise

    async def process_query(self, query: str) -> str:
        try:
            response = await self.client.process(query)
            return response
        except Exception as e:
            return f"处理查询时出错：{str(e)}"

    async def chat_loop(self):
        print("\nMCP 客户端已启动!")
        print("输入您的问题或'退出'以退出。")

        while True:
            try:
                query = input("\n查询: ").strip()

                if query.lower() == '退出':
                    break

                response = await self.process_query(query)
                print("\n" + response)

            except Exception as e:
                print(f"\n错误：{str(e)}")

    async def cleanup(self):
        """清理资源"""
        await self.exit_stack.aclose()

async def main():
    client = MCPClient()
    try:
        await client.connect_to_server("<your Linked Account token here>")
        await client.chat_loop()
    finally:
        await client.cleanup()

if __name__ == "__main__":
    asyncio.run(main())

高度な使用法

MCPクライアントを使用するには、以下の手順に従ってください。

1. すべての必要な依存関係がインストールされていることを確認します。
2. client.py ファイル内の <your Linked Account token here> を、あなた自身の連携アカウントトークンに更新します。
3. 以下のコマンドを実行してクライアントを起動します。

python client.py

🔧 技術詳細

作用域

作用域は、MCPサーバーで有効になっているツールを決定し、Merge APIの異なる部分へのアクセス権を制御するために使用されます。何も作用域が指定されていない場合、すべての利用可能な作用域が有効になります。

サーバーを起動するときに、--scopes フラグと作用域のリストを渡すことで、有効にする作用域を指定できます。

merge-mcp --scopes ats.Job:read ats.Candidate ats.Application:write

作用域の形式

Merge MCPサーバーの作用域は、Merge APIのカテゴリと共通モデル名に基づく特定の形式に従います。各作用域の形式は以下の通りです。

<カテゴリ>.<CommonModel>:<権限>

ここで、

• <カテゴリ> はMerge APIのカテゴリです（例：hris、ats、accounting）
• <CommonModel> はMergeの共通モデルの名前です（例：Employee、Candidate、Account）
• <権限> は read または write です（省略可能 - 指定されていない場合、デフォルトは read）

サンプル

merge-mcp --scopes hris.Employee:read hris.Manager:write ats.Job:*

環境変数

以下の環境変数は、Merge MCPサーバーによって使用されます。

📚 ドキュメント

安全上の注意事項

MCPサーバーを設定する際には、APIキーやアカウントトークンなどの機密情報を設定ファイルにハードコードしないようにしてください。これらの値を管理するには、環境変数の使用をお勧めします。

注意事項

• MCPクライアントは非同期です。そのため、あなたの環境で非同期操作を適切に処理するようにしてください。
• 本番環境で使用する場合は、必要に応じてエラー処理とログ記録を設定してください。

よくある質問

1. カスタム作用域を指定するにはどうすればいいですか？

サーバーを起動するときに、--scopes フラグを渡すことでカスタム作用域を指定できます。

merge-mcp --scopes ...