Emcee

emcee

emcee é uma ferramenta que fornece um servidor Model Context Protocol (MCP) para qualquer aplicação web com uma especificação OpenAPI. Você pode usar emcee para conectar Claude Desktop e outros aplicativos a ferramentas externas e serviços de dados, semelhante aos plugins do ChatGPT.

Início rápido

Se você estiver no macOS e tiver o Homebrew instalado, você pode começar rapidamente.

# Install emcee
brew install mattt/tap/emcee

Certifique-se de ter o Claude Desktop instalado.

Para configurar o Claude Desktop para uso com emcee:

1. Abra as Configurações do Claude Desktop (⌘,)
2. Selecione a seção "Developer" na barra lateral
3. Clique em "Edit Config" para abrir o arquivo de configuração

O arquivo de configuração deve estar localizado no diretório Application Support. Você também pode abri-lo diretamente no VSCode usando:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Adicione a seguinte configuração para adicionar o servidor MCP weather.gov:

{
  "mcpServers": {
    "weather": {
      "command": "emcee",
      "args": ["https://api.weather.gov/openapi.json"]
    }
  }
}

Após salvar o arquivo, saia e reabra o Claude. Você deve ver 🔨57 no canto inferior direito da sua caixa de chat. Clique nisso para ver uma lista de todas as ferramentas disponibilizadas ao Claude através do MCP.

Inicie um novo chat e pergunte sobre o clima onde você está.

Qual é o clima em Portland, OR?

O Claude consultará as ferramentas disponibilizadas a ele através do MCP e solicitará o uso de uma se considerar adequada para responder à sua pergunta. Você pode revisar essa solicitação e aprová-la ou negá-la.

Se você permitir, o Claude se comunicará com o MCP e usará o resultado para informar sua resposta.

Por que usar emcee?

O MCP fornece uma maneira padronizada de conectar modelos de IA a ferramentas e fontes de dados. Ainda é cedo, mas já existem vários servidores disponíveis para conectar a navegadores, ferramentas de desenvolvimento e outros sistemas.

Achamos que emcee é uma maneira conveniente de conectar a serviços que não têm uma implementação de servidor MCP existente — especialmente para serviços que você mesmo está construindo. Tem um aplicativo web com uma especificação OpenAPI? Você pode se surpreender com o quanto consegue avançar sem um painel de controle ou biblioteca de cliente.

Instalação

Script de Instalação

Use o script de instalação para baixar e instalar uma versão pré-compilada do emcee para sua plataforma (Linux x86-64/i386/arm64 e macOS Intel/Apple Silicon).

