mcpmake 0.1.0

package/README.md

@@ -0,0 +1,691 @@
+# mcpmake
+
+Generate fully functional [MCP](https://modelcontextprotocol.io/) servers from anything. One command, batteries included.
+
+```bash
+# From an OpenAPI spec (or provider shortcut)
+mcpmake from openapi ./petstore.yaml -o ./petstore-mcp
+mcpmake from openapi stripe -o ./stripe-mcp --include customers,charges
+
+# From a browser recording
+mcpmake from har ./session.har -o ./api-mcp
+
+# From a live website (opens a browser, you interact, close when done)
+mcpmake from url https://app.example.com -o ./app-mcp
+
+# From any website's HTML (forms, buttons, links → Playwright-based MCP server)
+mcpmake from website https://app.example.com -o ./site-mcp
+
+# Re-crawl that site later, heal broken selectors, regenerate
+mcpmake rescan ./site-mcp --write
+
+# From a Postman collection
+mcpmake from postman ./collection.json -o ./api-mcp
+
+# From a plain English description (AI-powered)
+mcpmake from describe "manage GitHub issues" -o ./github-mcp
+
+# Generate Python instead of TypeScript
+mcpmake from openapi ./spec.yaml -o ./api-mcp --format python
+
+# Deploy to mcpmake Cloud
+mcpmake deploy ./spec.yaml
+
+# Publish to Smithery/Glama registries
+mcpmake publish ./my-mcp-server
+```
+
+Produces a complete MCP server (TypeScript or Python) with typed tools, resources, prompts, auth, retries, rate limiting, and structured errors — ready for Claude Desktop or any MCP client.
+
+## Why
+
+The official `create-mcp-server` scaffolding gives you an empty shell. Writing tool definitions, wiring up auth, handling errors, and converting schemas by hand is tedious and repetitive. mcpmake does it all from your existing API spec, a browser recording, a live website, or even a plain English description.
+
+## Quick Start
+
+> **Not yet on npm.** Until the first release is published, install from source:
+> `git clone` this repo, `npm install && npm run build`, then `npm link` (or run
+> `npx tsx src/index.ts ...`). The `npm install -g mcpmake` line below applies
+> once published.
+
+```bash
+# Install (after first npm release)
+npm install -g mcpmake
+
+# Generate from an OpenAPI spec
+mcpmake from openapi ./api-spec.yaml -o ./my-mcp-server
+
+# Or use a provider shortcut
+mcpmake from openapi github -o ./github-mcp
+
+# Run the generated server
+cd my-mcp-server
+cp .env.example .env   # fill in your API credentials
+npm install
+npm run build
+npm start
+```
+
+### Keep it in sync with your spec (CI)
+
+```bash
+# Writes .github/workflows/mcpmake.yaml — regenerates + verifies the server
+# on every spec change, and fails CI if the committed output is out of date.
+mcpmake ci init ./api-spec.yaml -o ./my-mcp-server
+```
+
+> **Coming from Stainless?** See [Migrate off Stainless to an MCP server you own](docs/migrate-from-stainless.md).
+
+### Project config (`.mcpmake.yaml`)
+
+Stop repeating CLI flags — drop a `.mcpmake.yaml` in your project root and commit it so your team shares the same generation settings. It's auto-discovered from the working directory (override with `--config <path>` or `MCPMAKE_CONFIG`).
+
+```yaml
+# .mcpmake.yaml
+output: ./generated # global defaults for every command
+transport: http
+format: typescript
+
+openapi: # optional per-command overrides
+  base-url: https://api.example.com
+  include: [users, repos] # arrays become the --include users,repos form
+deploy:
+  server: https://mcpmake.dev
+```
+
+```bash
+# With the config above, this is equivalent to
+#   mcpmake from openapi ./api-spec.yaml -o ./generated -t http -b https://api.example.com -i users,repos
+mcpmake from openapi ./api-spec.yaml
+```
+
+**Precedence (highest wins):** explicit CLI flag → per-command section → global key → built-in default. Positional args (the spec path) always stay on the command line. See [`.mcpmake.example.yaml`](.mcpmake.example.yaml). Supported by every `from` generator and `deploy`.
+
+## What Gets Generated
+
+```
+my-mcp-server/
+├── package.json          # 2 runtime deps: @modelcontextprotocol/sdk + zod
+├── tsconfig.json
+├── Dockerfile            # (with --transport http) production-ready, non-root, read-only
+├── .env.example          # Pre-filled with base URL + auth vars
+├── README.md             # Tool docs + Claude Desktop config snippet
+├── .gitignore
+├── src/
+│   ├── index.ts           # McpServer bootstrap (stdio or HTTP transport)
+│   ├── config.ts          # Environment config loader + validation
+│   ├── auth.ts            # Auth header injection
+│   ├── http.ts            # fetch wrapper: retries, backoff, rate limiting
+│   ├── types.ts           # Shared types
+│   ├── resources.ts       # MCP resources (GET list endpoints)
+│   ├── prompts.ts         # MCP prompts (tag-grouped workflows)
+│   └── tools/
+│       ├── index.ts       # registerAllTools(server, config)
+│       ├── list-pets.ts   # One file per API operation
+│       ├── create-pet.ts
+│       └── get-pet.ts
+└── test/tools/
+    ├── list-pets.test.ts  # Test scaffolds (vitest)
+    ├── create-pet.test.ts
+    └── get-pet.test.ts
+```
+
+Each tool file is self-contained, clean, and designed to be edited after generation.
+
+## Input Adapters
+
+### `from openapi` — OpenAPI Specs
+
+Parse any OpenAPI 3.x spec and generate one tool per operation. Supports YAML/JSON, local files and URLs, and full `$ref` dereferencing.
+
+**Provider shortcuts** — skip the spec URL for popular APIs:
+
+```bash
+mcpmake from openapi stripe -o ./stripe-mcp --include customers,charges
+mcpmake from openapi github -o ./github-mcp --include repos,issues
+mcpmake from openapi slack -o ./slack-mcp --include chat,users
+```
+
+Available providers: `stripe`, `github`, `slack`, `notion`, `linear`, `shopify`
+
+### `from har` — Browser Recordings
+
+Record a session in Chrome/Firefox DevTools (Network tab -> Export HAR), and mcpmake will:
+
+- **Filter noise** — removes favicon, analytics, CDN, and static asset requests automatically
+- **Detect path parameters** — recognizes numeric IDs, UUIDs, and MongoDB ObjectIDs
+- **Cluster requests** — groups `GET /users/42` and `GET /users/99` into one `get_user` tool
+- **Infer schemas** — extracts Zod schemas from JSON request/response bodies
+- **Detect auth** — finds Bearer tokens, API keys, and Basic auth in headers
+
+```bash
+mcpmake from har ./session.har -o ./api-mcp --domain api.example.com
+```
+
+### `from url` — Live Website Recording
+
+Point mcpmake at any URL and it opens a browser. Click around, interact with the site, and when you close the browser it generates an MCP server from the captured API traffic.
+
+```bash
+mcpmake from url https://app.example.com -o ./app-mcp
+```
+
+Uses Playwright under the hood. Requires `npx playwright install chromium` on first use.
+
+**Headless / CI capture** — for automated environments where no one can drive a window, run headless and auto-visit a set of same-origin paths to surface their API calls:
+
+```bash
+mcpmake from url https://app.example.com -o ./app-mcp \
+  --headless --navigate /dashboard,/orders,/settings
+```
+
+`--navigate` takes a comma-separated list of absolute or relative same-origin URLs; cross-origin targets are skipped. The browser loads each, captures the traffic, and exits — no manual interaction needed.
+
+### `from postman` — Postman Collections
+
+Import a Postman Collection v2.1 and generate tools from its requests:
+
+```bash
+mcpmake from postman ./collection.json -o ./api-mcp
+```
+
+### `from website` — Website DOM Analysis
+
+Analyze any website's HTML structure (forms, buttons, links) and generate a Playwright-based MCP server with site-specific tools:
+
+```bash
+mcpmake from website https://app.example.com -o ./site-mcp
+mcpmake from website https://shop.example.com -o ./shop-mcp --depth 3 --max-pages 30
+mcpmake from website https://app.example.com -o ./site-mcp --goal "complete checkout flow"
+mcpmake from website https://app.example.com -o ./site-mcp --hybrid --improve-names
+```
+
+Unlike generic browser MCP servers (Playwright MCP, Puppeteer MCP), this generates **site-specific tools** like `login(email, password)` instead of generic `click(selector)`. Features:
+
+- **Multi-strategy selectors** — data-testid > id > aria-label > name > CSS path > XPath
+- **Resilient selectors at runtime** — each generated tool tries its primary selector and then every fallback, so a tool keeps working when the page's DOM shifts instead of failing on the first broken selector
+- **Page-level tools** — one tool per form (e.g., `login`, `search`, `subscribe`)
+- **Action-level tools** — one tool per standalone button
+- **Browser lifecycle** — `start_browser`, `stop_browser`, `take_screenshot`
+- **Session management** — persistent browser sessions via `sessionId`
+- **LLM-powered naming** — Claude infers semantic tool names from page context (`--improve-names`)
+- **Goal-directed crawl** — `--goal` flag for AI-driven navigation toward a specific objective
+- **Hybrid mode** — `--hybrid` uses HTTP fetch for API-backed forms, Playwright for HTML-only forms
+- **Auth detection** — automatically detects login forms, OAuth buttons, session cookies
+- **Drift rescan** — re-crawl the site later and self-heal broken selectors with [`mcpmake rescan`](#mcpmake-rescan)
+
+When the site changes, run `mcpmake rescan ./site-mcp` to diff the live site against the embedded snapshot, heal low-confidence selectors, and (with `--write`) regenerate the server in place.
+
+See **[Website MCP servers](docs/website-servers.md)** for the full `from url` / `from website` / `rescan` workflow, headless capture, and the runtime selector-resilience details.
+
+### `from describe` — Natural Language (AI-Powered)
+
+Describe what you want in plain English, and Claude generates an OpenAPI spec, which is then piped through the full generation pipeline.
+
+```bash
+export ANTHROPIC_API_KEY=your-key
+mcpmake from describe "manage GitHub issues and pull requests" -o ./github-mcp
+mcpmake from describe "a todo list API" -o ./todo-mcp --save-spec ./todo-spec.json
+```
+
+## Features
+
+### Output Formats
+
+Generate servers in TypeScript (default) or Python:
+
+```bash
+mcpmake from openapi ./spec.yaml -o ./my-server --format python
+```
+
+Python output uses the `mcp` SDK + `httpx`, producing a single `server.py` + `requirements.txt`.
+
+### Deployment Targets
+
+Generate for Node.js (default) or **Cloudflare Workers**:
+
+```bash
+mcpmake from openapi ./spec.yaml -o ./my-worker --target cloudflare
+```
+
+The Workers target emits a stateless JSON-RPC Fetch handler (no `node:http`, no
+SDK transport — the MCP 2026‑07‑28 stateless transport maps 1:1 onto a Worker
+request) plus `wrangler.toml`. Deploy with `wrangler deploy`; Cloudflare's free
+plan covers 100K requests/day. Secrets (API credentials + the MCP bearer token)
+are injected via the `env` binding (`wrangler secret put`), not `process.env`.
+Available on all spec adapters (`openapi`, `postman`, `har`, `url`, `describe`).
+v1 emits **tools** — for resources, prompts, the Tasks extension, or OAuth2
+outbound auth, use the default `--target node`.
+
+### Full MCP Primitive Support
+
+Generated servers include all three MCP primitives:
+
+- **Tools** — one per API operation, with Zod input schemas
+- **Resources** — GET list endpoints exposed as readable resources
+- **Prompts** — tag-grouped workflow prompts listing available tools
+
+### Auth Detection
+
+Security schemes are auto-detected from specs and HAR headers:
+
+| Source                | Detected As             | Env Var                             |
+| --------------------- | ----------------------- | ----------------------------------- |
+| OpenAPI `apiKey`      | Custom header/query     | `API_KEY`                           |
+| OpenAPI `http` bearer | `Authorization: Bearer` | `BEARER_TOKEN`                      |
+| OpenAPI `http` basic  | `Authorization: Basic`  | `BASIC_USERNAME` / `BASIC_PASSWORD` |
+| OpenAPI `oauth2`      | Bearer (pre-obtained)   | `OAUTH2_TOKEN`                      |
+| HAR Bearer header     | Bearer token            | `BEARER_TOKEN`                      |
+| HAR custom headers    | API key                 | `API_KEY`                           |
+
+### HTTP Executor
+
+Generated servers include a production-grade HTTP client:
+
+- Exponential backoff with `Retry-After` header support
+- Retries on 429, 500, 502, 503, 504
+- Configurable rate limiting (min interval between requests)
+- Structured `ApiError` with status code and response body
+
+### Dual Transport
+
+- **stdio** (default) — for Claude Desktop, Claude Code, local use
+- **HTTP** (`--transport http`) — for remote deployment with:
+  - Stateful sessions via `Mcp-Session-Id`
+  - Origin validation (DNS-rebinding protection per MCP spec)
+  - `/health` and `/ready` endpoints
+  - Graceful shutdown on `SIGTERM`
+  - Structured JSON logging
+  - Production Dockerfile (non-root, read-only, multi-stage build)
+
+### Security
+
+- **Input sanitization** — all user-controlled strings sanitized before embedding in generated code
+- **Path traversal protection** — generated file paths validated to stay within output directory
+- **Secret redaction** — auth tokens from HAR headers never included in generated code
+- **Prototype pollution defense** — dangerous keys filtered during schema inference
+- **Size limits** — HAR files capped at 50 MB, schema inference depth-limited to 20 levels
+- **Generated code audit** — scans for dangerous patterns before Docker image build
+
+### Operation Filtering
+
+All adapters support `--include` and `--exclude` to select operations by tag, path glob, or operationId:
+
+```bash
+mcpmake from openapi ./spec.yaml -o ./out --include pets --exclude delete
+mcpmake from openapi ./spec.yaml -o ./out --exclude "/admin*,/internal*"
+```
+
+## Additional Commands
+
+### `mcpmake verify`
+
+Check that a generated project still matches its source spec (useful in CI):
+
+```bash
+mcpmake verify ./spec.yaml -p ./my-mcp-server
+```
+
+### `mcpmake update`
+
+Re-generate a project from an updated spec, showing what changed:
+
+```bash
+mcpmake update ./spec.yaml -p ./my-mcp-server
+```
+
+### `mcpmake rescan`
+
+The website counterpart to `update`: re-crawl the target of a `from website`
+project, diff it against the snapshot embedded at generation time, self-heal
+broken selectors, and optionally regenerate the server in place.
+
+```bash
+# Report what changed (and which selectors are fragile) — no writes
+mcpmake rescan ./site-mcp
+
+# Heal low-confidence selectors via the page's accessibility tree (needs ANTHROPIC_API_KEY)
+ANTHROPIC_API_KEY=... mcpmake rescan ./site-mcp
+
+# Regenerate the project in place from the fresh, healed snapshot
+mcpmake rescan ./site-mcp --write
+
+# Machine-readable diff for CI
+mcpmake rescan ./site-mcp --format json
+```
+
+How it works:
+
+- Reads the snapshot from `src/site-descriptor.json` and the regeneration
+  settings from `mcpmake.site.json` (both written by `from website`).
+- Re-crawls the live site (override the URL with `--url`; crawl bounds default
+  from the snapshot, override with `--depth` / `--max-pages`).
+- Diffs old vs new and reports added/removed/modified pages, forms, fields,
+  buttons, and links, plus selectors that broke.
+- **Self-healing:** for fragile (low-confidence) selectors, it asks Claude for a
+  better one from the live accessibility tree and only applies it if it actually
+  resolves on the page. Skipped (with a warning) when `ANTHROPIC_API_KEY` is unset.
+- `--write` regenerates the project (overwrites generated files, like `update`).
+
+### `mcpmake deploy`
+
+Deploy a spec to mcpmake Cloud and get a running MCP server at a URL:
+
+```bash
+mcpmake deploy ./spec.yaml --name my-api
+# Returns: endpoint URL, bearer token, Claude Desktop config snippet
+```
+
+### `mcpmake publish`
+
+Generate registry manifests, or publish to the official MCP Registry:
+
+```bash
+mcpmake publish ./my-mcp-server                     # smithery.yaml + glama.json (default)
+mcpmake publish ./my-mcp-server --registry smithery # smithery.yaml only
+mcpmake publish ./my-mcp-server --registry glama    # glama.json only
+
+# Official MCP Registry (registry.modelcontextprotocol.io)
+mcpmake publish ./my-mcp-server --registry official                 # writes server.json + sets package.json mcpName
+mcpmake publish ./my-mcp-server --registry official --name io.github.you/my-server
+mcpmake publish ./my-mcp-server --registry official --remote-url https://my-server.example.com/mcp
+mcpmake publish ./my-mcp-server --registry official --push          # runs `mcp-publisher publish`
+```
+
+For `official`, mcpmake builds a schema-conformant `server.json`, sets the
+`mcpName` marker in `package.json`, and prints the exact `npm publish` +
+`mcp-publisher login/publish` steps. `--name` defaults to a namespaced id
+derived from your git remote; `--push` requires the `mcp-publisher` CLI (after
+`mcp-publisher login github` and an `npm publish`).
+
+### `mcpmake bundle`
+
+Bundle a generated project into an `.mcpb` file for one-click Claude Desktop
+install (builds the project first unless `--skip-build`):
+
+```bash
+mcpmake bundle ./my-mcp-server -o ./my-mcp-server.mcpb
+mcpmake bundle ./my-mcp-server --skip-build    # if already built
+```
+
+### `mcpmake lint`
+
+MCP-specific linting for OpenAPI specs (useful in CI):
+
+```bash
+mcpmake lint ./spec.yaml
+mcpmake lint ./spec.yaml --format json    # machine-readable output
+mcpmake lint ./spec.yaml --level warn     # filter by severity
+```
+
+Rules: tool name length (60/128 char limits), description quality, parameter count, duplicate names, missing annotations, reserved names. Exits with code 1 on errors.
+
+### `mcpmake diff`
+
+Compare two specs and show which MCP tools changed:
+
+```bash
+mcpmake diff ./old-spec.yaml ./new-spec.yaml
+mcpmake diff ./old-spec.yaml ./new-spec.yaml --format json
+```
+
+Shows added, removed, and changed tools with parameter-level detail.
+
+### `mcpmake merge`
+
+Combine multiple API specs into one MCP server:
+
+```bash
+mcpmake merge ./users-api.yaml ./orders-api.yaml -o ./combined.yaml
+```
+
+## Advanced Features
+
+### Swagger 2.0 Support
+
+Swagger 2.0 specs are automatically converted to OpenAPI 3.0 on ingest:
+
+```bash
+mcpmake from openapi ./swagger-v2.json -o ./my-server  # auto-detected
+```
+
+### OpenAPI Overlays
+
+Customize a spec non-destructively without editing the source:
+
+```bash
+mcpmake from openapi ./spec.yaml --overlay ./my-overrides.yaml -o ./my-server
+```
+
+Overlay format:
+
+```yaml
+overlay: 1.0.0
+actions:
+  - target: "$.paths['/users'].get"
+    update:
+      x-mcp-name: list_all_users
+      x-mcp-description: 'Retrieve all registered users'
+  - target: "$.paths['/admin/*']"
+    remove: true
+```
+
+### MCP Extensions
+
+Custom `x-mcp-*` extensions in your OpenAPI spec:
+
+```yaml
+paths:
+  /users:
+    get:
+      x-mcp-name: list_users # override tool name
+      x-mcp-description: 'Get users' # override description
+      x-mcp-emit: skip # skip this operation
+      x-mcp-scope: read # semantic scope hint
+      x-mcp-jq-filter: '.data' # trim response before returning
+      x-mcp-deprecation-message: 'Use /v2/users instead'
+      x-mcp-deprecation-replacement: list_users_v2
+      x-mcp-unknown-values: allow # accept unknown enum values
+```
+
+## CLI Reference
+
+Every command, argument, flag, default, and required env var is documented in
+the complete **[CLI reference → `docs/cli.md`](docs/cli.md)**. You can also run
+`mcpmake <command> --help` for the live, authoritative flag list.
+
+| Command | Purpose |
+| --- | --- |
+| [`from openapi`](docs/cli.md#mcpmake-from-openapi) | Generate from an OpenAPI/Swagger spec or provider shortcut |
+| [`from har`](docs/cli.md#mcpmake-from-har) | Generate from a HAR (browser DevTools) recording |
+| [`from url`](docs/cli.md#mcpmake-from-url) | Generate by recording a live browser session |
+| [`from postman`](docs/cli.md#mcpmake-from-postman) | Generate from a Postman Collection (v2.1) |
+| [`from website`](docs/cli.md#mcpmake-from-website) | Generate a Playwright server from a site's DOM |
+| [`from describe`](docs/cli.md#mcpmake-from-describe) | Generate from a natural-language description (AI) |
+| [`merge`](docs/cli.md#mcpmake-merge) | Merge two OpenAPI specs into one |
+| [`diff`](docs/cli.md#mcpmake-diff) | Compare tools generated from two specs |
+| [`lint`](docs/cli.md#mcpmake-lint) | Lint an OpenAPI spec for MCP issues |
+| [`verify`](docs/cli.md#mcpmake-verify) | Check a generated project still matches its spec |
+| [`update`](docs/cli.md#mcpmake-update) | Re-generate a project from a changed spec |
+| [`rescan`](docs/cli.md#mcpmake-rescan) | Re-crawl a website project, heal selectors, regenerate |
+| [`bundle`](docs/cli.md#mcpmake-bundle) | Bundle a generated project into an `.mcpb` file |
+| [`publish`](docs/cli.md#mcpmake-publish) | Generate registry manifests / publish to the MCP Registry |
+| [`deploy`](docs/cli.md#mcpmake-deploy) | Deploy a spec to the hosting backend |
+| [`ci init`](docs/cli.md#mcpmake-ci-init) | Generate a GitHub Actions drift-check workflow |
+
+## Architecture
+
+```
+Input Source (OpenAPI / HAR / URL / Description)
+  -> Parser (load, extract operations, convert schemas)
+    -> Transformer (build tools + resources + prompts, detect auth)
+      -> Emitter (render Handlebars templates, write project to disk)
+        -> Runnable MCP Server (stdio or HTTP)
+```
+
+Two parallel pipelines share the emitter infrastructure:
+
+- **API pipeline**: OpenAPI/HAR/URL/Postman/Describe → `OperationDescriptor[]` → HTTP-fetch MCP server
+- **Website pipeline**: Website URL → `SiteDescriptor` → Playwright-based MCP server
+
+### Project Layout
+
+```
+src/
+├── parser/               # Input adapters (OpenAPI, HAR, Postman)
+├── analyzer/             # Website DOM analysis (crawler, forms, selectors, screenshots)
+├── transformer/          # Tool/resource/prompt building, auth, naming, filtering
+├── site-transformer/     # Website → site-specific tool generation
+├── emitter/              # Template rendering, code writing, project scaffolding
+│   ├── templates/        # Handlebars templates for TypeScript servers
+│   ├── site-templates/   # Templates for Playwright-based servers
+│   └── python-templates/ # Templates for Python servers
+├── generator/            # AI-powered spec generation (Claude API)
+├── recorder/             # Playwright browser recorder (interactive + headless capture)
+├── rescan/               # Site diff + self-heal engine (powers `mcpmake rescan`)
+├── providers/            # Pre-built configs for popular APIs
+├── plugins/              # Adapter plugin system
+├── cloud/                # Hosting backend (server, containers, billing, DB)
+│   ├── db/               # PostgreSQL stores and migrations
+│   ├── billing/          # Usage tracking and plan enforcement
+│   └── web/              # Dashboard, auth, admin panel
+├── commands/             # CLI commands (from/*, verify, update, rescan, deploy, publish)
+├── pricing.ts            # Canonical Family A price card (served at /api/pricing)
+├── types/                # Shared TypeScript types
+└── utils/                # Logger, filesystem, sanitization helpers
+```
+
+## Pricing
+
+The CLI is **free forever** — generate code you own and run it anywhere. Paid
+tiers cover keeping it in sync and running it for you.
+
+| Tier                     | Price              | What you get                                                  |
+| ------------------------ | ------------------ | ------------------------------------------------------------- |
+| **Local compiler (CLI)** | **Free forever**   | Generate, own the code, run anywhere.                         |
+| **Sync — Solo**          | **$19/mo**         | CI drift-check + spec-currency auto-PRs, 1 repo.              |
+| **Sync — Team**          | **$499/mo**        | Multi-repo CI sync, policy checks, support.                   |
+| **Self-hosted license**  | **from $8,000/yr** | Run the generator + sync on your own infra; governance + SLA. |
+| **Migration engagement** | **$5,000–$20,000** | Done-for-you API → owned MCP servers + CI wiring.             |
+| **Managed hosting**      | convenience add-on | We host code you already own — self-host any time. See below. |
+| **Enterprise**           | custom             | SSO, RBAC, private registry, audit.                           |
+
+Prices are served live from the backend (`GET /api/pricing`) and defined in
+[`src/pricing.ts`](src/pricing.ts), so the CLI never shows stale numbers.
+Managed hosting is a convenience tier, not the anchor — the value you own is the
+editable code and safe regeneration.
+
+## mcpmake Cloud
+
+Hosted platform for deploying generated MCP servers as containers:
+
+- **Spec upload API** — `POST /api/servers` accepts specs, returns endpoint + bearer token
+- **Container management** — Docker-based with resource limits (HTTP: 256MB/0.5CPU, Playwright: 768MB/1CPU)
+- **Security** — read-only containers, non-root user, code auditing, bearer auth, encrypted secrets (AES-256-GCM)
+- **Auto-scaling** — idle containers stopped automatically, dynamic routing
+- **Monitoring** — per-server metrics, log streaming via SSE, rate limiting
+- **Web dashboard** — register/login, server CRUD, logs, metrics, billing, admin panel
+- **Billing** — browser-minute metering, plan quotas, Stripe payment integration
+- **Database** — PostgreSQL with in-memory fallback, automatic migrations
+- **Deployment** — VPS setup scripts, PM2/nginx, nightly pg_dump backups
+
+```bash
+# Deploy to mcpmake.dev
+mcpmake deploy ./petstore.yaml --server https://mcpmake.dev
+```
+
+### Admin dashboard
+
+The admin panel adds operational visibility and growth levers on top of the
+per-server views:
+
+- **Promotional tool-call credits** — grant or revoke bonus tool-calls per user
+  from the dashboard. Credits are consumed (all-or-nothing, atomically) when a
+  user is over their plan quota, _before_ the 429 hard cap. Every grant/revoke is
+  recorded in an auditable **ledger** (newest-first; per-request consumption is
+  intentionally not ledgered).
+- **Time-series charts** — server-rendered, script-free inline SVG (sparklines,
+  bar charts, and a requests-vs-errors dual line) backed by periodic metric
+  samples. CSP-safe: no inline JS, hover values via `<title>` only.
+- **Health panel** — host RAM/disk pressure, active containers, and totals at a
+  glance.
+- **API failure-rate** — a rolling per-minute tracker classifies responses by
+  status class (2xx/3xx/4xx/5xx) plus aborted requests, surfacing a
+  server-error rate (`(5xx + aborted) / total`) and client-error rate.
+- **CLI telemetry viewer** — opt-in crash reports grouped by fingerprint with
+  counts and last-seen, hardened against abuse (size cap, no decompression,
+  per-IP rate limit, strict field whitelist).
+
+### Public API endpoints
+
+Two endpoints are public (unauthenticated) and stable:
+
+| Endpoint                     | Purpose                                                                                                                                                                                            |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /api/pricing`           | Canonical Family A price card (the CLI fetches this so an old binary never prints stale prices; falls back to its bundled copy when unreachable).                                                  |
+| `POST /api/telemetry/report` | Receives opt-in, pre-redacted CLI crash reports. Returns **202** on accept; **400** (malformed/empty), **413** (oversized), **415** (`Content-Encoding` set), or **429** (rate-limited) on reject. |
+
+### Configuration
+
+Environment variables for the cloud backend:
+
+| Variable                | Required | Description                                                     |
+| ----------------------- | -------- | --------------------------------------------------------------- |
+| `DATABASE_URL`          | Yes      | PostgreSQL connection string                                    |
+| `PORT`                  | No       | Server port (default: 3001)                                     |
+| `DOMAIN`                | Yes      | Domain for hosted servers                                       |
+| `TRUST_PROXY`           | No       | Trust X-Forwarded headers                                       |
+| `ADMIN_TOKEN`           | Yes      | Admin API auth token                                            |
+| `ENCRYPTION_KEY`        | Yes      | 32+ char key for AES-256-GCM secrets                            |
+| `ALLOWED_EMAILS`        | No       | Comma-separated allowlist (e.g. `*@company.com,user@gmail.com`) |
+| `STRIPE_SECRET_KEY`     | No       | Stripe API key for payments                                     |
+| `STRIPE_WEBHOOK_SECRET` | No       | Stripe webhook signature secret                                 |
+| `ANTHROPIC_API_KEY`     | No       | For AI-powered features                                         |
+
+## Development
+
+```bash
+git clone <repo>
+cd mcpmake
+npm install
+npm run build
+
+# Run without building
+npx tsx src/index.ts from openapi ./test/fixtures/petstore.yaml -o /tmp/test-mcp
+
+# Type check
+npm run typecheck
+
+# Run tests (263 tests across 39 files)
+npm test
+
+# Release smoke tests (validate the packaged binary + a generated server)
+npm run smoke:pack
+npm run smoke:server
+
+# Format code
+npm run format
+```
+
+## Supported Inputs
+
+| Input       | Format         | Notes                                          |
+| ----------- | -------------- | ---------------------------------------------- |
+| OpenAPI     | 3.0.x, 3.1.x   | YAML/JSON, local/remote                        |
+| HAR         | 1.2            | Chrome/Firefox DevTools export                 |
+| URL         | http/https     | Playwright browser recording                   |
+| Website     | http/https     | DOM analysis, Playwright MCP server            |
+| Postman     | v2.1           | Collection import                              |
+| Description | Plain English  | Claude-powered spec generation                 |
+| Providers   | Shortcut names | stripe, github, slack, notion, linear, shopify |
+
+## Requirements
+
+- Node.js >= 20.0.0
+- Playwright (`npx playwright install chromium`) for `from url` command
+- `ANTHROPIC_API_KEY` for `from describe` command
+- Docker for `mcpmake deploy` / Cloud hosting
+
+## License
+
+Proprietary. All rights reserved.

package/bin/mcpmake.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';