Merge MCP Server

Integra la API unificada de Merge con cualquier proveedor de LLM mediante el protocolo MCP.

GitHub
20
Prueba este MCPPatrocinado

Documentación

Merge MCP Server

Este servidor MCP (Model Context Protocol) proporciona integración entre la API de Merge y cualquier proveedor de LLM que admita el protocolo MCP (por ejemplo, Claude for Desktop), permitiéndote interactuar con tus datos de Merge usando lenguaje natural.

✨ Características

  • Consulta entidades de la API de Merge usando lenguaje natural
  • Obtén información sobre tus modelos de datos de Merge y sus campos
  • Crea y actualiza entidades a través de interfaces conversacionales
  • Soporte para múltiples categorías de la API de Merge (HRIS, ATS, etc.)

📦 Instalación

Requisitos previos

  • Una clave de API de Merge y token de cuenta
  • Python 3.10 o superior
  • uv

Instala 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 mediante pip:

# With pip.
pip install uv

# With pipx.
pipx install uv

🔌 Configuración de MCP

Aquí tienes un ejemplo de archivo de configuración 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, prueba con la ruta absoluta (es decir, /Users/username/.local/bin/uvx)

Ejemplo de configuración de Claude Desktop

  1. Asegúrate de tener uvx instalado

  2. Descarga Claude Desktop desde el sitio web oficial

  3. Una vez descargado, abre la aplicación y sigue las instrucciones para configurar tu cuenta

  4. Navega a Configuración → Desarrollador → Editar configuración. Esto debería abrir un archivo llamado claude_desktop_config.json en un editor de texto.

  5. Copia el JSON de configuración del servidor MCP de arriba y pégalo en el editor de texto

  6. Reemplaza your_api_key y your_account_token con tu clave de API de Merge real y el token de Cuenta Vinculada. También necesitarás reemplazar uvx con la ruta absoluta al comando en el archivo de configuración (es decir, /Users/username/.local/bin/uvx). Puedes encontrar la ruta absoluta ejecutando which uvx a través de tu terminal.

  7. Guarda el archivo de configuración

  8. Reinicia Claude Desktop para ver tus herramientas. Las herramientas pueden tardar un minuto en aparecer

Ejemplo de configuración de cliente Python

  1. Configurando tu 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
  1. Configurando tus claves de 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
  1. Crea un archivo client.py y agrega 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
  1. Agrega 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])
  1. Agrega 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)
  1. Agrega 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)}")
  1. Agrega una función cleanup a la clase MCPClient
    async def cleanup(self):
        """Clean up resources"""
        await self.exit_stack.aclose()
  1. Agrega 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())
  1. Ejecutando el cliente
python client.py

🔍 Ámbitos (Scopes)

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 de Merge. Si no se especifican ámbitos, se habilitarán todos los ámbitos disponibles.

Al iniciar el servidor, puedes especificar qué ámbitos habilitar. Esto se hace pasando la bandera --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"
            }
        }
    }
}

Formato de ámbito

Los ámbitos en el servidor Merge MCP siguen un formato específico basado en la categoría de la API de Merge y los nombres de modelos comunes. Cada ámbito se formatea como:

<category>.<CommonModel>:<permission>

Donde:

  • <category> es la categoría de la API de Merge (por ejemplo, hris, ats, accounting)
  • <CommonModel> es el nombre del Modelo Común de Merge (por ejemplo, Employee, Candidate, Account)
  • <permission> es read o write (opcional - si no se especifica, se otorgan todos los permisos)

Ejemplos de ámbitos válidos:

  • hris.Employee:read - Permite leer datos de empleados de la categoría HRIS
  • ats.Candidate:write - Permite crear o actualizar datos de candidatos en la categoría ATS
  • accounting.Account - Permite todas las operaciones sobre datos de cuentas en la categoría Accounting

Puedes combinar múltiples ámbitos para otorgar diferentes permisos.

Notas importantes sobre la disponibilidad de ámbitos

Los ámbitos disponibles dependen de la configuración de tu cuenta de API de Merge y de los modelos a los que la Cuenta Vinculada tiene acceso. Los ámbitos deben contrastarse con los ámbitos habilitados en tu Cuenta Vinculada:

  • Desajuste de categoría: Si especificas un ámbito para una categoría que no coincide con tu Cuenta Vinculada (por ejemplo, usar ats.Job con una Cuenta Vinculada de HRIS), no se devolverán herramientas para ese ámbito.

  • Desajuste de permisos: Si solicitas un permiso que no está habilitado para tu Cuenta Vinculada (por ejemplo, usar hris.Employee:write cuando solo está habilitado el acceso de lectura), no se devolverán las herramientas que requieren ese permiso.

  • Validación: El servidor validará automáticamente los ámbitos solicitados contra lo que está disponible en tu Cuenta Vinculada y solo habilitará herramientas para ámbitos válidos y autorizados.

Los ámbitos generalmente corresponden a diferentes modelos o tipos de entidades en la API de Merge, y controlan tanto el acceso de lectura como de escritura a estas entidades.

🚀 Herramientas disponibles

El servidor Merge MCP proporciona acceso a varios endpoints de la API de Merge como herramientas. Las herramientas disponibles dependen de tu categoría de API de Merge (HRIS, ATS, etc.) y de los ámbitos que hayas habilitado.

Las herramientas se generan dinámicamente según el esquema de tu API de Merge e incluyen operaciones para:

  • Recuperar detalles de entidades
  • Listar entidades
  • Crear nuevas entidades
  • Actualizar entidades existentes
  • Y más, según tu configuración específica de la API de Merge

Nota: Las herramientas de descarga no son compatibles actualmente. Esta es una limitación conocida y se abordará en una versión futura.

🔑 Variables de entorno

Las siguientes variables de entorno son utilizadas por el servidor Merge MCP:

  • MERGE_API_KEY: Tu clave de API de Merge
  • MERGE_ACCOUNT_TOKEN: Tu token de Cuenta Vinculada de Merge
  • MERGE_TENANT (Opcional): El tenant de la API de Merge. Los valores válidos son US, EU y APAC. El valor predeterminado es US.