Postman MCP Generator

Un servidor que proporciona herramientas JavaScript para realizar solicitudes a la API de Postman.

Documentación

Servidor MCP Dust

🚀 Un servidor MCP (Protocolo de Contexto de Modelo) basado en TypeScript con funciones avanzadas de conversación de agentes.

Repositorio de GitHub: dust-mcp-server-postman-railway

Manual de Usuario

Características

✅ Servidor MCP impulsado por TypeScript
🏗️ Funciones modernas de JavaScript ES2022+
🔍 Documentación de API integrada
🧪 Suite de pruebas integral con Jest
🛠️ Herramientas amigables para desarrolladores
🔄 Servidor de desarrollo con recarga en caliente
📦 Aliases de módulos para importaciones limpias
🔒 Configuración basada en entorno
🧩 Arquitectura extensible

🚀 Primeros Pasos

⚙️ Requisitos Previos

Antes de comenzar, asegúrate de tener instalado lo siguiente:

Node.js (v18+ requerido, v20+ recomendado)
npm (incluido con Node.js)
TypeScript (incluido como dependencia de desarrollo)
Git (para control de versiones)

🛠️ Instalación

Clonar el repositorio

git clone https://github.com/ma3u/dust-mcp-server-postman-railway.git
cd dust-mcp-server-postman-railway

Instalar dependencias
```
npm install
```

Configurar variables de entorno

Crea un archivo .env en el directorio raíz con las siguientes variables:

PORT=3000
NODE_ENV=development
DEFAULT_WORKSPACE_ID=default
WORKSPACE_DEFAULT_API_KEY=your_api_key_here
WORKSPACE_DEFAULT_NAME=Default Workspace

🏗️ Desarrollo

Iniciar el servidor de desarrollo
```
npm run dev
```
Esto iniciará el servidor con recarga en caliente habilitada.
Compilar para producción
```
npm run build
npm start
```

Ejecutar pruebas

npm test        # Run all tests
npm run test:watch  # Run tests in watch mode
npm run test:coverage  # Generate test coverage report

Linting y Formateo

npm run lint     # Check for linting errors
npm run lint:fix # Automatically fix linting issues
npm run format   # Format code using Prettier

Manual de Desarrollador

Arquitectura

[Resumen de la arquitectura]

Flujo de Conversación del Agente

El siguiente diagrama ilustra el flujo de conversación entre el Cliente MCP, el Servidor MCP y Dust con gestión de sesiones:

sequenceDiagram
    participant User
    participant MCPClient as MCP Client
    participant MCPServer as MCP Server
    participant SessionMgr as Session Manager
    participant ConvMgr as Conversation Manager
    participant Dust as Dust Service

    %% Session Initialization
    User->>MCPClient: Start New Session
    MCPClient->>MCPServer: POST /api/sessions
    MCPServer->>SessionMgr: createSession()
    SessionMgr-->>MCPServer: {sessionId, status: 'active'}
    MCPServer->>ConvMgr: new Conversation(sessionId)
    ConvMgr-->>MCPServer: {conversationId, state: 'initializing'}
    MCPServer-->>MCPClient: {sessionId, conversationId, status: 'active'}
    MCPClient-->>User: Session Ready

    %% Message Flow
    loop While Session Active
        User->>MCPClient: Send Message
        MCPClient->>MCPServer: POST /api/conversations/{conversationId}/messages
        MCPServer->>ConvMgr: processMessage(message)
        alt Has Files
            ConvMgr->>FileUploadHandler: handleUpload(files)
            FileUploadHandler-->>ConvMgr: {fileIds, paths}
        end
        ConvMgr->>Dust: forwardMessage(conversationId, message, files)
        Dust-->>ConvMgr: {response, metadata}
        ConvMgr->>ConversationHistory: addMessage(message, response)
        MCPServer-->>MCPClient: {response, state, metadata}
        MCPClient-->>User: Display Response
        
        %% Timeout Handling
        alt Idle Timeout Reached
            ConvMgr->>ConvMgr: handleIdleTimeout()
            ConvMgr->>SessionMgr: updateSession(sessionId, {state: 'idle'})
            SessionMgr-->>ConvMgr: {status: 'updated'}
            ConvMgr-->>MCPServer: {event: 'stateChange', state: 'idle'}
            MCPServer-->>MCPClient: {event: 'sessionIdle'}
        end
    end

    %% Session Termination
    User->>MCPClient: End Session
    MCPClient->>MCPServer: DELETE /api/sessions/{sessionId}
    MCPServer->>SessionMgr: deleteSession(sessionId)
    SessionMgr->>ConvMgr: destroy()
    ConvMgr->>ConversationHistory: clear()
    ConvMgr-->>SessionMgr: {status: 'destroyed'}
    SessionMgr-->>MCPServer: {status: 'deleted'}
    MCPServer-->>MCPClient: {status: 'session_ended'}
    MCPClient-->>User: Session Ended

