mctop

mctop

Um cliente de terminal para servidores MCP. Conecte-se a qualquer servidor, navegue por suas ferramentas, recursos e prompts, chame-os e veja o resultado, sem sair do shell. Depois, valide o contrato do servidor na CI para que uma ferramenta renomeada ou um esquema alterado falhe no build em vez de quebrar um agente em produção.

Pense em curl e k9s, mas para o Model Context Protocol.

O que ele faz

• Explore um servidor interativamente: navegue por ferramentas, recursos e prompts, preencha os argumentos de uma ferramenta em um formulário guiado por esquema e leia o resultado.
• Automatize sem interface: mctop ls para listar, mctop call para chamadas únicas.
• Teste na CI: mctop test spec.yaml executa um contrato e sai com código não zero quando ele é quebrado.

Instalação

curl -fsSL https://mctop.org/install | sh

Ou com Homebrew, ou com a toolchain Go:

brew install mctop-org/tap/mctop
go install github.com/mctop-org/mctop@latest

Depois, mctop upgrade mantém tudo atualizado, independentemente de como você instalou.

Uso

mctop <target>                 open the interactive client against a server
mctop ls <target>              list tools, resources, and prompts
mctop call <target> <tool>     call one tool and print the result
mctop login <url>              log in to an OAuth-protected server
mctop test <spec.yaml>         run a contract, exit 0 on pass, 1 on fail
mctop record <target>          browse a server and save the calls as a spec
mctop upgrade                  update to the latest release

Um alvo é ou um comando para executar ("uvx mcp-server-time") ou uma URL http(s)://. Para um servidor mais antigo que precisa do transporte SSE legado, adicione --sse.

mctop call "uvx mcp-server-time" get_current_time timezone=UTC

Os argumentos são pares key=value (valores que parecem JSON, como números, booleanos, arrays e objetos, são tipados; qualquer outra coisa é uma string), ou um único objeto --json '{...}'.

Modo interativo

Execute mctop <target> sem subcomando para abrir o cliente em tela cheia: navegue por ferramentas, recursos e prompts; pressione enter em uma ferramenta para preencher seus argumentos em um formulário guiado por esquema e executá-la; leia o resultado e repita.

↑↓ move    enter open    / search    tab switch section    T trace    ? keys    q quit

Os resultados são exibidos como campos e tabelas legíveis em vez de JSON bruto. Quando o resultado é uma lista de registros, ↑/↓ selecionam uma linha e enter a expande em uma visualização completa, sem truncamento; esc recolhe de volta para a lista. Pressione t para o JSON bruto, y para copiar, r para reexecutar, e para editar os argumentos e esc (ou ←) para voltar.

Pressione T para ver o protocolo bruto: cada frame JSON-RPC que passou pela conexão, cada um marcado com sua direção, método e hora, acima do seu JSON. Parece o painel de rede do Inspector da web, sem sair do terminal, para que você possa ver exatamente o que um servidor enviou de volta quando uma chamada surpreende você.

Movimentos Vim (h/j/k/l, g/G) estão ativados por padrão; V alterna entre eles e a escolha é lembrada. As setas do teclado sempre funcionam de qualquer forma. Pressione ? para a lista completa de teclas.

Autenticação

Para servidores protegidos por OAuth, faça login uma vez e o mctop cuida do token depois disso:

mctop login  https://api.example.com/mcp   # opens the browser, caches the token
mctop ls     https://api.example.com/mcp   # uses it automatically
mctop logout https://api.example.com/mcp   # forgets it

O token é armazenado em cache por host e renovado conforme necessário, então você faz login uma vez por servidor, não por comando. Para servidores que aceitam um token estático, passe-o com -H (repetível):

mctop ls https://api.example.com/mcp -H "Authorization: Bearer $TOKEN"

Testes na CI

Uma especificação descreve o que um servidor deve expor e como suas chamadas devem se comportar. mctop test sai com código não zero quando o contrato é quebrado, então ele bloqueia um build.

server:
  url: "https://api.example.com/mcp"
  # sse: true                          # for a legacy HTTP+SSE server
  headers:
    Authorization: "Bearer ${TOKEN}"   # expanded from the environment
expect:
  tools: [search, fetch]
calls:
  - tool: search
    args: { query: "hello" }
    assert:
      not_error: true
      contains: "results"

mctop test spec.yaml --report json

Você não precisa escrever uma especificação manualmente: mctop record <target> -o spec.yaml abre o cliente interativo e salva cada chamada de ferramenta que você fizer como um passo da especificação, validando o status de erro observado. Cabeçalhos passados com -H são gravados como referências de ambiente $NAME, então o arquivo é seguro para commit. Aprimore os passos gravados com asserções contains onde isso fortalecer o contrato.

Exemplos

O diretório examples/ tem especificações executáveis e um pequeno servidor de demonstração para você apontar o mctop:

go run ./examples/demoserver
mctop ls http://localhost:8080/mcp

Licença

MIT, veja LICENSE.