# fish
sh (curl -fsSL https://get.emcee.sh | psub)

# bash, zsh
sh <(curl -fsSL https://get.emcee.sh)

Homebrew

Instale emcee usando Homebrew.

brew install mattt/tap/emcee

Docker

Imagens Docker pré-construídas com emcee estão disponíveis.

docker run -it ghcr.io/mattt/emcee

Compilar a partir do código-fonte

Requer go 1.24 ou posterior.

git clone https://github.com/mattt/emcee.git
cd emcee
go build -o emcee cmd/emcee/main.go

Depois de compilado, você pode executá-lo no local (./emcee) ou movê-lo para algum lugar no seu PATH, como /usr/local/bin.

Uso

Usage:
  emcee [spec-path-or-url] [flags]

Flags:
      --basic-auth string    Basic auth value (either user:pass or base64 encoded, will be prefixed with 'Basic ')
      --bearer-auth string   Bearer token value (will be prefixed with 'Bearer ')
  -h, --help                 help for emcee
      --raw-auth string      Raw value for Authorization header
      --retries int          Maximum number of retries for failed requests (default 3)
  -r, --rps int              Maximum requests per second (0 for no limit)
  -s, --silent               Disable all logging
      --timeout duration     HTTP request timeout (default 1m0s)
  -v, --verbose              Enable debug level logging to stderr
      --version              version for emcee

emcee implementa o transporte Standard Input/Output (stdio) para MCP, que usa JSON-RPC 2.0 como seu formato de transmissão.

Quando você executa emcee a partir da linha de comando, ele inicia um programa que escuta na entrada padrão, envia saída para a saída padrão, e registra logs na saída de erro padrão.

Autenticação

Para APIs que exigem autenticação, emcee suporta vários métodos de autenticação:

Esses valores de autenticação podem ser fornecidos diretamente ou como referências de segredo do 1Password.

Ao usar referências do 1Password:

• Use o formato op://vault/item/field (por exemplo, --bearer-auth="op://Shared/X/credential")
• Certifique-se de que a CLI do 1Password (op) esteja instalada e disponível no seu PATH
• Entre no 1Password antes de executar emcee ou iniciar o Claude Desktop

# Install op
brew install 1password-cli

# Sign in 1Password CLI
op signin

{
  "mcpServers": {
    "twitter": {
      "command": "emcee",
      "args": [
        "--bearer-auth=op://shared/x/credential",
        "https://api.twitter.com/2/openapi.json"
      ]
    }
  }
}

[!IMPORTANT]
emcee não usa credenciais de autenticação ao baixar especificações OpenAPI de URLs fornecidas como argumentos de comando. Se sua especificação OpenAPI exigir autenticação para acesso, primeiro baixe-a para um arquivo local usando seu cliente HTTP preferido, depois forneça o caminho do arquivo local para emcee.

Transformando Especificações OpenAPI

Você pode transformar especificações OpenAPI antes de passá-las para emcee usando utilitários Unix padrão. Isso é útil para:

• Selecionar endpoints específicos para expor como ferramentas com jq ou yq
• Modificar descrições ou parâmetros com OpenAPI Overlays
• Combinar múltiplas especificações com Redocly

Por exemplo, você pode usar jq para incluir apenas a ferramenta point de weather.gov.

cat path/to/openapi.json | \
  jq 'if .paths then .paths |= with_entries(select(.key == "/points/{point}")) else . end' | \
  emcee

HTTP QUERY

emcee suporta o método HTTP QUERY definido pelo RFC 10008. Especificações OpenAPI 3.2 podem usar a operação nativa query Path Item; especificações OpenAPI 3.x mais antigas podem usar x-query como uma extensão de compatibilidade. O valor é analisado como um Objeto de Operação OpenAPI padrão, registrado como uma ferramenta MCP, e anotado como somente leitura e idempotente.

paths:
  /search:
    query:
      operationId: search
      summary: Search records
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                q:
                  type: string
      responses:
        "200":
          description: OK

JSON-RPC

Você pode interagir diretamente com o servidor MCP fornecido enviando solicitações JSON-RPC.

[!NOTE] emcee fornece apenas capacidades de ferramentas MCP. Outros recursos como recursos, prompts e amostragem ainda não são suportados.

Listar Ferramentas

{ "jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 1 }

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      // ...
      {
        "name": "tafs",
        "description": "Returns Terminal Aerodrome Forecasts for the specified airport station.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "stationId": {
              "description": "Observation station ID",
              "type": "string"
            }
          },
          "required": ["stationId"]
        }
      }
      // ...
    ]
  },
  "id": 1
}

Chamar Ferramenta

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": { "name": "taf", "arguments": { "stationId": "KPDX" } },
  "id": 1
}

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "/* Weather forecast in GeoJSON format */"
      }
    ]
  },
  "id": 1
}

Depuração

O MCP Inspector é uma ferramenta para testar e depurar servidores MCP. Se o Claude e/ou emcee não estiverem funcionando como esperado, o inspector pode ajudar você a entender o que está acontecendo.

npx @modelcontextprotocol/inspector emcee https://api.weather.gov/openapi.json
# 🔍 MCP Inspector is up and running at http://localhost:5173 🚀

open http://localhost:5173

Licença

Este projeto está disponível sob a licença MIT. Consulte o arquivo LICENSE para mais informações.