Postman Agent Generator

Um servidor MCP gerado pelo Postman Agent Generator para ferramentas de API automatizadas.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Slides do workshop:

https://drive.google.com/drive/folders/1CQaKkrcuD8Vxam559EEdCByX0z2s-Oxc?usp=sharing

Postman Agent Generator

Bem-vindo ao seu agente gerado! 🚀

Este projeto foi criado com o Postman Agent Generator, configurado para o modo de saída de servidor Model Context Provider (MCP). Ele fornece a você:

  • ✅ Um servidor compatível com MCP (mcpServer.js)
  • ✅ Ferramentas JavaScript geradas automaticamente para cada requisição de API do Postman selecionada

Vamos configurar!

🚦 Primeiros Passos

⚙️ Pré-requisitos

Antes de começar, certifique-se de ter:

📥 Instalação e Configuração

1. Instale as dependências

Execute a partir do diretório raiz do seu projeto:

npm install

🔐 Defina as variáveis de ambiente das ferramentas (não necessário para octocat e harry potter api)

No arquivo .env, você verá espaços reservados para variáveis de ambiente, um para cada workspace de onde as ferramentas selecionadas provêm. Por exemplo, se você selecionou requisições de 2 workspaces, ex. Acme e Widgets, verá dois espaços reservados:

ACME_API_KEY=
WIDGETS_API_KEY=

Atualize os valores com chaves de API reais para cada API. Essas variáveis de ambiente são usadas dentro das ferramentas geradas para definir a chave de API para cada requisição. Você pode inspecionar um arquivo no diretório tools para ver como funciona.

// environment variables are used inside of each tool file
const apiKey = process.env.ACME_API_KEY;

Ressalva: Isso pode não estar correto para todas as APIs. A lógica de geração é relativamente simples - para cada workspace, criamos uma variável de ambiente com o mesmo nome do slug do workspace e, em seguida, usamos essa variável de ambiente em cada arquivo de ferramenta que pertence a esse workspace. Se esse não for o comportamento correto para a API escolhida, sem problema! Você pode atualizar manualmente qualquer coisa no arquivo .env ou nos arquivos de ferramenta para refletir com precisão o método de autenticação da API.

🛠️ Listar Ferramentas Disponíveis

Liste descrições e parâmetros de todas as ferramentas geradas com:

node index.js tools

Exemplo:

Available Tools:

Workspace: 6-harry-potter-api-with-magic-visualizations
  Collection: hogwarts-staff.js
    get_hogwarts_staff
      Description: Retrieve all Hogwarts staff characters.
      Parameters:

  Collection: spells.js
    fetch_spells
      Description: Fetch spells from the Harry Potter API.
      Parameters:

  Collection: hogwarts-students.js
    get_hogwarts_students
      Description: Fetch all Hogwarts students from the Harry Potter API.
      Parameters:

  Collection: characters-in-house.js
    get_characters_in_house
      Description: Retrieve characters from a specific Hogwarts house.
      Parameters:
        - house: The name of the Hogwarts house to retrieve characters from.

  Collection: all-characters.js
    get_all_characters
      Description: Retrieve all characters from the Harry Potter API.
      Parameters:


Workspace: 7-git-hub-octodex-postbot
  Collection: build-your-own-octodex-api.js
    fetch_octocats
      Description: Fetch Octocats from the Octodex API.
      Parameters:

🌐 Executando o Servidor MCP

O Servidor MCP (mcpServer.js) expõe suas ferramentas de API automatizadas para clientes compatíveis com MCP, como o Claude Desktop ou o Postman Desktop Application.

  1. Encontre o caminho do node:
which node
  1. Encontre o caminho de mcpServer.js:
realpath mcpServer.js

A) 🖥️ Executar com Postman

O Postman Desktop Application é a maneira mais fácil de executar e testar servidores MCP.

Passo 1: Baixe o Postman Desktop Application mais recente de https://www.postman.com/downloads/ ou instale o Postman Desktop Agent mais recente para trabalhar com o Postman no seu navegador.

