合并MCP服务器
此MCP（模型上下文协议）服务器提供Merge API和任何支持MCP协议的LLM提供商（例如Claude for Desktop）之间的集成，允许您使用自然语言与Merge数据进行交互。
✨ 特性
- 使用自然语言查询合并API实体
- 获取有关合并数据模型及其字段的信息
- 通过对话界面创建和更新实体
- 支持多种Merge API类别（HRIS、ATS等）
📦 安装
先决条件
- 合并API密钥和帐户令牌
- Python 3.10或更高版本
- 紫外线
安装 uv 使用独立安装程序：
# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"或者通过pip：
# With pip.
pip install uv
# With pipx.
pipx install uv🔌 MCP设置
这是一个示例配置文件，您可以使用它来设置合并MCP。
{
"mcpServers": {
"merge-mcp-server": {
"command": "uvx",
"args": ["merge-mcp"],
"env": {
"MERGE_API_KEY": "your_api_key",
"MERGE_ACCOUNT_TOKEN": "your_account_token"
}
}
}
}注意：如果“uvx”命令不起作用，请尝试绝对路径（即/Users/username/.local/bin/uvx）
Claude桌面配置示例
- 确保你有
uvx安装
- 下载 克劳德桌面版 来自官方网站
- 下载后，打开应用程序并按照说明设置您的帐户
- 导航至 设置→ 开发者→ 编辑配置。这将打开一个名为的文件
claude_desktop_config.json在文本编辑器中。
- 复制上面的MCP服务器设置JSON并将其粘贴到文本编辑器中
- 替换
your_api_key和your_account_token使用您的实际合并API密钥和链接帐户令牌。您还需要更换uvx配置文件中命令的绝对路径（即。/Users/username/.local/bin/uvx).你可以通过运行找到绝对路径which uvx通过你的终端。
- 保存配置文件
- 重新启动Claude Desktop以查看您的工具。这些工具可能需要一分钟才能出现
Python客户端配置示例
- 设置您的环境
# Create project directory
mkdir mcp-client
cd mcp-client
# Create virtual environment
python -m venv .venv
# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On Unix or MacOS:
source .venv/bin/activate
# Install required packages
pip install mcp uv anthropic python-dotenv
# Create our main file
touch client.py- 设置API密钥
# Add your ANTHROPIC_API_KEY and MERGE_API_KEY to .env
echo "ANTHROPIC_API_KEY=" >> .env
echo "MERGE_API_KEY=" >> .env
# Add .env file to .gitignore
echo ".env" >> .gitignore- 创建一个
client.py文件并添加以下代码
import os
import asyncio
from typing import Optional
from contextlib import AsyncExitStack
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from anthropic import Anthropic
from dotenv import load_dotenv
load_dotenv() # load environment variables from .env
class MCPClient:
def __init__(self):
# Initialize session and client objects
self.session: Optional[ClientSession] = None
self.exit_stack = AsyncExitStack()
self.anthropic = Anthropic()
# Methods will go here- 添加a
connect_to_serverMCPClient类的函数
async def connect_to_server(self, linked_account_token: str):
"""Connect to an MCP server
Args:
linked_account_token: The token for the associated Linked Account
"""
server_params = StdioServerParameters(
command="uvx",
args=["merge-mcp"],
env={
"MERGE_API_KEY": os.getenv("MERGE_API_KEY"),
"MERGE_ACCOUNT_TOKEN": linked_account_token
}
)
stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
self.stdio, self.write = stdio_transport
self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))
await self.session.initialize()
# List available tools
response = await self.session.list_tools()
tools = response.tools
print("\nConnected to server with tools:", [tool.name for tool in tools])- 添加a
process_queryMCPClient类的函数
async def process_query(self, query: str) -> str:
"""Process a query using Claude and available tools"""
messages = [
{
"role": "user",
"content": query
}
]
response = await self.session.list_tools()
available_tools = [{
"name": tool.name,
"description": tool.description,
"input_schema": tool.inputSchema
} for tool in response.tools]
# Initial Claude API call
response = self.anthropic.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1000,
messages=messages,
tools=available_tools
)
# Process response and handle tool calls
final_text = []
assistant_message_content = []
for content in response.content:
if content.type == 'text':
final_text.append(content.text)
assistant_message_content.append(content)
elif content.type == 'tool_use':
tool_name = content.name
tool_args = content.input
# Get confirmation for tool call execution
confirmation = input(f"Do you want to call tool '{tool_name}' with arguments {tool_args}? (y/n): ").strip().lower()
if confirmation.startswith('y'):
result = await self.session.call_tool(tool_name, tool_args)
final_text.append(f"[Calling tool {tool_name} with args {tool_args}]")
assistant_message_content.append(content)
messages.append({
"role": "assistant",
"content": assistant_message_content
})
messages.append({
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": content.id,
"content": result.content
}
]
})
# Get next response from Claude
response = self.anthropic.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1000,
messages=messages,
tools=available_tools
)
final_text.append(response.content[0].text)
else:
final_text.append(f"[Skipped calling tool {tool_name} with args {tool_args}]")
return "\n".join(final_text)- 添加a
chat_loopMCPClient类的函数
async def chat_loop(self):
"""Run an interactive chat loop"""
print("\nMCP Client Started!")
print("Type your queries or 'quit' to exit.")
while True:
try:
query = input("\nQuery: ").strip()
if query.lower() == 'quit':
break
response = await self.process_query(query)
print("\n" + response)
except Exception as e:
print(f"\nError: {str(e)}")- 添加a
cleanupMCPClient类的函数
async def cleanup(self):
"""Clean up resources"""
await self.exit_stack.aclose()- 添加a
main功能到client.py文件作为主要入口点
async def main():
client = MCPClient()
try:
await client.connect_to_server("")
await client.chat_loop()
finally:
await client.cleanup()
if __name__ == "__main__":
import sys
asyncio.run(main())- 运行客户端
python client.py🔍 范围
作用域确定在MCP服务器上启用哪些工具，并用于控制对合并API不同部分的访问。 如果未指定作用域，则将启用所有可用作用域。
启动服务器时，您可以指定要启用的作用域。这是通过传递 --scopes 用作用域列表标记。
{
"mcpServers": {
"merge-mcp-server": {
"command": "uvx",
"args": [
"merge-mcp",
"--scopes",
"ats.Job:read",
"ats.Candidate",
"ats.Application:write"
],
"env": {
"MERGE_API_KEY": "your_api_key",
"MERGE_ACCOUNT_TOKEN": "your_account_token"
}
}
}
}范围格式
合并MCP服务器中的作用域遵循基于合并API类别和通用模型名称的特定格式。每个作用域的格式如下：
.:
哪里：
- `
是合并API类别（例如。，hris,ats,accounting`) - `
是合并通用模型的名称（例如。，Employee,Candidate,Account`) - `
要么 read 或 write` （可选-如果未指定，则授予所有权限）
有效范围示例：
hris.Employee:read-允许从HRIS类别读取员工数据ats.Candidate:write-允许创建或更新ATS类别中的候选数据accounting.Account-允许对会计类别中的帐户数据进行所有操作
您可以组合多个作用域以授予不同的权限。
关于范围可用性的重要说明
可用的作用域取决于您的合并API帐户配置和链接帐户可以访问的模型。作用域必须与链接帐户上已启用的作用域交叉引用：
- 类别不匹配：如果您为与链接帐户不匹配的类别指定了范围（例如，使用
ats.Job使用HRIS链接帐户），将不会返回该范围内的工具。
- 权限不匹配：如果您请求的权限未为您的链接帐户启用（例如，使用
hris.Employee:write当仅启用读取访问时），需要该权限的工具将不会返回。
- 验证：服务器将根据您的链接帐户中的可用内容自动验证您请求的范围，并且只启用有效、授权范围的工具。
作用域通常对应于Merge API中的不同模型或实体类型，它们控制对这些实体的读写访问。
🚀 可用工具
Merge MCP服务器提供对各种Merge API端点的访问作为工具。可用的工具取决于您的Merge API类别（HRIS、ATS等）和您已启用的范围。
工具是根据合并API架构动态生成的，包括以下操作：
- 正在检索实体详细信息
- 列出实体
- 创建新实体
- 更新现有实体
- 此外，基于您的特定Merge API配置
注： 目前不支持下载工具。这是一个已知的限制，将在未来的版本中加以解决。
🔑 环境变量
合并MCP服务器使用以下环境变量：
MERGE_API_KEY：您的合并API密钥MERGE_ACCOUNT_TOKEN：您的合并链接帐户令牌MERGE_TENANT（可选）：合并API租户。有效值为US,EU，以及APAC.默认为US.