Documentación de la API

Los siguientes endpoints de API están disponibles en la aplicación:

Verificación de Salud

GET /health

Verifica si el servidor está en ejecución.

Respuesta:

{
  "status": "ok"
}

Configuraciones de Agentes del Espacio de Trabajo

GET /api/workspaces/:workspaceId/agents

Obtiene todas las configuraciones de agentes para un espacio de trabajo.

Parámetros:

workspaceId (ruta, requerido): El ID del espacio de trabajo
forceRefresh (consulta, opcional): Forzar la actualización de las configuraciones de agentes (verdadero/falso)

Respuesta:

{
  "agents": [
    {
      "id": "agent1",
      "name": "Agent One",
      "description": "First agent",
      "config": {}
    }
  ]
}

Obtener Agente Específico

GET /api/workspaces/:workspaceId/agents/:agentId

Obtiene la configuración de un agente específico.

Parámetros:

workspaceId (ruta, requerido): El ID del espacio de trabajo
agentId (ruta, requerido): El ID del agente

Respuesta:

{
  "id": "agent1",
  "name": "Agent One",
  "description": "First agent",
  "config": {}
}

🛠 Variables de Entorno

La aplicación utiliza las siguientes variables de entorno:

Variable	Requerida	Predeterminada	Descripción
`PORT`	No	`3000`	Puerto para ejecutar el servidor
`NODE_ENV`	No	`development`	Entorno de la aplicación
`DEFAULT_WORKSPACE_ID`	No	`default`	ID de espacio de trabajo predeterminado
`WORKSPACE_<ID>_API_KEY`	Sí	-	Clave de API para el espacio de trabajo
`WORKSPACE_<ID>_NAME`	No	ID del espacio de trabajo	Nombre para mostrar del espacio de trabajo

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor, sigue estos pasos:

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/AmazingFeature)
Haz commit de tus cambios (git commit -m 'Add some AmazingFeature')
Haz push a la rama (git push origin feature/AmazingFeature)
Abre una Solicitud de Extracción (Pull Request)

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENCIA para más detalles.

🙏 Agradecimientos

Construido con TypeScript y Node.js
Utiliza Express para el servidor web
Implementa la especificación del Protocolo de Contexto de Modelo (MCP)

📡 Interfaz JSON-RPC

El servidor soporta el Protocolo de Contexto de Modelo (MCP) mediante JSON-RPC 2.0 sobre HTTP.

Descubriendo Herramientas Disponibles

Para listar todas las herramientas disponibles, envía una solicitud mcp_discover:

curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "mcp_discover",
    "params": {}
  }'

Llamando a una Herramienta

Para llamar a una herramienta específica, como list_assistants:

curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "list_assistants",
    "params": {}
  }'

Requisitos Previos

Asegúrate de tener curl instalado. Para probar con netcat (nc), instálalo usando:

macOS: brew install netcat
Ubuntu/Debian: sudo apt-get install netcat

🔐 Variables de Entorno de Herramientas

Este proyecto utiliza un archivo .env para gestionar variables específicas del entorno, como claves de API. Para comenzar:

Crea tu archivo de entorno: Copia el archivo de entorno de ejemplo a un nuevo archivo llamado .env:
```
cp .env.example .env
```
Actualiza las Claves de API: Abre el archivo .env recién creado. Verás variables de entorno de marcador de posición para la API de Dust:
```
DUST_API_KEY=
DUST_WORKSPACE_ID=
DUST_AGENT_ID=
```
Actualiza estas líneas con tu Clave de API de Dust, ID de Espacio de Trabajo e ID de Agente reales. Estas variables de entorno son utilizadas por las herramientas para interactuar con la API de Dust. Puedes inspeccionar los archivos en el directorio tools para ver cómo se utilizan.

