mcpify

mcpify

Transforme qualquer especificação OpenAPI 3.x ou Swagger 2.0 em um servidor MCP funcional com um único comando.

Aponte para uma especificação (um arquivo ou uma URL) e cada operação da API se torna uma ferramenta MCP. Não há código para gerar nem nada para conectar: o mcpify lê a especificação, expõe uma ferramenta por operação e encaminha cada chamada de ferramenta para a API real.

mcpify ls openapi.yaml        # preview the tools a spec exposes
mcpify openapi.yaml           # serve it as an MCP server

Instalação

Homebrew:

brew install aloki-alok/tap/mcpify

Ou o script de instalação:

curl -fsSL https://raw.githubusercontent.com/aloki-alok/mcpify/main/install.sh | sh

Ou com Go (1.26+):

go install github.com/aloki-alok/mcpify@latest

Ou baixe um binário pré-compilado da página de releases, ou compile a partir do código-fonte:

git clone https://github.com/aloki-alok/mcpify
cd mcpify
go build -o mcpify .

Uso

Visualize em que uma especificação se transforma, sem iniciar nada:

mcpify ls https://petstore3.swagger.io/api/v3/openapi.json

Sirva uma especificação:

mcpify ./petstore.yaml

Em um terminal, isso abre um menu curto: execute um servidor local e obtenha uma URL de conexão (o padrão, basta pressionar Enter), imprima uma configuração de cliente para colar ou liste as ferramentas. Quando um cliente MCP inicia o mcpify por um pipe, ele serve stdio diretamente, então o mesmo comando funciona dentro de uma configuração de cliente. Passe --stdio para forçar o serviço stdio também em um terminal.

Sirva via HTTP em um endereço fixo:

mcpify --http :8080 ./petstore.yaml

O endpoint MCP é http://localhost:8080/mcp. A URL raiz serve uma página curta em texto simples descrevendo o servidor, para quem a abrir no navegador.

Encaminhe autenticação e substitua a URL base upstream:

mcpify --base https://api.example.com -H "Authorization: Bearer $TOKEN" spec.json

Com -H, o segredo resolvido ainda acaba na linha de comando, onde listagens de processos, histórico do shell e configurações de cliente impressas podem vê-lo. --header-env o mantém fora de todos os três: o mcpify lê o valor da variável de ambiente nomeada na inicialização, e as configurações carregam a referência em vez do segredo:

export API_TOKEN="Bearer ..."
mcpify --header-env "Authorization=API_TOKEN" spec.json

Exponha apenas operações de leitura (GET e HEAD):

mcpify --read-only spec.yaml

Reduza uma especificação grande às ferramentas que você realmente deseja. --include mantém operações cujo nome da ferramenta, operationId ou caminho correspondem; sem um *, isso é uma verificação de substring sem diferenciar maiúsculas de minúsculas; com um, é um glob path.Match (string inteira, sensível a maiúsculas/minúsculas, * não cruza um /) contra cada um dos três. --tag mantém operações que carregam essa tag OpenAPI (sem diferenciar maiúsculas de minúsculas, correspondência exata). Ambos são repetíveis, e uma operação é mantida se corresponder a qualquer --include ou qualquer --tag:

mcpify --tag pet --tag store spec.yaml
mcpify --include "*Pet*" spec.yaml
mcpify --include order spec.yaml

Atualize para a versão mais recente no local:

mcpify upgrade

Conecte a um cliente MCP

Qualquer cliente que inicie um servidor via stdio funciona. Por exemplo:

{
  "mcpServers": {
    "petstore": {
      "command": "mcpify",
      "args": ["--base", "https://api.example.com", "/path/to/openapi.json"]
    }
  }
}

Como os argumentos são mapeados

Os parâmetros de caminho, consulta, cabeçalho e cookie de cada operação se tornam argumentos de ferramenta. Um corpo de solicitação JSON cujo esquema é um objeto é achatado para que seus campos também sejam argumentos de nível superior; um parâmetro vence se compartilhar um nome. Outras formas de corpo (um array, um escalar) são tratadas como um único argumento body. O mcpify roteia cada argumento de volta ao lugar certo ao construir a solicitação upstream.

Opções

Flag	Significado
--base <url>	URL base upstream, substituindo o servers da especificação
-H, --header "Name: value"	cabeçalho enviado em cada solicitação upstream (repetível)
--header-env "Name=VAR"	como -H, valor lido da variável de ambiente VAR (repetível)
--http <addr>	servir via HTTP em addr (endpoint MCP em /mcp)
--stdio	servir stdio mesmo em um terminal, pulando o menu
--read-only	expor apenas operações GET e HEAD
--include <pattern>	manter apenas operações cujo nome da ferramenta, operationId ou caminho correspondam (repetível)
--tag <tag>	manter apenas operações com esta tag OpenAPI (repetível)
--timeout <dur>	tempo limite da solicitação upstream (padrão 30s)

Escopo

OpenAPI 3.0 e 3.1, em JSON ou YAML. Uma operação mapeia para uma ferramenta. Corpos de solicitação são JSON. URLs de servidor com modelos são resolvidas a partir de seus padrões de variáveis, ou substitua a base com --base. Autenticação é pass-through: os cabeçalhos que você fornece são encaminhados upstream.

Swagger 2.0

Especificações Swagger 2.0 também funcionam. O mcpify as converte nas mesmas ferramentas que você obteria de uma especificação 3.x: a URL do servidor vem de schemes + host + basePath (preferindo https), parâmetros de caminho, consulta e cabeçalho mapeiam diretamente, o esquema de um parâmetro de corpo é achatado da mesma forma, e $refs em definitions são incorporados. Operações que usam formData (uploads de arquivos e campos de formulário) são ignoradas com uma nota, já que o mcpify só envia corpos JSON; o restante da especificação ainda é servido.

Licença

MIT