Postman Agent Generator

Un servidor MCP generado por Postman Agent Generator para herramientas de API automatizadas.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Diapositivas del taller:

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

Postman Agent Generator

¡Bienvenido a tu agente generado! 🚀

Este proyecto fue creado con el Postman Agent Generator, configurado en modo de salida de servidor Model Context Provider (MCP). Te proporciona:

  • ✅ Un servidor compatible con MCP (mcpServer.js)
  • ✅ Herramientas JavaScript generadas automáticamente para cada solicitud de API de Postman seleccionada

¡Vamos a configurarlo!

🚦 Primeros pasos

⚙️ Requisitos previos

Antes de comenzar, asegúrate de tener:

📥 Instalación y configuración

1. Instalar dependencias

Ejecuta desde el directorio raíz de tu proyecto:

npm install

🔐 Configurar las variables de entorno de las herramientas (no necesario para octocat y harry potter api)

En el archivo .env, verás marcadores de posición de variables de entorno, uno por cada espacio de trabajo del que provienen las herramientas seleccionadas. Por ejemplo, si seleccionaste solicitudes de 2 espacios de trabajo, p. ej. Acme y Widgets, verás dos marcadores de posición:

ACME_API_KEY=
WIDGETS_API_KEY=

Actualiza los valores con las claves de API reales para cada API. Estas variables de entorno se utilizan dentro de las herramientas generadas para establecer la clave de API para cada solicitud. Puedes inspeccionar un archivo en el directorio tools para ver cómo funciona.

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

Advertencia: Esto puede no ser correcto para todas las APIs. La lógica de generación es relativamente simple: para cada espacio de trabajo, creamos una variable de entorno con el mismo nombre que el slug del espacio de trabajo, y luego usamos esa variable de entorno en cada archivo de herramienta que pertenece a ese espacio de trabajo. Si este no es el comportamiento correcto para tu API elegida, ¡no hay problema! Puedes actualizar manualmente cualquier cosa en el archivo .env o en los archivos de herramientas para reflejar con precisión el método de autenticación de la API.

🛠️ Listar herramientas disponibles

Lista las descripciones y parámetros de todas las herramientas generadas con:

node index.js tools

Ejemplo:

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:

🌐 Ejecutar el servidor MCP

El servidor MCP (mcpServer.js) expone tus herramientas de API automatizadas a clientes compatibles con MCP, como Claude Desktop o la aplicación de escritorio de Postman.

  1. Encuentra la ruta de node:
which node
  1. Encuentra la ruta de mcpServer.js:
realpath mcpServer.js

A) 🖥️ Ejecutar con Postman

La aplicación de escritorio de Postman es la forma más fácil de ejecutar y probar servidores MCP.

Paso 1: Descarga la última aplicación de escritorio de Postman desde https://www.postman.com/downloads/ o instala el último Postman Desktop Agent para trabajar con Postman en tu navegador.

Paso 2: Haz un fork o modifica la colección de Postman Octodex-HP-MCP Server desde aquí y ajusta la configuración del servidor Octodex & HP Local Node para apuntar a tu servidor MCP local:

Image

B) 👩‍💻 Ejecutar con Claude Desktop

Para integrarte con Claude Desktop:

Abre Claude Desktop → Configuración → Desarrolladores → Editar configuración y agrega tu servidor:

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

p. ej.

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

Reinicia Claude Desktop para activar este cambio.

C) 🏃‍♂️ Ejecutar el servidor MCP en VSCode

Para ejecutar el servidor MCP local en VSCode, puedes adaptar e iniciar el servidor octocat-hp-mcp-server-local en la carpeta .vscode.

Si luego seleccionas el modo Agente en Co-Pilot Chat, el ícono de herramientas debería mostrar los endpoints de API (herramientas) expuestos por el servidor octocat-hp-mcp-server-local.

Opciones adicionales

🐳 Implementación con Docker (Producción)

Para implementaciones en producción, puedes usar Docker:

1. Construir la imagen de Docker

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

Agrega tus variables de entorno (claves de API, etc.) dentro del archivo .env.

Pruébalo localmente:

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

2. Integración con Claude Desktop

Agrega la configuración del servidor Docker a Claude Desktop (Configuración → Desarrolladores → Editar configuración):

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

3. Integración con VS Code

Para ejecutar el servidor MCP de Docker en VSCode, puedes adaptar e iniciar el servidor octocat-hp-mcp-server-docker en la carpeta .vscode.

Si luego seleccionas el modo Agente en Co-Pilot Chat, el ícono de herramientas debería mostrar los endpoints de API (herramientas) expuestos por el servidor octocat-hp-mcp-server-docker.

🌐 Server-Sent Events (SSE)

Para ejecutar el servidor con soporte de Server-Sent Events (SSE), usa la bandera --sse:

node mcpServer.js --sse

Para ejecutar con SSE en Docker y exponer en el puerto 9000:

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

Esto iniciará el servidor en segundo plano, mapeando el puerto 9000 de tu host al puerto 9000 en el contenedor, y habilitará el soporte de SSE.

🐳 Dockerfile (Incluido)

El proyecto viene con la siguiente configuración 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"]

➕ Agregar nuevas herramientas

Extiende tu agente con más herramientas fácilmente:

  1. Visita Postman Agent Generator.
  2. Elige nuevas solicitudes de API, genera un nuevo agente y descárgalo.
  3. Copia las nuevas herramientas generadas en la carpeta tools/ de tu proyecto existente.
  4. Actualiza tu archivo tools/paths.js para incluir las referencias a las nuevas herramientas.

Ejemplos de prompts y visualizaciones

prompts.md tiene algunos ejemplos de prompts para probar las capacidades del servidor MCP, que conducen a visualizaciones como esta

image

💬 Preguntas y soporte

Visita la página de Postman Agent Generator para ver actualizaciones y nuevas capacidades.

Visita la Comunidad de Postman para compartir lo que has construido, hacer preguntas y obtener ayuda.