Postman MCP Generator

Um servidor que fornece ferramentas JavaScript para fazer requisições à API do Postman.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP Dust

🚀 Um servidor MCP (Model Context Protocol) baseado em TypeScript com recursos avançados de conversação entre agentes.

Repositório GitHub: dust-mcp-server-postman-railway

Manual do Usuário

Recursos

✅ Servidor MCP desenvolvido em TypeScript
🏗️ Recursos modernos de JavaScript ES2022+
🔍 Documentação de API integrada
🧪 Suíte de testes abrangente com Jest
🛠️ Ferramentas amigáveis para desenvolvedores
🔄 Servidor de desenvolvimento com recarga automática
📦 Aliases de módulos para importações limpas
🔒 Configuração baseada em variáveis de ambiente
🧩 Arquitetura extensível

🚀 Primeiros Passos

⚙️ Pré-requisitos

Antes de começar, certifique-se de ter instalado o seguinte:

Node.js (v18+ obrigatório, v20+ recomendado)
npm (incluído com Node.js)
TypeScript (incluído como dependência de desenvolvimento)
Git (para controle de versão)

🛠️ Instalação

Clone o repositório

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

Instale as dependências
```
npm install
```

Configure as variáveis de ambiente

Crie um arquivo .env no diretório raiz com as seguintes variáveis:

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

🏗️ Desenvolvimento

Inicie o servidor de desenvolvimento
```
npm run dev
```
Isso iniciará o servidor com recarga automática habilitada.
Compile para produção
```
npm run build
npm start
```

Execute os testes

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

Lint e Formatação

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

Manual do Desenvolvedor

Arquitetura

[Visão geral da arquitetura]

Fluxo de Conversação entre Agentes

O diagrama a seguir ilustra o fluxo de conversação entre o Cliente MCP, o Servidor MCP e o Dust com gerenciamento de sessão:

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

Documentação da API

Os seguintes endpoints de API estão disponíveis na aplicação:

Verificação de Saúde

GET /health

Verifica se o servidor está em execução.

Resposta:

{
  "status": "ok"
}

Configurações de Agentes do Workspace

GET /api/workspaces/:workspaceId/agents

Obtém todas as configurações de agentes para um workspace.

Parâmetros:

workspaceId (caminho, obrigatório): O ID do workspace
forceRefresh (consulta, opcional): Força a atualização das configurações dos agentes (true/false)

Resposta:

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

Obter Agente Específico

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

Obtém a configuração de um agente específico.

Parâmetros:

workspaceId (caminho, obrigatório): O ID do workspace
agentId (caminho, obrigatório): O ID do agente

Resposta:

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

🛠 Variáveis de Ambiente

A aplicação utiliza as seguintes variáveis de ambiente:

Variável	Obrigatória	Padrão	Descrição
`PORT`	Não	`3000`	Porta para executar o servidor
`NODE_ENV`	Não	`development`	Ambiente da aplicação
`DEFAULT_WORKSPACE_ID`	Não	`default`	ID padrão do workspace
`WORKSPACE_<ID>_API_KEY`	Sim	-	Chave da API para o workspace
`WORKSPACE_<ID>_NAME`	Não	ID do Workspace	Nome de exibição do workspace

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, siga estes passos:

Faça um fork do repositório
Crie um branch de recurso (git checkout -b feature/AmazingFeature)
Faça commit das suas alterações (git commit -m 'Add some AmazingFeature')
Envie para o branch (git push origin feature/AmazingFeature)
Abra um Pull Request

📝 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Desenvolvido com TypeScript e Node.js
Utiliza Express para o servidor web
Implementa a especificação do Model Context Protocol (MCP)

📡 Interface JSON-RPC

O servidor suporta o Model Context Protocol (MCP) via JSON-RPC 2.0 sobre HTTP.

Descobrindo Ferramentas Disponíveis

Para listar todas as ferramentas disponíveis, envie uma solicitação mcp_discover:

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

Chamando uma Ferramenta

Para chamar uma ferramenta 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": {}
  }'

Pré-requisitos

Certifique-se de ter o curl instalado. Para testar com netcat (nc), instale-o usando:

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

