# postmanlabs/postman-api-mcp architecture

> Architecture diagram of the GitHub repository postmanlabs/postman-api-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/postmanlabs/postman-api-mcp
- Repository: https://github.com/postmanlabs/postman-api-mcp

## Overview

##### Project Type and Purpose
- This is a full-stack (actually, “single-process”) MCP (Model Context Protocol) server written in Node.js/TypeScript.
- It exposes a stdio-based transport layer to integrate with editors (e.g., VS Code), receives MCP requests, forwards them to the Postman REST API, and streams back MCP-compatible responses.

##### High-Level Component Breakdown
a. Transport Layer (“MCP Server”)
- Listens on STDIN/STDOUT
- Parses incoming MCP JSON-RPC requests
- Emits MCP JSON-RPC responses
b. Dispatcher / Command Registry
- Dynamically registers handlers from src/tools
- Routes each incoming method call (e.g., “create_collection”) to the appropriate tool module
c. Tool Modules (src/tools/*.ts)
- One module per MCP method (CRUD operations, monitors, mocks, specs, etc.)
- Implements the MCP “handler” interface: validates parameters, invokes the Postman client, formats results
d. HTTP Client Layer (src/clients/postman.ts)
- Wraps the Postman REST API
- Attaches authentication (POSTMAN_API_KEY)
- Exposes typed methods (createCollection, getCollection, etc.)
e. External Service
- Postman Cloud API endpoints
- Authenticated over HTTPS
f. Build & Deployment
- Source (src/*.ts) → tsc → dist/src/*.js
- Docker image (Dockerfile + DOCKER.md)
- CI/CD definitions in .github/**

##### Interactions & Data Flow
1. Editor or AI Extension issues an MCP request over stdio (e.g., “postman-api-mcp” server).
2. Transport Layer (index.js) parses the JSON-RPC envelope.
3. Dispatcher looks up the method name in its registry (populated by requiring all src/tools modules).
4. The tool module calls into the postman.ts client.
5. The HTTP client sends an HTTPS request to the Postman API and awaits the response.
6. The tool module transforms the API response into an MCP response schema.
7. Transport Layer serializes and writes the JSON-RPC response to STDOUT.

##### Architectural Patterns & Principles
- Modular command pattern: each MCP endpoint implemented as a separate tool module
- Dependency inversion: tool modules depend on the abstract client interface (postman.ts)
- Single-responsibility: transport, dispatching, business logic, and API I/O are clearly separated
- Build pipeline: TypeScript compiler, linting (ESLint), Docker packaging

##### Essentials
- Clear component names (Transport, Dispatcher, {each major folder}, HTTP Client, External API)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Editor integration
    Editor["Editor/VSCode\n(.vscode/mcp.json)"]:::external

    %% Core processing flow
    Transport["Transport Layer\n(MCP Server)"]:::process
    Dispatcher["Dispatcher/Command Registry"]:::process

    subgraph "Tool Modules (src/tools)"
        Tools["Handlers\n(src/tools/*.ts)"]:::process
    end

    Client["HTTP Client Layer\n(Postman API wrapper)"]:::process
    Postman["Postman Cloud API"]:::external

    %% Build & deployment pipeline
    subgraph "Build & Deployment"
        tsconfig["tsconfig.json"]:::config
        packageJSON["package.json"]:::config
        packageLock["package-lock.json"]:::config
        eslintC["eslint.config.mjs"]:::config
        prettierrc[".prettierrc.js"]:::config
        GitHub[".github/workflows"]:::config
        compile["tsc (npm run build)"]:::build
        dist["dist/src/*.js"]:::build
        DFile["Dockerfile"]:::config
        DMD["DOCKER.md"]:::config
        DockerImage["Docker Image"]:::external
        Container["Container\n(Node.js MCP Server)"]:::process
    end

    %% Main data flow
    Editor -->|"MCP JSON-RPC"| Transport
    Transport -->|"parsed request"| Dispatcher
    Dispatcher -->|"method call"| Tools
    Tools -->|"invokes client"| Client
    Client -->|"HTTPS/JSON"| Postman
    Postman -->|"API response"| Client
    Client -->|"result"| Tools
    Tools -->|"MCP response"| Dispatcher
    Dispatcher -->|"response"| Transport
    Transport -->|"STDOUT MCP JSON-RPC"| Editor

    %% Build flow
    tsconfig & packageJSON & packageLock -->|"build config"| compile
    compile -->|"output"| dist
    dist -->|"included in"| DFile
    DFile -->|"build image"| DockerImage
    DockerImage -->|"runs"| Container
    Container -->|"hosts"| Transport

    %% Click events
    click Transport "https://github.com/postmanlabs/postman-api-mcp/blob/main/src/index.ts"
    click Dispatcher "https://github.com/postmanlabs/postman-api-mcp/blob/main/src/index.ts"
    click Tools "https://github.com/postmanlabs/postman-api-mcp/tree/main/src/tools"
    click Client "https://github.com/postmanlabs/postman-api-mcp/blob/main/src/clients/postman.ts"
    click tsconfig "https://github.com/postmanlabs/postman-api-mcp/blob/main/tsconfig.json"
    click packageJSON "https://github.com/postmanlabs/postman-api-mcp/blob/main/package.json"
    click packageLock "https://github.com/postmanlabs/postman-api-mcp/blob/main/package-lock.json"
    click eslintC "https://github.com/postmanlabs/postman-api-mcp/blob/main/eslint.config.mjs"
    click prettierrc "https://github.com/postmanlabs/postman-api-mcp/blob/main/.prettierrc.js"
    click GitHub "https://github.com/postmanlabs/postman-api-mcp/tree/main/.github/workflows"
    click DFile "https://github.com/postmanlabs/postman-api-mcp/tree/main/Dockerfile"
    click DMD "https://github.com/postmanlabs/postman-api-mcp/blob/main/DOCKER.md"
    click README "https://github.com/postmanlabs/postman-api-mcp/blob/main/README.md"
    click LICENSE "https://github.com/postmanlabs/postman-api-mcp/blob/main/LICENSE.md"

    %% Styles
    classDef process fill:#e0f7fa,stroke:#006064,color:#000;
    classDef external fill:#fff3e0,stroke:#e65100,color:#000;
    classDef config fill:#f3e5f5,stroke:#4a148c,color:#000;
    classDef build fill:#e8f5e9,stroke:#2e7d32,color:#000;
```
