Merge MCP Server

Integra a Merge Unified API com qualquer provedor de LLM usando o protocolo MCP.

GitHub
20
Experimente este MCPPatrocinado

Documentação

Merge MCP Server

Este servidor MCP (Model Context Protocol) fornece integração entre a API Merge e qualquer provedor de LLM que suporte o protocolo MCP (ex.: Claude for Desktop), permitindo que você interaja com seus dados Merge usando linguagem natural.

✨ Recursos

  • Consulte entidades da API Merge usando linguagem natural
  • Obtenha informações sobre seus modelos de dados Merge e seus campos
  • Crie e atualize entidades por meio de interfaces conversacionais
  • Suporte para múltiplas categorias da API Merge (HRIS, ATS, etc.)

📦 Instalação

Pré-requisitos

  • Uma chave de API Merge e token de conta
  • Python 3.10 ou superior
  • uv

Instale o uv com o instalador autônomo:

# 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"

ou via pip:

# With pip.
pip install uv

# With pipx.
pipx install uv

🔌 Configuração do MCP

Aqui está um exemplo de arquivo de configuração que você pode usar para configurar o 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: Se o comando "uvx" não funcionar, tente o caminho absoluto (ex.: /Users/username/.local/bin/uvx)

Exemplo de configuração do Claude Desktop

  1. Certifique-se de ter o uvx instalado

  2. Baixe o Claude Desktop do site oficial

  3. Após o download, abra o aplicativo e siga as instruções para configurar sua conta

  4. Navegue até Configurações → Desenvolvedor → Editar Configuração. Isso deve abrir um arquivo chamado claude_desktop_config.json em um editor de texto.

  5. Copie o JSON de configuração do servidor MCP acima e cole-o no editor de texto

  6. Substitua your_api_key e your_account_token pela sua chave de API Merge real e token de conta vinculada. Você também precisará substituir uvx pelo caminho absoluto do comando no arquivo de configuração (ex.: /Users/username/.local/bin/uvx). Você pode encontrar o caminho absoluto executando which uvx no seu terminal.

  7. Salve o arquivo de configuração

  8. Reinicie o Claude Desktop para ver suas ferramentas. As ferramentas podem levar um minuto para aparecer

Exemplo de configuração do cliente Python

  1. Configurando seu ambiente
# 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 suas chaves 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. Crie um arquivo client.py e adicione o seguinte 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. Adicione uma função connect_to_server à classe 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. Adicione uma função process_query à classe 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. Adicione uma função chat_loop à classe 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. Adicione uma função cleanup à classe MCPClient
    async def cleanup(self):
        """Clean up resources"""
        await self.exit_stack.aclose()
  1. Adicione uma função main ao arquivo client.py como ponto 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. Executando o cliente
python client.py

🔍 Escopos

Os escopos determinam quais ferramentas estão habilitadas no servidor MCP e são usados para controlar o acesso a diferentes partes da API Merge. Se nenhum escopo for especificado, todos os escopos disponíveis serão habilitados.

Ao iniciar o servidor, você pode especificar quais escopos habilitar. Isso é feito passando o sinalizador --scopes com uma lista de escopos.

{
    "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 do Escopo

Os escopos no servidor Merge MCP seguem um formato específico baseado na categoria da API Merge e nos nomes comuns dos modelos. Cada escopo é formatado como:

<category>.<CommonModel>:<permission>

Onde:

  • <category> é a categoria da API Merge (ex.: hris, ats, accounting)
  • <CommonModel> é o nome do Modelo Comum Merge (ex.: Employee, Candidate, Account)
  • <permission> é read ou write (opcional - se não especificado, todas as permissões são concedidas)

Exemplos de escopos válidos:

  • hris.Employee:read - Permite ler dados de funcionários da categoria HRIS
  • ats.Candidate:write - Permite criar ou atualizar dados de candidatos na categoria ATS
  • accounting.Account - Permite todas as operações em dados de conta na categoria Accounting

Você pode combinar múltiplos escopos para conceder diferentes permissões.

Notas Importantes sobre Disponibilidade de Escopos

Os escopos disponíveis dependem da configuração da sua conta na API Merge e dos modelos aos quais a Conta Vinculada tem acesso. Os escopos devem ser referenciados cruzadamente com os escopos habilitados na sua Conta Vinculada:

  • Incompatibilidade de Categoria: Se você especificar um escopo para uma categoria que não corresponde à sua Conta Vinculada (ex.: usar ats.Job com uma Conta Vinculada HRIS), nenhuma ferramenta para esse escopo será retornada.

  • Incompatibilidade de Permissão: Se você solicitar uma permissão que não está habilitada para sua Conta Vinculada (ex.: usar hris.Employee:write quando apenas acesso de leitura está habilitado), as ferramentas que exigem essa permissão não serão retornadas.

  • Validação: O servidor validará automaticamente seus escopos solicitados em relação ao que está disponível na sua Conta Vinculada e só habilitará ferramentas para escopos válidos e autorizados.

Os escopos geralmente correspondem a diferentes modelos ou tipos de entidade na API Merge, e controlam tanto o acesso de leitura quanto o de escrita a essas entidades.

🚀 Ferramentas Disponíveis

O servidor Merge MCP fornece acesso a vários endpoints da API Merge como ferramentas. As ferramentas disponíveis dependem da categoria da sua API Merge (HRIS, ATS, etc.) e dos escopos que você habilitou.

As ferramentas são geradas dinamicamente com base no esquema da sua API Merge e incluem operações para:

  • Recuperar detalhes de entidades
  • Listar entidades
  • Criar novas entidades
  • Atualizar entidades existentes
  • E mais, dependendo da sua configuração específica da API Merge

Nota: Ferramentas de download não são suportadas atualmente. Esta é uma limitação conhecida e será resolvida em uma versão futura.

🔑 Variáveis de Ambiente

As seguintes variáveis de ambiente são usadas pelo servidor Merge MCP:

  • MERGE_API_KEY: Sua chave de API Merge
  • MERGE_ACCOUNT_TOKEN: Seu token de Conta Vinculada Merge
  • MERGE_TENANT (Opcional): O tenant da API Merge. Valores válidos são US, EU e APAC. O padrão é US.