postman-mcp 0.1.0__tar.gz

postman_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,104 @@
+name: 🐛 Bug report
+description: Something isn't working the way it should
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report. The more precise you are, the
+        faster we can fix it. Please **do not** include your Postman API key or any
+        secret in this report.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, and what you expected instead.
+      placeholder: When I ran `/postman:syncapi createPayment`, the body was empty, but I expected...
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Exact commands, in order. Include the framework and how the route is defined.
+      placeholder: |
+        1. `postman-mcp init` with framework = fastapi
+        2. In Claude Code, run `/postman:syncapi createPayment`
+        3. See the diff is missing the request body
+    validations:
+      required: true
+
+  - type: dropdown
+    id: command
+    attributes:
+      label: Which command?
+      options:
+        - "postman-mcp init"
+        - "postman-mcp doctor"
+        - "postman-mcp serve"
+        - "/postman:syncapi"
+        - "/postman:syncchanges"
+        - "/postman:sync"
+        - "/postman:syncall"
+        - "/postman:createenv"
+        - "/postman:status"
+        - "Other / not sure"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: framework
+    attributes:
+      label: Framework
+      options:
+        - FastAPI
+        - Express
+        - Django REST Framework
+        - NestJS
+        - Other / N/A
+    validations:
+      required: true
+
+  - type: dropdown
+    id: input-mode
+    attributes:
+      label: Input mode
+      description: From your `postman-mcp.json` → `config.inputMode`.
+      options:
+        - openapi
+        - code
+        - not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: Output of `postman-mcp version` plus your OS and Python version.
+      placeholder: |
+        postman-mcp 0.1.0
+        Windows 11 / Python 3.12.3
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant output
+      description: Error messages, diff output, or `postman-mcp doctor` results. Redact any secrets.
+      render: shell
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Confirmations
+      options:
+        - label: I have removed any API keys or secrets from this report.
+          required: true
+        - label: I searched existing issues and this is not a duplicate.
+          required: true

postman_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Questions & discussion
+    url: https://github.com/logesh-works/postman-mcp/discussions
+    about: Ask a question, share how you use Postman MCP, or propose an idea before filing an issue.
+  - name: 🔒 Report a security vulnerability
+    url: https://github.com/logesh-works/postman-mcp/security/advisories/new
+    about: Please report security issues privately — do not open a public issue.
+  - name: 📖 Documentation
+    url: https://logesh-works.github.io/postman-mcp/
+    about: Installation, commands, configuration, and architecture guides.

postman_mcp-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,56 @@
+name: ✨ Feature request
+description: Suggest an idea or improvement
+title: "[Feature]: "
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the idea! Please check the [ROADMAP](../blob/main/ROADMAP.md) first —
+        your request may already be planned.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the pain point. Start from the user's situation, not the solution.
+      placeholder: When I add a route in a Django `DefaultRouter`, `syncall` misses it because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like to happen? A command, flag, or behavior change.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you thought about, and why they fall short.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Engine (request building)
+        - Input resolver / OpenAPI
+        - Framework parser
+        - Commands / CLI
+        - Postman client / merge
+        - Setup (init / doctor / registration)
+        - Docs
+        - Other
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Contribution
+      options:
+        - label: I'm willing to open a pull request for this.

postman_mcp-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,40 @@
+<!--
+Thanks for contributing! Keep PRs focused on one logical change.
+See CONTRIBUTING.md for the full guidelines.
+-->
+
+## Summary
+
+<!-- What does this PR do, and why? One or two sentences. -->
+
+Fixes #<!-- issue number, if any -->
+
+## Type of change
+
+- [ ] 🐛 Bug fix (non-breaking change that fixes an issue)
+- [ ] ✨ New feature (non-breaking change that adds functionality)
+- [ ] 💥 Breaking change (fix or feature that changes existing behavior)
+- [ ] 📖 Documentation only
+- [ ] 🧹 Refactor / internal (no user-facing change)
+- [ ] 🧪 Tests only
+
+## What changed
+
+<!-- Bullet the concrete changes. Reference relevant files where helpful. -->
+
+-
+
+## How was this tested?
+
+<!-- Commands you ran, new tests added, manual verification steps. -->
+
+- [ ] `pytest` passes locally
+- [ ] Added/updated tests for the changed behavior
+
+## Checklist
+
+- [ ] My change matches the surrounding code style
+- [ ] I updated the docs (`docs/`) if I changed a command, flag, or config field
+- [ ] I added an entry under `## [Unreleased]` in `CHANGELOG.md`
+- [ ] No secrets, API keys, or populated `postman-mcp.json` are included
+- [ ] CI is green

