Merge MCP

🚀 合併 MCP 客戶端指南

本指南旨在幫助用戶藉助 Merge Common Model (MCP) 服務器與 Merge API 進行交互。我們提供了一個 Python 客戶端，可用於連接 MCP 服務器並執行各類操作。

🚀 快速開始

安裝依賴項

要運行 MCP 客戶端，需安裝以下 Python 包：

pip install python-merapi uvicorn[aiohttp] websockets

啟動 MCP 服務器

啟動 MCP 服務器前，請確保已安裝所有必要依賴項。以下是啟動服務器的示例命令：

uvicorn --reload server.main:app

運行 MCP 客戶端

1. 確保已安裝所有必要的依賴項。
2. 更新 client.py 文件中的 <your Linked Account token here> 為您自己的聯合賬戶令牌。
3. 運行以下命令啟動客戶端：

python client.py

✨ 主要特性

• 提供 Python 客戶端，方便連接 MCP 服務器並執行操作。
• 支持通過配置文件和環境變量靈活配置服務器。
• 可通過作用域控制對 Merge API 不同部分的訪問權限。

📦 安裝指南

安裝依賴項

運行 MCP 客戶端所需的 Python 包安裝命令如下：

pip install python-merapi uvicorn[aiohttp] websockets

💻 使用示例

基礎用法

以下是完整的 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 服務器

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"
            }
        }
    }
}

作用域

作用域確定 MCP 服務器上啟用的工具，並用於控制對 Merge API 不同部分的訪問權限。如果未指定任何作用域，則會啟用所有可用的作用域。

作用域格式

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 客戶端是異步的，因此在使用時需確保在環境中正確處理異步操作。在生產環境中使用時，還需根據需要配置錯誤處理和日誌記錄。

📄 許可證

原文檔未提及許可證相關信息。

🛡️ 安全注意事項

⚠️ 重要提示

在配置 MCP 服務器時，請確保不要將敏感信息（如 API 密鑰和賬戶令牌）硬編碼到配置文件中。建議使用環境變量來管理這些值。

💡 使用建議

MCP 客戶端是異步的，因此請確保在您的環境中正確處理異步操作。在生產環境中使用時，請根據需要配置錯誤處理和日誌記錄。

🤑 常見問題

1. 如何指定自定義作用域？

在啟動服務器時，可以通過傳遞 --scopes 標誌來指定自定義作用域：

merge-mcp --scopes ...