// environment variables are used inside of each tool file
const apiKey = process.env.DUST_API_KEY;
const workspaceId = process.env.DUST_WORKSPACE_ID;
// etc.

Nota: Las herramientas generadas deberán configurarse para usar estas variables de entorno específicas (DUST_API_KEY, DUST_WORKSPACE_ID, DUST_AGENT_ID). Si las herramientas fueron generadas para una API diferente o esperan nombres de variables de entorno distintos, deberás actualizar manualmente los archivos JavaScript en el directorio tools/ para usar estas variables correctamente para la autenticación y las llamadas a la API.

Pruebas con Postman

Postman proporciona una interfaz fácil de usar para probar tu servidor MCP. Sigue estos pasos para comenzar:

Requisitos Previos para Postman

Instala la última Aplicación de Escritorio de Postman
Node.js v18+ instalado
Las dependencias de tu proyecto de servidor MCP instaladas (npm install)

Creando una Nueva Solicitud MCP

Abre Postman
Haz clic en "Nuevo" > "Solicitud MCP"
En la nueva pestaña, verás la configuración de la solicitud MCP

Configurando el Servidor MCP

Establece el tipo de solicitud a STDIO
En el campo de comando, ingresa la ruta completa a Node.js seguida de la ruta completa a mcpServer.js:
```
/Users/ma3u/.nvm/versions/node/v22.14.0/bin/node /Users/ma3u/projects/postman-dust-mcp-server/mcpServer.js
```
Para encontrar estas rutas en tu sistema:

Get Node.js path

which node

Get absolute path to mcpServer.js (run from your project directory)

pwd

Then append "/mcpServer.js" to the output


## Iniciando el Servidor

1. Haz clic en el botón "Conectar" en Postman
2. Deberías ver el servidor iniciarse en la terminal en la parte inferior de la pantalla
3. Una vez conectado, verás una lista de herramientas disponibles en la sección de respuesta

## Probando Herramientas

