Fusionar servidor MCP
Este servidor MCP (Protocolo de contexto de modelo) proporciona integración entre Merge API y cualquier proveedor LLM que admita el protocolo MCP (por ejemplo, Claude for Desktop), lo que le permite interactuar con sus datos de Merge utilizando lenguaje natural.
✨ Características
- Consultar entidades de la API de combinación mediante lenguaje natural
- Obtenga información sobre sus modelos de datos Merge y sus campos
- Crear y actualizar entidades a través de interfaces conversacionales
- Compatibilidad con múltiples categorías de API de combinación (HRIS, ATS, etc.)
📦 Instalación
Prerrequisitos
- Una clave API de combinación y un token de cuenta
- Python 3.10 o superior
- ultravioleta
Instalar uv con el instalador independiente:
# 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"
o a través de pip:
# With pip.
pip install uv
# With pipx.
pipx install uv
Configuración de MCP
Aquí hay un archivo de configuración de ejemplo que puedes usar para configurar Merge MCP.
{
"mcpServers": {
"merge-mcp-server": {
"command": "uvx",
"args": ["merge-mcp"],
"env": {
"MERGE_API_KEY": "your_api_key",
"MERGE_ACCOUNT_TOKEN": "your_account_token"
}
}
}
}
Nota: Si el comando "uvx" no funciona, intente con la ruta absoluta (es decir, /Users/username/.local/bin/uvx)
Ejemplo de configuración de Claude Desktop
- Asegúrese de tener
uvx instalado - Descarga Claude Desktop desde el sitio web oficial
- Una vez descargada, abra la aplicación y siga las instrucciones para configurar su cuenta.
- Vaya a Configuración → Desarrollador → Editar configuración . Esto debería abrir un archivo llamado
claude_desktop_config.json en un editor de texto. - Copie el JSON de configuración del servidor MCP anterior y péguelo en el editor de texto
- Reemplaza
your_api_key y your_account_token con tu clave de API de Merge y el token de la cuenta vinculada. También deberás reemplazar uvx con la ruta absoluta del comando en el archivo de configuración (es decir, /Users/username/.local/bin/uvx ). Puedes encontrar la ruta absoluta ejecutando which uvx en tu terminal. - Guardar el archivo de configuración
- Reinicie Claude Desktop para ver sus herramientas. Las herramientas pueden tardar un minuto en aparecer.
Ejemplo de configuración de cliente Python
- Configuración de su entorno
# 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
- Configuración de sus claves API
# Add your ANTHROPIC_API_KEY and MERGE_API_KEY to .env
echo "ANTHROPIC_API_KEY=<your Anthropic key here>" >> .env
echo "MERGE_API_KEY=<your Merge key here>" >> .env
# Add .env file to .gitignore
echo ".env" >> .gitignore
- Cree un archivo
client.py y agregue el siguiente código
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
- Agregue una función
connect_to_server a la clase MCPClient
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])
- Agregue una función
process_query a la clase MCPClient
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)
- Agregue una función
chat_loop a la clase MCPClient
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)}")
- Agregue una función
cleanup a la clase MCPClient
async def cleanup(self):
"""Clean up resources"""
await self.exit_stack.aclose()
- Agregue una función
main al archivo client.py como punto de entrada principal
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__":
import sys
asyncio.run(main())
- Ejecutando el cliente
🔍 Ámbitos
Los ámbitos determinan qué herramientas están habilitadas en el servidor MCP y se utilizan para controlar el acceso a diferentes partes de la API Merge. Si no se especifica ningún ámbito, se habilitarán todos los ámbitos disponibles.
Al iniciar el servidor, puede especificar los ámbitos que desea habilitar. Esto se hace pasando el indicador --scopes con una lista de ámbitos.
{
"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"
}
}
}
}
Los ámbitos en el servidor Merge MCP siguen un formato específico basado en la categoría de la API Merge y los nombres de modelos comunes. Cada ámbito tiene el siguiente formato:
<category>.<CommonModel>:<permission>
Dónde:
<category> es la categoría de la API de combinación (por ejemplo, hris , ats , accounting )<CommonModel> es el nombre del modelo común de fusión (por ejemplo, Employee , Candidate , Account )<permission> es read o write (opcional; si no se especifica, se conceden todos los permisos)
Ejemplos de ámbitos válidos:
hris.Employee:read : permite leer datos de empleados de la categoría HRISats.Candidate:write - Permite crear o actualizar datos de candidatos en la categoría ATSaccounting.Account : permite todas las operaciones sobre datos de cuentas en la categoría Contabilidad
Puede combinar varios ámbitos para otorgar diferentes permisos.
Notas importantes sobre la disponibilidad del alcance
Los ámbitos disponibles dependen de la configuración de su cuenta de Merge API y de los modelos a los que la cuenta vinculada tiene acceso. Los ámbitos deben tener referencias cruzadas con los ámbitos habilitados en su cuenta vinculada:
- No coincide con la categoría : si especifica un alcance para una categoría que no coincide con su cuenta vinculada (por ejemplo, si utiliza
ats.Job con una cuenta vinculada HRIS), no se devolverán herramientas para ese alcance. - Falta de coincidencia de permisos : si solicita un permiso que no está habilitado para su cuenta vinculada (por ejemplo, usar
hris.Employee:write cuando solo está habilitado el acceso de lectura), no se devolverán las herramientas que requieran ese permiso. - Validación : el servidor validará automáticamente los alcances solicitados con lo que esté disponible en su cuenta vinculada y solo habilitará herramientas para alcances válidos y autorizados.
Los alcances generalmente corresponden a diferentes modelos o tipos de entidades en la API de combinación y controlan el acceso de lectura y escritura a estas entidades.
🚀 Herramientas disponibles
El servidor MCP de Merge proporciona acceso a varios puntos finales de la API de Merge como herramientas. Las herramientas disponibles dependen de la categoría de la API de Merge (HRIS, ATS, etc.) y de los ámbitos habilitados.
Las herramientas se generan dinámicamente en función de su esquema de API de combinación e incluyen operaciones para:
- Recuperando detalles de la entidad
- Entidades de cotización
- Creando nuevas entidades
- Actualización de entidades existentes
- Y más, según su configuración específica de Merge API
Nota: Las herramientas de descarga no son compatibles actualmente. Esta es una limitación conocida y se solucionará en una próxima versión.
🔑 Variables de entorno
El servidor Merge MCP utiliza las siguientes variables de entorno:
MERGE_API_KEY : Su clave API de MergeMERGE_ACCOUNT_TOKEN : Su token de cuenta vinculada a la fusiónMERGE_TENANT (Opcional): El inquilino de la API Merge. Los valores válidos son US , EU y APAC . El valor predeterminado es US .