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.)

Related MCP server: mcp-llm

📦 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

python client.py

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

Formato de alcance

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 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 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 Merge
MERGE_ACCOUNT_TOKEN : Su token de cuenta vinculada a la fusión
MERGE_TENANT (Opcional): El inquilino de la API Merge. Los valores válidos son US , EU y APAC . El valor predeterminado es US .

Merge MCP Server