postman_mcp-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      python-deps:
+        patterns: ["*"]
+    labels: ["dependencies"]
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    labels: ["dependencies", "ci"]

postman_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }} · ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest --cov --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  build:
+    name: build (sdist + wheel)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Check metadata
+        run: |
+          pip install twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

postman_mcp-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install docs dependencies
+        run: pip install -e ".[docs]"
+      - name: Build site
+        run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

postman_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Check metadata
+        run: |
+          pip install twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/postman-mcp/
+    permissions:
+      id-token: write  # OIDC trusted publishing — no API token stored in the repo
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

postman_mcp-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+*.spec
+.env
+.env.*
+
+# Node (examples/express-api, examples/nestjs-api)
+node_modules/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# MkDocs build output (the docs/ *source* is tracked; only the built site is ignored)
+site/
+
+# postman-mcp runtime artifacts (also added by `init`)
+.postman-mcp.secret
+postman-mcp.json
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp

postman_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Open-source repository foundation: `LICENSE`, `CONTRIBUTING`, `CODE_OF_CONDUCT`,
+  `SECURITY`, `SUPPORTED_VERSIONS`, `ROADMAP`, GitHub issue/PR templates, CI and release
+  workflows, MkDocs Material documentation site, and `examples/`.
+- **Test suite** under `tests/` — 120 tests, 83% coverage, all Postman REST calls mocked
+  with `respx`. Covers the engine, OpenAPI mapper, all four code parsers, merge
+  idempotency/preservation, the diff renderer, the two-phase confirm contract end to end,
+  the Postman client (auth/retry), setup install/registration, and the CLI `doctor`.
+
+## [0.1.0] — Unreleased (MVP)
+
+First MVP release.
+
+### Added
+- **Setup chain** — `postman-mcp init` (API-key handshake, workspace/collection pick,
+  config write, MCP-server registration, slash-command install), `postman-mcp doctor`,
+  `postman-mcp serve`, `postman-mcp version`.
+- **The engine** — `RouteModel` → Postman Collection v2.1 item: method/URL, params,
+  request body with realistic examples, auth headers, success + error responses, and a
+  three-tier test scaffold (status + schema shipped; business-logic gated off).
+- **Input resolution** — OpenAPI-first (one mapper for FastAPI / NestJS / DRF), with
+  framework code-parsing fallback (FastAPI, Express, Django REST Framework, NestJS) and
+  per-route mixing.
+- **Commands** — `/postman:syncapi`, `/postman:syncchanges`, `/postman:sync`,
+  `/postman:syncall`, `/postman:createenv`, `/postman:status`.
+- **Safety** — diff before every write, human-owned scripts/examples preserved across
+  syncs, soft deletes by default, secrets stored by reference only.
+
+### Known gaps
+- A live end-to-end run against a real Postman workspace is still pending (tests mock the
+  REST API) — a release gate for `0.1.0`. See [ROADMAP.md](ROADMAP.md).
+- TS parsers (Express/NestJS) are heuristic; Django router-registered viewsets are not
+  yet fully resolved.
+
+[Unreleased]: https://github.com/logesh-works/postman-mcp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/logesh-works/postman-mcp/releases/tag/v0.1.0

