🚀 合并 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 ...