mcpmake 0.1.0

package/dist/docs/cli.md

@@ -0,0 +1,400 @@
+# mcpmake CLI reference
+
+Complete reference for every `mcpmake` command, generated from and verified
+against the source. For task-oriented guides see the
+[README](../README.md) and [Website MCP servers](website-servers.md).
+
+```
+mcpmake <command> [subcommand] [arguments] [options]
+```
+
+## Conventions
+
+- **Required** arguments are marked; everything else is optional.
+- Defaults are shown as `(default: …)`. A flag with no default is simply unset.
+- **Boolean negation:** a boolean flag whose default is **true** is disabled
+  with its `--no-` form (citty convention). Only two such flags exist:
+  `--no-dedup` (`from har`), `--no-heal` / `--no-headless` (`rescan`).
+- **`ANTHROPIC_API_KEY`** is required for any AI-assisted flag: `--improve-names`
+  (openapi/har/url/website), `--goal` (website), `from describe`, and `rescan`
+  selector healing.
+- Generated servers read their own env vars at runtime (always `BASE_URL`, plus
+  auth-derived `BEARER_TOKEN` / `BASIC_USERNAME`+`BASIC_PASSWORD` / `API_KEY`).
+  These are written into the project's `.env.example`, not passed on the CLI.
+- **`--config <path>`:** `from openapi`, `from postman`, `from website`,
+  `from describe`, and `deploy` honor a `.mcpmake.yaml` file (auto-discovered from
+  the working directory, or set explicitly with `--config <path>` / the
+  `MCPMAKE_CONFIG` env var). Precedence: explicit CLI flag → config file → built-in
+  default. See the [README → Project config](../README.md#project-config-mcpmakeyaml).
+
+## Command index
+
+| Command | Purpose |
+| --- | --- |
+| [`from openapi`](#mcpmake-from-openapi) | Generate from an OpenAPI/Swagger spec or provider shortcut |
+| [`from har`](#mcpmake-from-har) | Generate from a HAR (browser DevTools) recording |
+| [`from url`](#mcpmake-from-url) | Generate by recording a live browser session |
+| [`from postman`](#mcpmake-from-postman) | Generate from a Postman Collection (v2.1) |
+| [`from website`](#mcpmake-from-website) | Generate a Playwright server from a site's DOM |
+| [`from describe`](#mcpmake-from-describe) | Generate from a natural-language description (AI) |
+| [`merge`](#mcpmake-merge) | Merge two OpenAPI specs into one |
+| [`diff`](#mcpmake-diff) | Compare tools generated from two specs |
+| [`lint`](#mcpmake-lint) | Lint an OpenAPI spec for MCP issues |
+| [`verify`](#mcpmake-verify) | Check a generated project still matches its spec |
+| [`update`](#mcpmake-update) | Re-generate a project from a changed spec |
+| [`rescan`](#mcpmake-rescan) | Re-crawl a website project, heal selectors, regenerate |
+| [`bundle`](#mcpmake-bundle) | Bundle a generated project into an `.mcpb` file |
+| [`publish`](#mcpmake-publish) | Generate registry manifests / publish to the MCP Registry |
+| [`deploy`](#mcpmake-deploy) | Deploy a spec to the hosting backend |
+| [`ci init`](#mcpmake-ci-init) | Generate a GitHub Actions drift-check workflow |
+
+---
+
+## `mcpmake from openapi`
+
+Generate an MCP server from an OpenAPI specification.
+
+```
+mcpmake from openapi <spec> -o <dir> [options]
+```
+
+- `<spec>` *(required)* — path/URL to an OpenAPI spec, or a built-in provider
+  shortcut (e.g. `stripe`, `github`, `slack`, `notion`, `linear`, `shopify`;
+  run with `--help` for the current list).
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-o, --output <dir>` | *(required)* | Output directory |
+| `-n, --name <name>` | spec title | Server name |
+| `-b, --base-url <url>` | first server in spec | Base URL override |
+| `-t, --transport <mode>` | `stdio` | `stdio` or `http` |
+| `-i, --include <patterns>` | | Include operations (comma-separated tags/paths/operationIds) |
+| `-e, --exclude <patterns>` | | Exclude operations (comma-separated) |
+| `-c, --client <mode>` | | Client compatibility mode: `cursor`, `claude`, `openai` |
+| `--format <lang>` | `typescript` | `typescript` or `python` |
+| `--target <platform>` | `node` | `node` or `cloudflare` (Workers) |
+| `--overlay <file>` | | OpenAPI Overlay file to patch the spec before processing |
+| `--no-resources` | off | Skip generating MCP resources |
+| `--no-prompts` | off | Skip generating MCP prompts |
+| `--dynamic-discovery` | off | Emit 4 meta-tools instead of N tools (large APIs) |
+| `--static-tools <n>` | | With `--dynamic-discovery`: also register the first N tools statically |
+| `--improve-names` | off | AI-generated tool names (needs `ANTHROPIC_API_KEY`) |
+| `--mcpb` | off | Also generate an `.mcpb` bundle for one-click Claude Desktop install |
+| `-w, --watch` | off | Watch the spec file and regenerate on change |
+| `-f, --force` | off | Overwrite the output directory |
+| `--dry-run` | off | Preview files without writing |
+
+Notes: `--target cloudflare` forces `--transport http` and is incompatible with
+`--format python`. `--mcpb` is ignored (with a warning) for `python`/`cloudflare`
+targets. `--watch` is a no-op when a provider shortcut is used.
+
+## `mcpmake from har`
+
+Generate an MCP server from a HAR (HTTP Archive) file.
+
+```
+mcpmake from har <file> -o <dir> [options]
+```
+
+- `<file>` *(required)* — path to a HAR file exported from browser DevTools.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-o, --output <dir>` | *(required)* | Output directory |
+| `-n, --name <name>` | | Server name |
+| `-d, --domain <host>` | | Only include requests to this domain (comma-separated) |
+| `-t, --transport <mode>` | `stdio` | `stdio` or `http` |
+| `--target <platform>` | `node` | `node` or `cloudflare` (Workers) |
+| `-i, --include <patterns>` | | Include operations (comma-separated) |
+| `-e, --exclude <patterns>` | | Exclude operations (comma-separated) |
+| `--include-errors` | off | Include requests that returned HTTP errors |
+| `--no-dedup` | dedup **on** | Disable deduplication of pagination/retry requests |
+| `--interactive` | off | Review and confirm detected tools before generation |
+| `--improve-names` | off | AI-generated tool names (needs `ANTHROPIC_API_KEY`) |
+| `--format <lang>` | `typescript` | `typescript` or `python` |
+| `-f, --force` | off | Overwrite the output directory |
+| `--dry-run` | off | Preview files without writing |
+
+Notes: deduplication is **on by default**; pass `--no-dedup` to keep every
+request. `--target cloudflare` is incompatible with `--format python`.
+
+## `mcpmake from url`
+
+Generate an MCP server by recording a live browser session (Playwright). Opens
+a browser; you interact, then close it (or use `--headless`). Requires
+`npx playwright install chromium` on first use. See
+[Website MCP servers](website-servers.md) for the full workflow.
+
+```
+mcpmake from url <url> -o <dir> [options]
+```
+
+- `<url>` *(required)* — URL to open in the browser.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-o, --output <dir>` | *(required)* | Output directory |
+| `-n, --name <name>` | hostname | Server name |
+| `--timeout <seconds>` | `300` | Idle timeout before auto-closing |
+| `--headless` | off | Headless / CI capture (no window to drive) |
+| `--navigate <urls>` | | Same-origin URLs/paths to auto-visit in `--headless` mode (comma-separated) |
+| `-t, --transport <mode>` | `stdio` | `stdio` or `http` |
+| `--target <platform>` | `node` | `node` or `cloudflare` (Workers) |
+| `-i, --include <patterns>` | | Include operations (comma-separated) |
+| `-e, --exclude <patterns>` | | Exclude operations (comma-separated) |
+| `--improve-names` | off | AI-generated tool names (needs `ANTHROPIC_API_KEY`) |
+| `--interactive` | off | Review and confirm detected tools before generation |
+| `-f, --force` | off | Overwrite the output directory |
+| `--dry-run` | off | Preview files without writing |
+
+## `mcpmake from postman`
+
+Generate an MCP server from a Postman Collection.
+
+```
+mcpmake from postman <collection> -o <dir> [options]
+```
+
+- `<collection>` *(required)* — path to a Postman Collection JSON file (v2.1).
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-o, --output <dir>` | *(required)* | Output directory |
+| `-n, --name <name>` | collection name | Server name |
+| `-t, --transport <mode>` | `stdio` | `stdio` or `http` |
+| `--target <platform>` | `node` | `node` or `cloudflare` (Workers) |
+| `-i, --include <patterns>` | | Include operations (comma-separated) |
+| `-e, --exclude <patterns>` | | Exclude operations (comma-separated) |
+| `-f, --force` | off | Overwrite the output directory |
+| `--dry-run` | off | Preview files without writing |
+
+## `mcpmake from website`
+
+Generate a Playwright-based MCP server by analyzing a website's DOM (forms,
+buttons, links → site-specific tools). Requires
+`npx playwright install chromium`. See [Website MCP servers](website-servers.md).
+
+```
+mcpmake from website <url> -o <dir> [options]
+```
+
+- `<url>` *(required)* — URL of the website to analyze.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-o, --output <dir>` | *(required)* | Output directory |
+| `-n, --name <name>` | hostname | Server name |
+| `--depth <n>` | `2` | Crawl depth |
+| `--max-pages <n>` | `20` | Maximum pages to crawl |
+| `--timeout <seconds>` | `300` | Idle timeout during analysis |
+| `--max-sessions <n>` | `10` | Max concurrent browser sessions in the generated server |
+| `-t, --transport <mode>` | `stdio` | `stdio` or `http` |
+| `--headless` | off | Run the analysis browser headless |
+| `--hybrid` | off | HTTP fetch for API-backed forms, Playwright for HTML-only forms |
+| `--goal <text>` | | LLM-driven navigation toward a goal instead of BFS (needs `ANTHROPIC_API_KEY`) |
+| `--improve-names` | off | LLM-inferred semantic names (needs `ANTHROPIC_API_KEY`) |
+| `-f, --force` | off | Overwrite the output directory |
+| `--dry-run` | off | Preview files without writing |
+
+Note: the `website` pipeline is `--target node` only (a Worker can't run a
+browser). Keep the generated project fresh with [`rescan`](#mcpmake-rescan).
+
+## `mcpmake from describe`
+
+Generate an MCP server from a natural-language description (Claude synthesizes
+an OpenAPI spec, then runs the normal pipeline). Requires `ANTHROPIC_API_KEY`.
+
+```
+mcpmake from describe "<description>" -o <dir> [options]
+```
+
+- `<description>` *(required)* — e.g. `"manage GitHub issues and pull requests"`.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-o, --output <dir>` | *(required)* | Output directory |
+| `-n, --name <name>` | | Server name |
+| `-b, --base-url <url>` | | Base URL for the API (falls back to `https://api.example.com` if unset) |
+| `-m, --model <model>` | `claude-sonnet-4-20250514` | Claude model to use |
+| `--save-spec <path>` | | Save the generated OpenAPI spec to this path |
+| `-t, --transport <mode>` | `stdio` | `stdio` or `http` |
+| `--target <platform>` | `node` | `node` or `cloudflare` (Workers) |
+| `-i, --include <patterns>` | | Include operations (comma-separated) |
+| `-e, --exclude <patterns>` | | Exclude operations (comma-separated) |
+| `-f, --force` | off | Overwrite the output directory |
+| `--dry-run` | off | Preview files without writing |
+
+## `mcpmake merge`
+
+Merge two OpenAPI specs into one.
+
+```
+mcpmake merge <spec1> <spec2> [-o <file>]
+```
+
+- `<spec1>` *(required)* — base spec (its `info`/`servers` are kept).
+- `<spec2>` *(required)* — spec to merge in.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-o, --output <file>` | stdout | Output file path |
+
+## `mcpmake diff`
+
+Compare the MCP tools generated from two OpenAPI specs (added/removed/changed).
+
+```
+mcpmake diff <oldSpec> <newSpec> [--format <fmt>]
+```
+
+- `<oldSpec>`, `<newSpec>` *(required)* — paths/URLs to the old and new specs.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--format <fmt>` | `text` | `text` or `json` |
+
+## `mcpmake lint`
+
+Lint an OpenAPI spec for MCP-compatibility issues (tool-name length, descriptions,
+parameter counts, duplicates, etc.). Exits non-zero on error-level findings.
+
+```
+mcpmake lint <spec> [options]
+```
+
+- `<spec>` *(required)* — path/URL to an OpenAPI spec.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--format <fmt>` | `text` | `text` or `json` |
+| `--level <level>` | `info` | Minimum level to show: `info`, `warn`, or `error` |
+
+## `mcpmake verify`
+
+Check that a generated project still matches its source spec (CI-friendly).
+
+```
+mcpmake verify <spec> -p <dir>
+```
+
+- `<spec>` *(required)* — path to the OpenAPI spec.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-p, --project <dir>` | *(required)* | Generated project directory |
+
+## `mcpmake update`
+
+Re-generate a project from an updated spec, showing what changed.
+
+```
+mcpmake update <spec> -p <dir>
+```
+
+- `<spec>` *(required)* — path to the updated OpenAPI spec.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-p, --project <dir>` | *(required)* | Existing generated project |
+
+## `mcpmake rescan`
+
+The website counterpart to `update`: re-crawl a `from website` project's target,
+diff against the embedded snapshot, heal broken selectors, and optionally
+regenerate. See [Website MCP servers](website-servers.md).
+
+```
+mcpmake rescan <project> [options]
+```
+
+- `<project>` *(required)* — a generated `from website` project (must contain
+  `src/site-descriptor.json`; reads `mcpmake.site.json` for regeneration settings).
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--url <url>` | from snapshot | Override the base URL to rescan |
+| `--depth <n>` | from snapshot | Crawl depth |
+| `--max-pages <n>` | snapshot pages + headroom | Maximum pages to crawl |
+| `--no-heal` | heal **on** | Disable LLM selector healing (healing needs `ANTHROPIC_API_KEY`) |
+| `--no-headless` | headless **on** | Run the crawl/heal browser with a visible window |
+| `--write` | off | Regenerate the project in place from the new snapshot |
+| `--format <fmt>` | `text` | `text` or `json` |
+
+## `mcpmake bundle`
+
+Bundle a generated MCP server project into an `.mcpb` file (one-click Claude
+Desktop install). Runs `npm install --omit=dev` + `npm run build` first unless
+`--skip-build` is set.
+
+```
+mcpmake bundle <directory> [options]
+```
+
+- `<directory>` *(required)* — a generated MCP server project (must have a `package.json`).
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-o, --output <file>` | | Output path for the `.mcpb` file |
+| `--skip-build` | off | Skip `npm install` / build (use if already built) |
+
+## `mcpmake publish`
+
+Generate registry manifests, or publish to the official MCP Registry.
+
+```
+mcpmake publish <directory> [options]
+```
+
+- `<directory>` *(required)* — a generated MCP server project.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-r, --registry <name>` | smithery + glama | Target registry: `official`, `smithery`, or `glama` |
+| `-n, --name <name>` | derived from git remote | `official`: registry name (e.g. `io.github.you/my-server`) |
+| `--remote-url <url>` | | `official`: hosted endpoint to advertise as a remote (streamable-http) |
+| `--push` | off | `official`: run `mcp-publisher publish` after generating `server.json` |
+
+Notes: with no `--registry`, both `smithery.yaml` and `glama.json` are written.
+The `official` flow writes a schema-conformant `server.json`, sets `mcpName` in
+`package.json`, and prints the exact `npm publish` + `mcp-publisher login/publish`
+steps. `--push` requires the external `mcp-publisher` CLI on `PATH`, a prior
+`mcp-publisher login github`, and an `npm publish` first.
+
+## `mcpmake deploy`
+
+Deploy a spec to the hosting backend and get a running MCP server URL.
+
+```
+mcpmake deploy <spec> [options]
+```
+
+- `<spec>` *(required)* — OpenAPI spec or HAR file (≤ 5 MB; `.yaml`/`.yml`/`.json`/`.har`).
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-n, --name <name>` | derived from spec | Server name |
+| `-s, --server <url>` | `http://localhost:3001` | Cloud backend URL |
+| `-t, --token <token>` | `$MCPMAKE_ADMIN_TOKEN` | Admin token for gated backends |
+
+The admin token falls back to the `MCPMAKE_ADMIN_TOKEN` environment variable when
+`--token` is omitted, and is sent as an `Authorization: Bearer` header.
+
+## `mcpmake ci init`
+
+Generate a GitHub Actions workflow (`.github/workflows/mcpmake.yaml`) that
+regenerates and verifies the server when the spec changes, failing CI on drift.
+
+```
+mcpmake ci init <spec> [options]
+```
+
+- `<spec>` *(required)* — path to the API spec, relative to the repo root.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-o, --output <dir>` | `./mcp-server` | Generated server directory |
+| `-s, --source <adapter>` | `openapi` | Source adapter: `openapi`, `har`, or `postman` |
+| `-n, --name <name>` | | Server name passed to generation |
+| `-t, --transport <mode>` | `stdio` | `stdio` or `http` |
+| `--mcpmake-version <ver>` | `latest` | mcpmake version/tag to pin in CI (e.g. `latest`, `0.1.0`) |
+| `-f, --force` | off | Overwrite an existing workflow file |

package/dist/docs/mcp-2026-07-28-migration.md

@@ -0,0 +1,78 @@
+# MCP 2026-07-28 migration status
+
+The MCP spec revision **2026-07-28** is a **release candidate** (final publishes
+July 28, 2026). It is the largest revision since launch: a stateless core, new
+routing headers, a `server/discover` preflight, a reshaped Tasks extension, and
+authorization hardening.
+
+> **Two facts that bound this work** (verified during implementation):
+> 1. The RC is **explicitly not final** — "Changes may be introduced between the
+>    RC and the final release." Every speculative wire shape below is marked
+>    `VERIFY` in the generated code.
+> 2. The TypeScript SDK is still at protocol **`2025-11-25`** (`@modelcontextprotocol/sdk`
+>    resolves `^1.12.0` → 1.29.0; `LATEST_PROTOCOL_VERSION = "2025-11-25"`). It
+>    does **not** dispatch `server/discover`, the new headers, or the reshaped
+>    Tasks extension, and **still requires the `initialize` handshake**. So the
+>    handshake-removal half is **SDK-gated** — it lands when we bump the pin to
+>    the post-RC SDK.
+
+Primary sources: the official RC post
+(`blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/`) and the
+spec repo SEPs. The versioning page (`modelcontextprotocol.io/specification/versioning`)
+still lists **2025-11-25** as *current*.
+
+## Verified change set (corrects earlier secondary-source notes)
+
+| Change | SEP | Status here |
+| ------ | --- | ----------- |
+| `Mcp-Session-Id` + protocol session removed (stateless) | SEP-2567 | ✅ Shipped (stateless default) |
+| `initialize`/`initialized` removed; version/capabilities in per-request `_meta` | SEP-2575 | ⏳ SDK-gated |
+| `server/discover` preflight | SEP-2575 | ✅ Shipped (hand-rolled) |
+| `Mcp-Method` **and** `Mcp-Name` routing headers | SEP-2243 | ✅ Logged + forwarded |
+| `MCP-Protocol-Version: 2026-07-28` header | — | ✅ Advertised in discover; ⏳ enforcement SDK-gated |
+| Tasks extension: `tasks/get`/`update`/`cancel`; **no `tasks/list`**; tool returns a handle | — | ✅ Shipped (hand-rolled) |
+| OAuth: `iss` validation, `application_type` in DCR, issuer binding, `.well-known` discovery | SEP-2468/837/2352/2351 | ✅ RFC 8414 `.well-known` route; rest mostly client-side |
+| ~~OAuth DCR → CIMD~~ | — | ❌ **Does not exist** — secondary-source error. DCR is retained. |
+
+Deprecated in the RC (12-month grace): **Roots, Sampling, MCP Logging**.
+mcpmake's generated servers use **none** of these (logging is structured JSON
+to stderr), so there is nothing to remove.
+
+## What shipped (generated HTTP servers)
+
+All additive and flag-guarded so current SDK-1.12+ clients keep working.
+Verified by emitting an HTTP+OAuth+async project and running `tsc --noEmit` +
+runtime smoke against the real SDK (1.29).
+
+- **Stateless transport by default** — per-request `StreamableHTTPServerTransport({ sessionIdGenerator: undefined })` with a **fresh `McpServer` per request** (a shared server connected to many transports races on its internal transport reference). Set **`MCP_STATEFUL=true`** to keep session mode (one shared server + transport). `initialize` round-trips in both modes.
+- **`server/discover`** — hand-rolled: `POST /mcp` bodies are peeked; a `server/discover` JSON-RPC request is answered directly (capabilities: tool count, declared extensions, `protocolRevision`, `cacheTtlSeconds`) without touching the SDK transport. Body is then replayed to the transport via its `parsedBody` argument.
+- **`Mcp-Method` / `Mcp-Name`** — logged for observability; never rejected.
+- **Tasks extension** — `tasks/get`/`tasks/update`/`tasks/cancel` JSON-RPC intercepts backed by the existing task manager; `tasks/list` returns method-not-found; `isAsync` tools answer `tools/call` with a `{ task: { taskId, status } }` handle and run the work in the background. REST `/tasks/*` endpoints retained during the grace period.
+- **`.well-known/oauth-authorization-server`** (RFC 8414) — public GET route when the server has OAuth; reuses `getAuthServerMetadata`. (No CIMD — that was a research error.)
+
+## What shipped (mcpmake Cloud)
+
+The backend was already stateless: one container per tenant, the proxy forwards
+all headers verbatim except hop-by-hop. Regression tests now assert
+`Mcp-Method`/`Mcp-Name`/`Mcp-Session-Id`/`MCP-Protocol-Version` pass through to
+the container unchanged and that `GET /mcp` proxies. No backend code change was
+needed; see `deploy/Caddyfile.example` for the round-robin payoff note.
+
+## SDK-gated follow-ups (do when the post-RC SDK ships)
+
+1. Bump the generated `@modelcontextprotocol/sdk` pin to the version that
+   implements 2026-07-28, then remove the in-template `server/discover`/Tasks
+   hand-rolls in favor of native SDK dispatch where available.
+2. With that SDK: `initialize`/`initialized` removal + per-request `_meta`
+   (version/clientInfo/capabilities) become real; enforce/advertise
+   `MCP-Protocol-Version: 2026-07-28`.
+3. Re-verify every `VERIFY`-marked wire shape (`server/discover` result fields,
+   Tasks envelopes, the `isAsync` task-handle shape) against the **final** spec
+   once published, and align field names.
+
+## VERIFY checklist (re-confirm before the final spec)
+
+- [ ] `server/discover` result fields: `server`, `protocolRevision`, `capabilities`, `extensions`, `cacheTtlSeconds`.
+- [ ] `Mcp-Method` / `Mcp-Name` exact semantics (we only log them).
+- [ ] Tasks wire: `tasks/get`/`update`/`cancel` params + result fields; the `tools/call` task-handle envelope.
+- [ ] OAuth `application_type` / `iss` / issuer-binding handling if generated servers act as the authorization server.

package/dist/docs/migrate-from-stainless.md

@@ -0,0 +1,94 @@
+# Migrate off Stainless to an MCP server you own
+
+Stainless was acquired by Anthropic (~May 2026) and its hosted MCP generator is
+winding down. If you have an MCP server generated/hosted by Stainless, this
+guide moves you to an **mcpmake** server you fully own: editable code you can run
+anywhere, kept in sync with your spec by CI, with self-hosting and your existing
+inputs preserved.
+
+## What you keep and gain
+
+| | Stainless (hosted generator) | mcpmake |
+| --- | --- | --- |
+| Generated code | Managed for you | **Yours** — exported, editable, committed to your repo |
+| Hosting | Their platform | Self-host (Docker), your VPS, or mcpmake Cloud |
+| Input | OpenAPI spec | OpenAPI **+** HAR / Postman / live website / plain-English describe |
+| Spec sync | Auto-regenerate on spec change | `mcpmake ci init` — same workflow, in your CI |
+| Lock-in | Platform-managed | None — plain TypeScript (or Python) you control |
+
+## Migrate in five steps
+
+### 1. Find your source of truth
+
+Use the same OpenAPI spec Stainless generated from (often `openapi.yaml` /
+`openapi.json` in your API repo, or your provider's published spec). No spec?
+See [No spec?](#no-spec) below.
+
+### 2. Generate a server you own
+
+```bash
+# HTTP server (for remote/hosted use); drop -t http for stdio/local
+mcpmake from openapi ./openapi.yaml -o ./my-mcp-server -t http
+```
+
+The output is a complete, self-contained project: tools, auth wiring, schemas,
+tests, a Dockerfile, and a README. Commit it — it's yours to edit.
+
+> Large API (50+ operations)? Add `--dynamic-discovery` so the agent loads tool
+> schemas on demand instead of paying upfront token cost for every tool.
+
+### 3. Review and own it
+
+Open `my-mcp-server/`. Each tool is a readable file under `src/tools/`; auth is
+in `src/auth.ts`; the HTTP/transport entry is `src/index.ts`. Edit anything —
+there's no hidden runtime.
+
+```bash
+cd my-mcp-server && npm install && npm run build && npm test
+```
+
+### 4. Keep it in sync with the spec (the Stainless habit)
+
+```bash
+mcpmake ci init ./openapi.yaml -o ./my-mcp-server
+```
+
+This writes `.github/workflows/mcpmake.yaml`, which on every spec change
+regenerates the server, runs `mcpmake verify`, and **fails CI if the committed
+server has drifted from the spec** — the auto-regenerate-on-spec-change
+guarantee, now in your own repo.
+
+### 5. Run it
+
+- **Self-host:** the generated `Dockerfile` builds a hardened, non-root,
+  read-only-filesystem container. Set the bearer token your client sends as
+  `MCP_AUTH_TOKEN` and run it behind your reverse proxy.
+- **mcpmake Cloud:** `mcpmake deploy ./openapi.yaml` (or use the dashboard) to
+  build + host it with auth, metering, and quotas.
+- **Connect:** point Claude/Cursor at `https://<host>/mcp` with
+  `Authorization: Bearer <token>`.
+
+## No spec?
+
+mcpmake doesn't require an OpenAPI spec — most APIs don't have one:
+
+```bash
+mcpmake from har ./session.har -o ./my-mcp-server        # a browser/devtools recording
+mcpmake from postman ./collection.json -o ./my-mcp-server # a Postman collection
+mcpmake from website https://app.example.com -o ./my-mcp-server   # a live site
+mcpmake from describe "manage GitHub issues" -o ./my-mcp-server   # plain English
+```
+
+## FAQ
+
+**Do I have to change my clients?** No — it still speaks MCP over the same
+`/mcp` endpoint. Update the URL/token to point at your new server.
+
+**Is there a one-click importer?** Not yet. In practice migration is: point
+mcpmake at the same spec, generate, commit, wire up `ci init`. If you only have
+a Stainless config and no spec, export the underlying OpenAPI document and use
+step 2.
+
+**TypeScript or Python?** Both — add `--format python` for a Python server.
+
+**Questions:** support@mcpmake.dev