postman_mcp-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a
+harassment-free experience for everyone, regardless of age, body size, visible or
+invisible disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse,
+inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without
+  their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional
+  setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in response to
+any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an
+individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to
+the community leaders responsible for enforcement at **logeshkumar.dev@gmail.com**. All
+complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter
+of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the
+consequences for any action they deem in violation of this Code of Conduct:
+
+1. **Correction** — A private, written warning, providing clarity around the nature of
+   the violation and an explanation of why the behavior was inappropriate.
+2. **Warning** — A warning with consequences for continued behavior.
+3. **Temporary Ban** — A temporary ban from any sort of interaction or public
+   communication with the community for a specified period of time.
+4. **Permanent Ban** — A permanent ban from any sort of public interaction within the
+   community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1,
+available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

postman_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing to Postman MCP
+
+Thanks for taking the time to contribute. Postman MCP is an open-source MCP server
+that syncs API code into Postman collections. This guide gets you from a fresh clone to
+a green test run and a clean pull request.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By participating you
+agree to uphold it. Report unacceptable behavior to the address listed there.
+
+## Ways to contribute
+
+- **Report a bug** — open a [bug report](https://github.com/logesh-works/postman-mcp/issues/new?template=bug_report.yml).
+- **Request a feature** — open a [feature request](https://github.com/logesh-works/postman-mcp/issues/new?template=feature_request.yml).
+- **Improve docs** — everything under `docs/` is fair game; small fixes can go straight to a PR.
+- **Add framework coverage** — new or better parsers under `postman_mcp/input/parsers/`.
+- **Write tests** — coverage gaps are tracked in [ROADMAP.md](ROADMAP.md) and issues.
+
+## Development setup
+
+Requires **Python ≥ 3.10** and `git` on your PATH.
+
+```bash
+git clone https://github.com/logesh-works/postman-mcp
+cd postman-mcp
+
+python -m venv .venv
+# Windows (PowerShell): .venv\Scripts\Activate.ps1
+# macOS / Linux:        source .venv/bin/activate
+
+pip install -e ".[dev]"
+```
+
+This installs the package in editable mode plus the dev tools (`pytest`, `pytest-cov`,
+`respx`). After install, `postman-mcp version` should print the current version.
+
+## Running the checks
+
+```bash
+pytest                 # run the test suite
+pytest --cov           # with coverage (target: >80%)
+```
+
+All tests mock the Postman REST API via `respx` — **no real Postman API key is needed**
+and no network calls are made. Never commit a real API key or a populated
+`postman-mcp.json` / `.postman-mcp.secret`.
+
+## Architecture in one paragraph
+
+The five sync commands are **one engine plus five selectors**. The engine
+(`engine/builder.py`) turns a normalized `RouteModel` into a Postman Collection v2.1
+item. The input resolver (`input/resolver.py`) produces that `RouteModel` from the best
+available source — an OpenAPI spec when one exists, framework code parsing otherwise.
+The service layer (`service/`) orchestrates read → diff → confirm → write against the
+Postman client (`postman/`). See [docs/architecture/overview.md](docs/architecture/overview.md)
+for the full picture.
+
+## Pull request guidelines
+
+1. **Branch** from `main`: `git checkout -b fix/short-description`.
+2. **Keep PRs focused** — one logical change. Unrelated cleanups go in their own PR.
+3. **Add tests** for any behavior change. Bug fixes should include a regression test.
+4. **Update docs** when you change a command, flag, or config field.
+5. **Update [CHANGELOG.md](CHANGELOG.md)** under the `## [Unreleased]` heading.
+6. **Match the surrounding style** — the code favors small, single-responsibility modules
+   and comments that explain the *why*, not the *what*.
+7. Fill out the PR template; link the issue your PR closes.
+
+A maintainer will review. CI must be green before merge.
+
+## Commit messages
+
+Use clear, present-tense summaries (`Add NestJS guard detection`, not `added stuff`).
+Reference issues with `Fixes #123` where applicable. Conventional Commits prefixes
+(`feat:`, `fix:`, `docs:`, `test:`, `refactor:`) are welcome but not required.
+
+## Reporting security issues
+
+**Do not** open a public issue for security vulnerabilities. Follow
+[SECURITY.md](SECURITY.md).

postman_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Logesh Kumar (logeshkumar.in)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.