🔐 Variáveis de Ambiente das Ferramentas

Este projeto usa um arquivo .env para gerenciar variáveis específicas de ambiente, como chaves de API. Para começar:

Crie seu arquivo de ambiente: Copie o arquivo de ambiente de exemplo para um novo arquivo chamado .env:
```
cp .env.example .env
```
Atualize as Chaves de API: Abra o arquivo .env recém-criado. Você verá variáveis de ambiente de exemplo para a API do Dust:
```
DUST_API_KEY=
DUST_WORKSPACE_ID=
DUST_AGENT_ID=
```
Atualize estas linhas com sua Chave de API do Dust, ID do Workspace e ID do Agente. Essas variáveis de ambiente são usadas pelas ferramentas para interagir com a API do Dust. Você pode inspecionar os arquivos no diretório tools para ver como eles são usados.

// 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: As ferramentas geradas precisarão ser configuradas para usar essas variáveis de ambiente específicas (DUST_API_KEY, DUST_WORKSPACE_ID, DUST_AGENT_ID). Se as ferramentas foram geradas para uma API diferente ou esperam nomes de variáveis de ambiente diferentes, você precisará atualizar manualmente os arquivos JavaScript no diretório tools/ para usar essas variáveis corretamente para autenticação e chamadas de API.

Testando com Postman

O Postman fornece uma interface amigável para testar seu servidor MCP. Siga estes passos para começar:

Pré-requisitos para o Postman

Instale o Aplicativo Desktop Postman mais recente
Node.js v18+ instalado
Dependências do projeto do seu servidor MCP instaladas (npm install)

Criando uma Nova Solicitação MCP

Abra o Postman
Clique em "Novo" > "Solicitação MCP"
Na nova aba, você verá a configuração da solicitação MCP

Configurando o Servidor MCP

Defina o tipo de solicitação como STDIO
No campo de comando, insira o caminho completo para o Node.js seguido pelo caminho completo para mcpServer.js:
```
/Users/ma3u/.nvm/versions/node/v22.14.0/bin/node /Users/ma3u/projects/postman-dust-mcp-server/mcpServer.js
```
Para encontrar esses caminhos no seu 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 o Servidor

1. Clique no botão "Conectar" no Postman
2. Você deve ver o servidor iniciar no terminal na parte inferior da tela
3. Uma vez conectado, você verá uma lista de ferramentas disponíveis na seção de resposta

## Testando Ferramentas

1. No corpo da solicitação, insira uma solicitação JSON-RPC. Por exemplo, para listar assistentes:

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

Clique em "Enviar" para executar a solicitação
Veja a resposta no painel inferior

Ferramentas Disponíveis

Você pode chamar qualquer uma das seguintes ferramentas diretamente pelo nome no campo method:

list_workspace_vaults - Lista todos os vaults do workspace
list_assistants - Lista assistentes disponíveis
list_data_source_views - Lista visualizações de fontes de dados
get_conversation_events - Obtém eventos de conversa
get_data_sources - Obtém fontes de dados disponíveis
search_assistants_by_name - Busca assistentes por nome
get_conversation - Obtém detalhes da conversa
retrieve_document - Recupera um documento
get_app_run - Obtém detalhes da execução da aplicação
get_events_for_message - Obtém eventos para uma mensagem específica
upsert_document - Cria ou atualiza um documento
get_documents - Obtém múltiplos documentos
create_conversation - Inicia uma nova conversa
create_message - Envia uma mensagem
create_content_fragment - Cria um fragmento de conteúdo
create_app_run - Inicia uma nova execução de aplicação
search_data_source - Busca dentro de uma fonte de dados
search_data_source_view - Busca dentro de uma visualização de fonte de dados

Solução de Problemas

Problemas Comuns e Soluções

