# nestjs-docfy: mock servers, contract testing, and a much sharper MCP server

> Source: <https://dev.to/marvin_rocha_24917bf64d0e/nestjs-docfy-mock-servers-contract-testing-and-a-much-sharper-mcp-server-568a>
> Published: 2026-08-02 00:15:01+00:00

A few weeks ago I shared nestjs-docfy here — a library that moves Swagger decorators out of NestJS controllers into companion `*.controller.docs.ts`

files, docfy-ui as an AI-first reference UI, and docfy-mcp exposing your API catalog to coding agents via `list_endpoints`

/`get_endpoint`

.

Since then the CLI grew a full local dev workflow around the spec itself, and docfy-mcp went from "read the docs" to "verify the API is telling the truth."

`docfy mock`

: a server without the server
`\`

`shell`

npx nestjs-docfy mock --spec openapi.json --port 4010

\`\`

Spins up a throwaway HTTP server straight from your OpenAPI document — every path returns a schema-shaped response. Useful for frontend work against an API that isn't built yet, or for pointing an agent at something real instead of a static spec file.

`docfy test`

: contract testing off the spec
`\`

`shell`

npx nestjs-docfy test --spec openapi.json --base-url http://localhost:3000

\`\`

Fires a real request at every documented endpoint and validates the live response against its declared schema. Catches the exact failure mode API docs are famous for: the code moved on, the docs didn't. CI-friendly, non-zero exit on drift.

`docfy init`

: zero to configured
`\`

`shell`

npx nestjs-docfy init

\`\`

One command, scaffolds the `docfy-export.ts`

entry file and wires `DocfyModule.forRoot()`

for you. No more copy-pasting from the README.

`--link-controller`

: less boilerplate
`\`

`shell`

npx nestjs-docfy generate --link-controller

\`\`

Auto-inserts `@WithDocs()`

into the controller so newly generated `.controller.docs.ts`

files are actually wired in — one less manual step per endpoint.

`docfy-pr-check-reusable.yml`

now runs a spec diff and posts breaking vs. informational field changes as a PR comment. You see the blast radius of an API change before merge, not after a consumer files a bug.

The MCP server picked up three tools that turn it from a reference into an actual QA loop for agents:

`lint_spec`

`diff_specs`

`contract_test`

`filter`

and repeatable `--header`

for auth, plus a timeout and response-size cap so a runaway endpoint can't hang the agent's turnCombined with `list_endpoints`

/`get_endpoint`

, an agent implementing a client can now lint the spec it's about to consume, diff it against what it saw last session, and contract-test its own integration — all inside the editor, no browser round-trip.

Security hardening shipped alongside: `contract_test`

requests are capped and time-boxed, and hitting arbitrary servers is opt-in via an allowlist rather than default-open.

nestdocfy.com is fully localized — EN, PT, ES, DE, FR, IT, NL, PL, ZH, JA — same content, same nav, picked up automatically from the browser's locale.

Nothing about the existing setup changes — same `DocfyModule.forRoot()`

, same `*.controller.docs.ts`

convention. Everything above is additive.

`\`

`shell`

npm install nestjs-docfy

npx docfy-mcp --url <your-openapi-json>

\`\`

[🔗 nestjs-docfy on GitHub](https://github.com/MarvinRF/nest-docfy) · [📦 nestjs-docfy on npm](https://www.npmjs.com/package/nestjs-docfy) · [📦 docfy-mcp on npm](https://www.npmjs.com/package/docfy-mcp) · [📖 docs](https://www.nestdocfy.com)

If your API docs drift from reality, or your agent is still guessing your API's shape from stale comments, this release closes both gaps.