mcpmake 0.1.1 → 0.2.0

package/dist/docs/quickstart.md

@@ -1,166 +0,0 @@
-# mcpmake Cloud — Quickstart
-
-Turn any API or website into a hosted, authenticated MCP server in about a
-minute, then connect it to Claude, Cursor, or any MCP client.
-
----
-
-## 1. Create an account
-
-1. Go to the dashboard and **register** with your email.
-2. **Verify your email** — we send a confirmation link. You must verify before
-   you can deploy a server. (Need another link? Use **Resend** on the dashboard.)
-
-## 2. Deploy a server
-
-From **Dashboard → New Server**, pick a source:
-
-| Source                 | What to provide                                                                                               | Result                                                                    |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| **Upload file**        | An OpenAPI/Swagger spec (`.yaml`/`.yml`/`.json`), a HAR recording (`.har`), or a Postman collection (`.json`) | A server with one tool per API operation                                  |
-| **From URL → spec**    | A URL to an OpenAPI spec                                                                                      | Same as upload, fetched for you                                           |
-| **From URL → website** | Any website URL                                                                                               | A Playwright-driven server with tools for the site's interactive elements |
-
-Click **Deploy Server**. When the build finishes you land on the server's
-detail page, which shows your **endpoint** and a **one-time bearer token**.
-
-> **Save the token now.** It is shown only once. If you lose it, re-deploy the
-> server (the API re-deploy path rotates the token) or create a new server.
-
-## 3. Connect your MCP client
-
-Your server is reachable at `https://<slug>.<domain>/mcp` and requires the
-bearer token on every request. Replace `YOUR_TOKEN` with the token you saved.
-
-### Claude Desktop / Cursor
-
-Add to `claude_desktop_config.json` (Claude) or your MCP config (Cursor):
-
-```json
-{
-  "mcpServers": {
-    "my-server": {
-      "url": "https://my-server-a1b2.mcpmake.dev/mcp",
-      "headers": {
-        "Authorization": "Bearer YOUR_TOKEN"
-      }
-    }
-  }
-}
-```
-
-### Claude Code (CLI)
-
-```bash
-claude mcp add my-server https://my-server-a1b2.mcpmake.dev/mcp \
-  --header "Authorization: Bearer YOUR_TOKEN"
-```
-
-Requests without a valid token are rejected (`401`/`403`), so keep the token
-secret — treat it like a password.
-
-## 3a. Keeping a website server fresh
-
-Website (`from website`) servers are generated against a snapshot of the site's
-DOM, so they can drift when the site changes. With the CLI you can re-crawl and
-self-heal an exported project locally:
-
-```bash
-mcpmake rescan ./site-mcp            # report drift + fragile selectors
-mcpmake rescan ./site-mcp --write    # heal selectors and regenerate, then re-deploy
-```
-
-See **[Website MCP servers](website-servers.md)** for the full workflow.
-
-## 4. Add API secrets
-
-If your generated server calls an upstream API that needs credentials (an API
-key, bearer token, basic auth), add them as **Secrets** on the server detail
-page. Secrets are encrypted at rest and injected into the container as
-environment variables. After adding or changing a secret, **re-deploy** the
-server so it picks up the new value.
-
-Common secret names: `API_KEY`, `BEARER_TOKEN`, `BASIC_USERNAME` /
-`BASIC_PASSWORD`. The exact names your server expects are derived from its spec.
-
-## 5. Limits and quotas
-
-Each plan includes:
-
-- a maximum number of **hosted servers**, and
-- a monthly **tool-call** allowance.
-
-When you hit a limit, server creation is blocked (with an upgrade prompt) and
-over-quota tool calls are rejected with `429 Too Many Requests`. Browser-driven
-(website) servers also consume **browser minutes**. See the **Billing** page for
-your current usage and remaining quota.
-
-Idle servers are paused automatically to save resources and resume on the next
-authorized request, so the first call after a quiet period may be slightly
-slower.
-
-## 6. Pricing
-
-> The core product — the `mcpmake` CLI and CI sync — is what you pay for. See
-> the [Pricing](../README.md#pricing) section in the README for the full price
-> card. **Managed hosting (this page) is a convenience add-on**: it hosts code
-> you already own, and you can take it self-hosted at any time.
-
-Managed-hosting plans (priced in **Dashboard → Billing**):
-
-| Plan                         | Hosted servers | Tool calls / mo | Notes                              |
-| ---------------------------- | -------------- | --------------- | ---------------------------------- |
-| **Free**                     | 1              | ~1,000          | All input modes enabled            |
-| **Hobbyist**                 | 3              | ~10,000         |                                    |
-| **Pro**                      | 5              | ~100,000        | Secrets, dev/prod, overage billing |
-| **Team**                     | 20             | ~1,000,000      |                                    |
-| **Enterprise / self-hosted** | Unlimited      | Unlimited       | BYO-infra, code ownership          |
-
-Browser-driven (website) servers also consume **browser minutes**, metered
-separately — see the **Billing** page. Upgrade, downgrade, or cancel anytime
-from **Dashboard → Billing** (managed via Stripe). Cancellation takes effect at
-the end of the current period; access downgrades to Free afterward.
-
-## CLI error reporting (telemetry)
-
-When a CLI command fails, mcpmake can send an **opt-in, redacted crash report**
-so we can fix the failures real users hit. It is strictly opt-in and never blocks
-or slows down the CLI.
-
-Control it with the global `telemetry` key in your `.mcpmake.yaml`:
-
-```yaml
-# .mcpmake.yaml
-telemetry: prompt # prompt | auto | off  (default: prompt)
-```
-
-| Mode                 | Behaviour                                                                            |
-| -------------------- | ------------------------------------------------------------------------------------ |
-| `prompt` _(default)_ | On a failure, shows you the exact (already-redacted) report and asks before sending. |
-| `auto`               | Sends silently on failure.                                                           |
-| `off`                | Never sends anything.                                                                |
-
-Regardless of the configured mode, telemetry **auto-degrades to `off` in CI or
-any non-interactive (non-TTY) environment**, so it can never hang a pipeline
-waiting for input.
-
-A crash report contains only: the command name (e.g. `from openapi`), the error
-message and stack trace, the CLI version, your OS/arch, and the Node version. It
-**never** includes file contents, environment variables, or secrets. Before
-sending, mcpmake redacts home-directory paths (`/Users/<you>/…` → `~`), bearer
-tokens, mcpmake `mf_…` tokens, and URL query strings, so credentials embedded in
-paths or URLs don't leak.
-
-## Troubleshooting
-
-- **`401 Unauthorized`** — the `Authorization: Bearer` header is missing or
-  malformed in your client config.
-- **`403 Forbidden`** — the token is wrong. Re-check it, or re-deploy to rotate.
-- **`429 Too Many Requests`** — you've hit your monthly tool-call quota; upgrade
-  your plan or wait for the next period.
-- **`503 Server is not running`** — the server was paused or is rebuilding; try
-  again, or open the server's **Logs** to investigate.
-- **Build failed** — check that your spec is valid and under 5 MB; the server's
-  **Logs** page shows build output.
-
-Questions: support@mcpmake.dev

package/dist/docs/show-hn.md

@@ -1,26 +0,0 @@
-# Show HN: mcpmake -- Turn any API or website into an MCP server in 30 seconds
-
-mcpmake generates fully functional MCP (Model Context Protocol) servers from OpenAPI specs, HAR files, Postman collections, live websites, or plain English descriptions.
-
-Unlike generic browser automation tools (Playwright MCP, Puppeteer MCP) that make the AI rediscover page structure on every call, mcpmake analyzes a website's DOM once and generates **site-specific tools** like `login(email, password)` instead of `click(selector)`.
-
-**What it does:**
-
-- `mcpmake from openapi ./spec.yaml` -- generates a TypeScript MCP server from any OpenAPI spec
-- `mcpmake from website https://app.example.com` -- analyzes HTML forms, buttons, links and generates Playwright-based MCP tools
-- `mcpmake from har ./recording.har` -- turns a browser recording into MCP tools
-- `mcpmake from describe "manage GitHub issues"` -- AI generates the spec, then the server
-- `mcpmake deploy ./spec.yaml` -- deploys to mcpmake.dev, returns a URL + bearer token
-
-**Key differentiators:**
-
-1. **6 input adapters** -- OpenAPI, HAR, URL recording, website DOM, Postman, natural language. Competitors support 1.
-2. **Website-to-MCP** -- the only tool that generates site-specific MCP tools from HTML analysis. No one else does this.
-3. **91-97% token reduction** -- `--dynamic-discovery` mode for large APIs (50+ tools) uses 4 meta-tools instead of flooding the context window.
-4. **Full MCP spec** -- Tools + Resources + Prompts + outputSchema + annotations. Most generators only emit tools.
-5. **Editable output** -- clean TypeScript (or Python) you own and can modify. Not a black-box proxy.
-6. **Cloud hosting** at mcpmake.dev -- upload a spec, get a running MCP server with HTTPS, auth, and metrics.
-
-**Live demo:** https://mcpmake.dev
-
-Built with Node.js, Playwright, Handlebars templates. Generated servers have 2 runtime deps (MCP SDK + Zod).

package/dist/docs/website-servers.md

@@ -1,169 +0,0 @@
-# Website MCP servers — generate, run, and keep them fresh
-
-mcpmake can turn a **website with no API spec** into an MCP server in two ways.
-Both drive a real browser; the difference is what they capture.
-
-| Command | Captures | Generates | Runtime |
-| --- | --- | --- | --- |
-| `mcpmake from url` | the site's **network/API traffic** while it loads/you interact | an HTTP-fetch MCP server (one tool per API call) | `fetch` — no browser |
-| `mcpmake from website` | the site's **DOM** (forms, buttons, links) | a Playwright MCP server with site-specific tools | Playwright/Chromium |
-
-If the site is backed by a clean JSON API, prefer `from url` (or `from har`) —
-the output is a lightweight HTTP server. Use `from website` when the only way to
-drive the site is the page itself.
-
-> Requires `npx playwright install chromium` on first use of either command.
-
----
-
-## `from url` — record API traffic
-
-Point mcpmake at a URL; it opens a browser, you click around, and on close it
-builds an MCP server from the captured API calls.
-
-```bash
-mcpmake from url https://app.example.com -o ./app-mcp
-```
-
-### Headless / CI capture
-
-When no human can drive a window (CI, containers), run headless and list the
-same-origin paths to auto-visit. mcpmake loads each, captures its traffic, and
-exits — no manual interaction:
-
-```bash
-mcpmake from url https://app.example.com -o ./app-mcp \
-  --headless --navigate /dashboard,/orders,/settings
-```
-
-- `--navigate` accepts absolute or relative URLs; **cross-origin targets are
-  skipped** (logged as a warning).
-- If nothing is captured, mcpmake tells you to add `--navigate` paths that
-  actually trigger API calls.
-
-`from url` also supports `-o/--output` (required), `-n/--name`, `--timeout`,
-`-t/--transport`, `--target` (`node`/`cloudflare`), `-i/--include`,
-`-e/--exclude`, `--improve-names`, `--interactive`, `-f/--force`, and
-`--dry-run` — see the [CLI reference](cli.md#mcpmake-from-url) for the full list.
-
----
-
-## `from website` — generate site-specific tools
-
-```bash
-mcpmake from website https://app.example.com -o ./site-mcp
-```
-
-Unlike generic browser MCP servers (Playwright MCP, Puppeteer MCP) that make the
-model rediscover the page on every call, this analyzes the DOM **once** and emits
-named tools — `login(email, password)`, `search(query)` — plus lifecycle tools
-(`start_browser`, `stop_browser`, `take_screenshot`).
-
-Useful flags:
-
-| Flag | Effect |
-| --- | --- |
-| `--depth`, `--max-pages` | crawl bounds (default depth 2, 20 pages) |
-| `--timeout <seconds>` | idle timeout during analysis (default 300) |
-| `--goal "..."` | LLM-driven navigation toward a goal instead of BFS (needs `ANTHROPIC_API_KEY`) |
-| `--hybrid` | HTTP fetch for API-backed forms, Playwright for HTML-only forms |
-| `--improve-names` | LLM-inferred semantic tool names (needs `ANTHROPIC_API_KEY`) |
-| `--headless` | run the analysis browser headless |
-| `--max-sessions <n>` | max concurrent browser sessions in the generated server (default 10) |
-| `-t, --transport` | `stdio` (default) or `http` |
-
-Plus the usual `-o/--output` (required), `-n/--name`, `-f/--force`, and
-`--dry-run`. The `website` pipeline is `--target node` only. See the
-[CLI reference](cli.md#mcpmake-from-website) for the complete list.
-
-### Resilient selectors at runtime
-
-Each generated tool stores a ranked **selector set** (data-testid > id >
-aria-label > name > CSS path > XPath), not just one selector. At runtime the
-tool tries the primary selector and then falls back through the rest, so a small
-DOM change doesn't immediately break the tool. This happens with no LLM and no
-network — pure Playwright in the generated server.
-
-### What gets written
-
-The generated project includes two files that make rescans possible:
-
-- `src/site-descriptor.json` — the snapshot of pages/forms/selectors captured at
-  generation time.
-- `mcpmake.site.json` — regeneration metadata (server name, transport, browser
-  config, env vars) so a rescan can rebuild without re-specifying CLI flags.
-
----
-
-## Keeping a website server fresh — `mcpmake rescan`
-
-Sites change. `rescan` is the website counterpart to `mcpmake update`: it
-re-crawls the live site, diffs it against the embedded snapshot, heals fragile
-selectors, and can regenerate the project in place.
-
-```bash
-# Report what changed and which selectors are fragile (no writes)
-mcpmake rescan ./site-mcp
-
-# Heal low-confidence selectors from the live 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 (CI)
-mcpmake rescan ./site-mcp --format json
-```
-
-### What it does
-
-1. Loads `src/site-descriptor.json` (old snapshot) and `mcpmake.site.json`
-   (regeneration settings).
-2. Re-crawls the site. Override the target with `--url`; crawl bounds default
-   from the snapshot (with headroom so newly added pages are still found) and
-   can be overridden with `--depth` / `--max-pages`.
-3. **Diffs** old vs new and reports added / removed / modified pages, forms,
-   fields, buttons, and links — plus any selectors that broke.
-4. **Self-heals:** for each fragile (low-confidence) selector it asks Claude for
-   a better selector based on the live accessibility tree, and applies it **only
-   if it actually resolves on the page**. Healing is skipped (with a warning) if
-   `ANTHROPIC_API_KEY` is unset; the diff/report still runs.
-5. With `--write`, regenerates the project from the healed snapshot. Like
-   `update`, this overwrites the generated files — commit first, then review the
-   diff.
-
-### Options
-
-```
-mcpmake rescan <project> [options]
-
-  --url <url>        Override the base URL to rescan (default: from the snapshot)
-  --depth <n>        Crawl depth (default: from the snapshot)
-  --max-pages <n>    Max pages to crawl (default: snapshot page count + headroom)
-  --no-heal          Disable LLM selector healing
-  --write            Regenerate the project in place from the new snapshot
-  --no-headless      Run the crawl/heal browser with a visible window
-  --format <fmt>     "text" (default) or "json"
-```
-
-### In CI
-
-Use the JSON output to gate on drift — e.g. fail a scheduled job when selectors
-break so you can rescan-and-commit deliberately:
-
-```bash
-mcpmake rescan ./site-mcp --format json > rescan.json
-# inspect .summary.brokenSelectors / .summary.totalChanges in your pipeline
-```
-
----
-
-## Security notes
-
-- Generated tool selectors, link hrefs, and field-name keys are derived from the
-  (untrusted) crawled page; mcpmake escapes them when emitting code so a crafted
-  page cannot inject code into the generated server.
-- LLM-healed selectors are validated and rejected if they contain characters
-  that could break out of a generated string literal.
-- The generated HTTP transport enforces an exact-host `ALLOWED_ORIGIN` check
-  (DNS-rebinding protection) in addition to the `MCP_AUTH_TOKEN` bearer check.

package/dist/emitter/code-writer.d.ts

@@ -1,8 +0,0 @@
-export interface CodeUnit {
-    filePath: string;
-    content: string;
-}
-export declare function writeCodeUnits(units: CodeUnit[], outputDir: string, options: {
-    force: boolean;
-    dryRun: boolean;
-}): Promise<void>;

package/dist/emitter/code-writer.js

@@ -1,25 +0,0 @@
-import { resolve } from 'node:path';
-import { writeFileSafe } from '../utils/fs.js';
-import { logger } from '../utils/logger.js';
-export async function writeCodeUnits(units, outputDir, options) {
-    const resolvedOutputDir = resolve(outputDir);
-    for (const unit of units) {
-        const absPath = resolve(outputDir, unit.filePath);
-        if (!absPath.startsWith(resolvedOutputDir + '/') && absPath !== resolvedOutputDir) {
-            throw new Error(`Path traversal detected: ${unit.filePath} resolves outside output directory`);
-        }
-        if (options.dryRun) {
-            logger.info(`[dry-run] Would write: ${unit.filePath}`);
-            continue;
-        }
-        const written = await writeFileSafe(absPath, unit.content, {
-            force: options.force,
-        });
-        if (written) {
-            logger.info(`  ${unit.filePath}`);
-        }
-        else {
-            logger.warn(`  Skipped (exists): ${unit.filePath}`);
-        }
-    }
-}

package/dist/emitter/index.d.ts

@@ -1,32 +0,0 @@
-import type { ProjectManifest } from '../types/index.js';
-import type { SiteProjectManifest } from '../types/site.js';
-export interface EmitOptions {
-    outputDir: string;
-    force: boolean;
-    dryRun: boolean;
-}
-export declare function emitProject(manifest: ProjectManifest, options: EmitOptions): Promise<void>;
-/**
- * Emit a Cloudflare Workers MCP server project (the `--target cloudflare` path).
- *
- * Workers is stateless and has no node:http server, so the SDK's
- * StreamableHTTPServerTransport cannot run there. The entry (`src/index.ts`) is a
- * hand-rolled JSON-RPC Fetch handler instead. The runtime-agnostic modules
- * (`http.ts`, `auth.ts`, `trace.ts`) are reused verbatim from the Node templates —
- * they only need `nodejs_compat`, which `wrangler.toml` enables.
- *
- * v1 scope is tools + initialize/ping/server-discover + bearer auth. Resources,
- * prompts, the Tasks extension and OAuth2 outbound auth are not emitted for this
- * target (a warning is logged and the user is pointed at `--target node`).
- */
-export declare function emitWorkerProject(manifest: ProjectManifest, options: EmitOptions): Promise<void>;
-/**
- * Emit a Playwright-based MCP server project from a SiteProjectManifest.
- * Parallel to emitProject() but uses site-specific templates.
- */
-export declare function emitSiteProject(manifest: SiteProjectManifest, options: EmitOptions): Promise<void>;
-/**
- * Emit a Python MCP server project.
- * Generates a single server.py file with all tools, plus requirements.txt.
- */
-export declare function emitPythonProject(manifest: ProjectManifest, options: EmitOptions): Promise<void>;