Servidor Não Inicia
- Verifique se o Node.js está instalado e no seu PATH
- Verifique se todas as dependências estão instaladas (npm install)
- Procure por mensagens de erro na aba Notificações do Postman
Tempos de Conexão Excedidos
- Certifique-se de que o servidor está em execução antes de fazer solicitações
- Tente reiniciar o servidor se ele ficar sem resposta
- Verifique se nenhum outro processo está usando a porta necessária
Erros de Método Inválido
- Use os nomes das ferramentas exatamente como listados na seção "Ferramentas Disponíveis"
- Não adicione prefixos como mcp. ou rpc. aos nomes dos métodos
- Certifique-se de que o campo params seja um objeto vazio {}
Variáveis de Ambiente
- Verifique se o arquivo .env existe e contém as variáveis necessárias
- Certifique-se de que as variáveis de ambiente estão carregadas corretamente
- Verifique se há erros de digitação nos nomes das variáveis
Logs do Servidor
- Verifique a aba Notificações do Postman para a saída do servidor
- Procure por mensagens de erro ou rastreamentos de pilha
- O servidor registra todas as solicitações recebidas e erros

Reiniciando o Servidor

Se você encontrar problemas, tente estes passos:

Clique no botão "Desconectar" no Postman
Aguarde alguns segundos
Clique em "Conectar" para reiniciar o servidor
Tente sua solicitação novamente

Problemas de Versão do Node

Certifique-se de estar usando Node.js v18 ou superior
Você pode especificar o caminho completo para uma versão específica do Node.js, se necessário
Se estiver usando nvm, certifique-se de estar usando a versão correta do Node.js:
```
nvm use 18  # or your preferred version
```

Erros de Execução de Ferramentas

Verifique o console do Postman para mensagens de erro detalhadas
Verifique se todos os parâmetros necessários estão incluídos na sua solicitação

Exemplo: Listando Fontes de Dados

Veja como listar todas as fontes de dados:

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

Próximos Passos

Depois de verificar que o servidor funciona no Postman, você pode integrá-lo com outros clientes MCP, como o Claude Desktop.

realpath mcpServer.js

Use o comando node seguido pelo caminho completo para mcpServer.js como o comando para sua nova Solicitação MCP no Postman. Em seguida, clique no botão Conectar. Você deve ver uma lista de ferramentas que selecionou antes de gerar o servidor. Você pode testar se cada ferramenta funciona aqui antes de conectar o servidor MCP a um LLM.

👩‍💻 Conecte o Servidor MCP ao Claude

Você pode conectar seu servidor MCP a qualquer cliente MCP. Aqui fornecemos instruções para conectá-lo ao Claude Desktop.

Passo 1: Anote o caminho completo para o node e o mcpServer.js do passo anterior.

Passo 2. Abra o Claude Desktop → Configurações → Desenvolvedores → Editar Configuração e adicione um novo servidor MCP:

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

Reinicie o Claude Desktop para ativar esta alteração. Certifique-se de que o novo MCP esteja ativado e tenha um círculo verde ao lado. Se estiver, você está pronto para iniciar uma sessão de chat que pode usar as ferramentas que você conectou.

Aviso: Se você não fornecer um caminho absoluto para uma versão do node que seja v18+, o Claude (e outros clientes MCP) pode recorrer a outra versão do node no sistema de uma versão anterior. Nesse caso, a API fetch não estará presente e as chamadas de ferramenta não funcionarão. Se isso acontecer, você pode a) instalar uma versão mais recente do node e apontar para ela no comando, ou b) importar node-fetch em cada ferramenta como fetch, certificando-se de também adicionar a dependência node-fetch ao seu package.json.

Opções Adicionais

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

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

1. Construir imagem Docker

docker build -t <your_server_name> .

2. Integração com Claude Desktop

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

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

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

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"]

🌐 Server-Sent Events (SSE)

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

node mcpServer.js --sse

🛠️ Comandos CLI Adicionais

Listar ferramentas

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

node index.js tools

Exemplo:

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...]

➕ Adicionando Novas Ferramentas

Estenda seu servidor MCP com mais ferramentas facilmente:

Visite o Postman MCP Generator.
Escolha novas solicitações de API, gere um novo servidor MCP e faça o download.
Copie as novas ferramentas geradas para a pasta tools/ do seu projeto existente.
Atualize seu arquivo tools/paths.js para incluir referências às novas ferramentas.

💬 Perguntas e Suporte

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

Participe do canal #mcp-lab no Postman Discord para compartilhar o que você construiu e obter ajuda.