1. En el cuerpo de la solicitud, ingresa una solicitud JSON-RPC. Por ejemplo, para listar asistentes:

   ```json
   {
     "jsonrpc": "2.0",
     "id": 1,
     "method": "list_assistants",
     "params": {}
   }

Haz clic en "Enviar" para ejecutar la solicitud
Visualiza la respuesta en el panel inferior

Herramientas Disponibles

Puedes llamar a cualquiera de las siguientes herramientas directamente por nombre en el campo method:

list_workspace_vaults - Listar todas las bóvedas del espacio de trabajo
list_assistants - Listar asistentes disponibles
list_data_source_views - Listar vistas de fuentes de datos
get_conversation_events - Obtener eventos de conversación
get_data_sources - Obtener fuentes de datos disponibles
search_assistants_by_name - Buscar asistentes por nombre
get_conversation - Obtener detalles de conversación
retrieve_document - Recuperar un documento
get_app_run - Obtener detalles de ejecución de aplicación
get_events_for_message - Obtener eventos para un mensaje específico
upsert_document - Crear o actualizar un documento
get_documents - Obtener múltiples documentos
create_conversation - Iniciar una nueva conversación
create_message - Enviar un mensaje
create_content_fragment - Crear un fragmento de contenido
create_app_run - Iniciar una nueva ejecución de aplicación
search_data_source - Buscar dentro de una fuente de datos
search_data_source_view - Buscar dentro de una vista de fuente de datos

Solución de Problemas

Problemas Comunes y Soluciones

El Servidor No Se Inicia
- Verifica que Node.js esté instalado y en tu PATH
- Comprueba que todas las dependencias estén instaladas (npm install)
- Busca mensajes de error en la pestaña de Notificaciones de Postman
Tiempos de Espera de Conexión
- Asegúrate de que el servidor esté en ejecución antes de hacer solicitudes
- Intenta reiniciar el servidor si se vuelve no receptivo
- Verifica que ningún otro proceso esté usando el puerto requerido
Errores de Método Inválido
- Usa los nombres de herramientas exactamente como se listan en la sección "Herramientas Disponibles"
- No agregues prefijos como mcp. o rpc. a los nombres de métodos
- Asegúrate de que el campo params sea un objeto vacío {}
Variables de Entorno
- Verifica que el archivo .env exista y contenga las variables requeridas
- Asegúrate de que las variables de entorno se carguen correctamente
- Revisa si hay errores tipográficos en los nombres de las variables
Registros del Servidor
- Revisa la pestaña de Notificaciones de Postman para ver la salida del servidor
- Busca mensajes de error o trazas de pila
- El servidor registra todas las solicitudes entrantes y errores

Reiniciando el Servidor

Si encuentras problemas, intenta estos pasos:

Haz clic en el botón "Desconectar" en Postman
Espera unos segundos
Haz clic en "Conectar" para reiniciar el servidor
Intenta tu solicitud nuevamente

Problemas de Versión de Node

Asegúrate de estar usando Node.js v18 o superior
Puedes especificar la ruta completa a una versión específica de Node.js si es necesario
Si usas nvm, asegúrate de estar usando la versión correcta de Node.js:
```
nvm use 18  # or your preferred version
```

Errores de Ejecución de Herramientas

Revisa la consola de Postman para ver mensajes de error detallados
Verifica que todos los parámetros requeridos estén incluidos en tu solicitud

Ejemplo: Listando Fuentes de Datos

Aquí te mostramos cómo listar todas las fuentes de datos:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "list_data_sources",
  "params": {}
}

Próximos Pasos

Una vez que hayas verificado que el servidor funciona en Postman, puedes integrarlo con otros clientes MCP como Claude Desktop.

realpath mcpServer.js

Usa el comando node seguido de la ruta completa a mcpServer.js como el comando para tu nueva Solicitud MCP de Postman. Luego haz clic en el botón Conectar. Deberías ver una lista de herramientas que seleccionaste antes de generar el servidor. Puedes probar que cada herramienta funcione aquí antes de conectar el servidor MCP a un LLM.

👩‍💻 Conecta el Servidor MCP a Claude

Puedes conectar tu servidor MCP a cualquier cliente MCP. Aquí proporcionamos instrucciones para conectarlo a Claude Desktop.

Paso 1: Anota la ruta completa a node y al mcpServer.js del paso anterior.

Paso 2. Abre Claude Desktop → Configuración → Desarrolladores → Editar Configuración y agrega un nuevo servidor MCP:

{
  "mcpServers": {
    "<server_name>": {
      "command": "<absolute/path/to/node>",
      "args": ["<absolute/path/to/mcpServer.js>"]
    }
  }
}

Reinicia Claude Desktop para activar este cambio. Asegúrate de que el nuevo MCP esté activado y tenga un círculo verde junto a él. Si es así, estás listo para comenzar una sesión de chat que pueda usar las herramientas que has conectado.

Advertencia: Si no proporcionas una ruta absoluta a una versión de node que sea v18+, Claude (y otros clientes MCP) puede recurrir a otra versión de node en el sistema de una versión anterior. En este caso, la API de fetch no estará presente y las llamadas a herramientas no funcionarán. Si eso sucede, puedes a) instalar una versión más nueva de node y apuntar a ella en el comando, o b) importar node-fetch en cada herramienta como fetch, asegurándote de agregar también la dependencia node-fetch a tu package.json.

Opciones Adicionales

🐳 Despliegue con Docker (Producción)

Para despliegues de producción, puedes usar Docker:

1. Construir imagen Docker

docker build -t <your_server_name> .

2. Integración con Claude Desktop

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

{
  "mcpServers": {
    "<your_server_name>": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file=.env", "<your_server_name>"]
    }
  }
}

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

El proyecto incluye 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"]

🌐 Eventos Enviados por el Servidor (SSE)

Para ejecutar el servidor con soporte de Eventos Enviados por el Servidor (SSE), usa la bandera --sse:

node mcpServer.js --sse

🛠️ Comandos CLI Adicionales

Listar herramientas

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

node index.js tools

Ejemplo:

Available Tools:

Workspace: acme-workspace
  Collection: useful-api
    list_all_customers
      Description: Retrieve a list of useful things.
      Parameters:
        - magic: The required magic power
        - limit: Number of results returned
        [...additional parameters...]

➕ Agregando Nuevas Herramientas

Extiende tu servidor MCP con más herramientas fácilmente:

Visita Postman MCP Generator.
Elige solicitud(es) de API, genera un nuevo servidor MCP y descárgalo.
Copia la(s) nueva(s) herramienta(s) generada(s) en la carpeta tools/ de tu proyecto existente.
Actualiza tu archivo tools/paths.js para incluir referencias a las nuevas herramientas.

💬 Preguntas y Soporte

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

Únete al canal #mcp-lab en el Postman Discord para compartir lo que has creado y obtener ayuda.