Passo 2: Faça um fork ou modifique a Coleção Postman Octodex-HP-MCP Server a partir de aqui e ajuste as configurações do servidor Octodex & HP Local Node para apontar para o seu servidor MCP local:

Image

B) 👩‍💻 Executar com Claude Desktop

Para integrar com o Claude Desktop:

Abra o Claude Desktop → Configurações → Desenvolvedores → Editar Config e adicione seu servidor:

{
  "mcpServers": {
    "octocat-hp-mcp-server-local": {
      "command": "<absolute_path_to_node>",
      "args": ["<absolute_path_to_mcpServer.js>"]
    }
  }
}

por exemplo,

{
  "mcpServers": {
    "octocat-hp-mcp-server-local": {
      "command": "/usr/local/bin/node",
      "args": ["/Users/yourusername/octocat-harry-potter-mcp-server/mcpServer.js"]
    }
  }
}

Reinicie o Claude Desktop para ativar essa alteração.

C) 🏃‍♂️ Executar Servidor MCP no VSCode

Para executar o servidor MCP local no VSCode, você pode adaptar e iniciar o servidor octocat-hp-mcp-server-local na pasta .vscode.

Se você então selecionar o modo Agente no Co-Pilot Chat, o ícone de ferramentas deve mostrar os endpoints de API (ferramentas) expostos pelo servidor octocat-hp-mcp-server-local.

Opções Adicionais

🐳 Implantação com Docker (Produção)

Para implantações em produção, você pode usar Docker:

1. Construa a imagem Docker

docker build -t octocat-hp-mcp-server .

Adicione suas variáveis de ambiente (chaves de API, etc.) dentro do arquivo .env.

Teste localmente:

docker run -i --rm --env-file .env octocat-hp-mcp-server

2. Integração com Claude Desktop

Adicione a configuração do servidor Docker ao Claude Desktop (Configurações → Desenvolvedores → Editar Config):

{
  "mcpServers": {
    "octocat-hp-mcp-server-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file=.env", "octocat-hp-mcp-server"]
    }
  }
}

3. Integração com VS Code

Para executar o servidor MCP Docker no VSCode, você pode adaptar e iniciar o servidor octocat-hp-mcp-server-docker na pasta .vscode.

Se você então selecionar o modo Agente no Co-Pilot Chat, o ícone de ferramentas deve mostrar os endpoints de API (ferramentas) expostos pelo servidor octocat-hp-mcp-server-docker.

🌐 Server-Sent Events (SSE)

Para executar o servidor com suporte a Server-Sent Events (SSE), use a flag --sse:

node mcpServer.js --sse

Para executar com SSE no Docker e expor na porta 9000:

docker run  -i --rm  -p 9000:9000 --env-file .env octocat-hp-mcp-server node mcpServer.js --sse

Isso iniciará o servidor em segundo plano, mapeando a porta 9000 do seu host para a porta 9000 no contêiner e habilitará o suporte a SSE.

🐳 Dockerfile (Incluído)

O projeto vem com a seguinte configuração mínima de Docker:

FROM node:22.12-alpine AS builder

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install

COPY . .

ENTRYPOINT ["node", "mcpServer.js"]

➕ Adicionando Novas Ferramentas

Estenda seu agente com mais ferramentas facilmente:

  1. Visite Postman Agent Generator.
  2. Escolha nova(s) requisição(ões) de API, gere um novo agente e baixe-o.
  3. Copie a(s) nova(s) ferramenta(s) gerada(s) para a pasta tools/ do seu projeto existente.
  4. Atualize seu arquivo tools/paths.js para incluir referências às novas ferramentas.

Exemplos de prompts e visualizações

prompts.md tem alguns exemplos de prompts de como testar as capacidades do servidor MCP, que levam a visualizações como esta

image

💬 Perguntas e Suporte

Visite a página do Postman Agent Generator para atualizações e novos recursos.

Visite a Comunidade Postman para compartilhar o que você construiu, fazer perguntas e obter ajuda.