@lukoweb/apitogo 0.1.67 → 0.1.69

package/docs/mcp/go-live.md

@@ -0,0 +1,100 @@
+---
+title: Go live with MCP
+description:
+  Publish an APIToGo developer portal — platform plans, secrets, publish_dev_portal, and verify.
+sidebar_icon: rocket
+---
+
+**Go live** publishes your shaped portal to APItoGo hosting, optionally deploys the backend, upserts
+gateway plans, and verifies the live site.
+
+## Before you publish
+
+1. Confirm **gateway / API plans** in the manifest (or pass them in `apply_product_intent`). Do not
+   invent Free + Pro.
+2. Save secrets in the site **`.env`** (never in chat):
+
+   ```sh
+   APITOGO_CONFIG_AUTHENTICATION__OIDC__AUTHORITY=https://login.example.com
+   APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_ID=your-client-id
+   APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_SECRET=your-client-secret
+   # Only when you have paid project plans:
+   APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
+   APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
+   ```
+
+3. Choose a **platform hosting** plan: **Free**, **Starter**, or **Professional**. Agents should
+   call `list_platform_plans` / explain `freeProjectsQuota` before you pick. Starter and Professional
+   use Stripe checkout (`checkoutUrl`).
+
+## Happy path
+
+```text
+apply_product_intent({ mode: "goLive", siteDirectory, platformPlan?, ... })
+  → check_dev_portal_publish_readiness
+  → ensure_platform_plan (if needed)
+  → publish_dev_portal
+  → verify_dev_portal_live
+```
+
+If status is `blocked`, fix the readiness checklist (missing secrets, plan, OpenAPI). Do not invent
+credentials.
+
+After success, register **`manualSteps.oidcRedirectUri`** in your IdP. When `stripeRequired` is true,
+create a Stripe webhook at `manualSteps.stripeWebhookUrl` for the listed events.
+
+Do not treat warm-pool URLs as live until publish / deploy / verify succeed.
+
+## Granular go-live paths
+
+### Portal-first
+
+Docs and billing before the API backend:
+
+```text
+shape → publish_dev_portal → deploy_backend → sync_gateway_plans_from_manifest(syncActionsOnly: true)
+```
+
+### Full-stack
+
+Backend already healthy:
+
+```text
+shape → deploy_backend → publish_dev_portal(skipBackendRedeploy: true)
+```
+
+### CI one-shot
+
+`bootstrap_dev_portal` provisions and deploys in one call (advanced).
+
+## Platform plan vs API plans
+
+| Kind              | Meaning                                      | How                          |
+| ----------------- | -------------------------------------------- | ---------------------------- |
+| Platform hosting  | Free / Starter / Professional on APItoGo     | `ensure_platform_plan`       |
+| Gateway / API     | End-user SKUs and rate limits on `/pricing`  | Manifest / intent `plans`    |
+
+## Publish behavior
+
+- Unchanged healthy backend/site artifacts are reused unless you force redeploy.
+- `publish_dev_portal` upserts gateway plans from the manifest; do **not** call
+  `sync_gateway_plans_from_manifest` before publish.
+- After a post-publish `deploy_backend`, sync actions with
+  `sync_gateway_plans_from_manifest({ syncActionsOnly: true })`.
+- Resume from `.apitogo/publish-state.json` or `resumeFromStep` if a previous publish stopped early.
+
+## CLI deploy vs MCP publish
+
+| Path                         | Use when                                              |
+| ---------------------------- | ----------------------------------------------------- |
+| MCP `publish_dev_portal`     | Full product go-live (plans, auth, hosting, verify)   |
+| CLI `apitogo deploy`         | Build + deploy a site with a deployment token only    |
+
+See [Deploy with APIToGo CLI](../deploy/apitogo.md).
+
+## Related
+
+- [Shape](./shape.md)
+- [Tools](./tools.md)
+- [Authentication](../configuration/authentication.md)
+- [Manifest](../configuration/manifest.md)

package/docs/mcp/overview.md

@@ -0,0 +1,76 @@
+---
+title: MCP overview
+description:
+  Use the APItoGo MCP server to scaffold, shape, and publish API products from an AI agent.
+sidebar_icon: bot
+---
+
+The **APItoGo MCP** server lets AI agents manage projects, developer portals, gateway plans, backend
+deploy, and go-live. You can use MCP tools, edit site files yourself, or mix both.
+
+**First time?** Install and wire the server in your agent →
+**[Configure MCP in your agent](./setup.md)**. Then follow the [Quickstart](../quickstart.md).
+
+## What you get
+
+- Scaffold a local portal site (`create_dev_portal` / `apply_product_intent`)
+- Shape OpenAPI, plans, branding, theme, and docs pages
+- Publish to APItoGo hosting (`publish_dev_portal`) with platform plans **Free**, **Starter**, or
+  **Professional**
+- Deploy backends and sync gateway actions after publish
+
+Prefer **`apply_product_intent`** for “create / shape / go live” prompts. See [Shape](./shape.md) and
+[Go live](./go-live.md).
+
+## Prerequisites
+
+### MCP host environment
+
+| Variable                | Required | Purpose           |
+| ----------------------- | -------- | ----------------- |
+| `APITOGO_API_KEY_ID`    | Yes      | Platform API auth |
+| `APITOGO_API_SECRET`    | Yes      | Platform API auth |
+
+### Agent host
+
+- Node.js 20+ (scaffold, build, preview)
+- Network access to the npm registry during install/build
+- OIDC credentials at publish time (site `.env` only — never in chat)
+- Stripe secrets at publish only when you have **paid** project plans
+
+## Changing your site
+
+You choose how to edit the portal:
+
+| Approach | When it helps |
+| -------- | ------------- |
+| **MCP tools** | Agent-driven changes; tools can wire navigation/config and run validation. See [Tools](./tools.md). |
+| **Edit files directly** | Full control in your editor — `apitogo.config.json`, `pages/**`, `landing/LandingPage.tsx`, etc. |
+
+Useful MCP tools (optional — not required):
+
+| Change                              | Tool                                             |
+| ----------------------------------- | ------------------------------------------------ |
+| Add / edit a docs page              | `add_dev_portal_page` / `update_dev_portal_page` |
+| OpenAPI                             | `set_dev_portal_openapi`                         |
+| Plans, branding, backend, projectId | `update_dev_portal_manifest`                     |
+| Theme                               | `set_dev_portal_theme`                           |
+
+Home page content often lives in `landing/LandingPage.tsx`. Site footer can live under
+`modules.landing.content.footer` in `apitogo.config.json`.
+
+## Config model (local site)
+
+| File                  | Role                                  |
+| --------------------- | ------------------------------------- |
+| `apitogo.config.json` | Site, modules, plans, auth type, apis |
+| `.env`                | `VITE_*` + `APITOGO_CONFIG_*` secrets |
+
+Details: [Manifest](../configuration/manifest.md).
+
+## Next
+
+- [Configure MCP](./setup.md)
+- [Quickstart](../quickstart.md)
+- [Shape](./shape.md) · [Go live](./go-live.md) · [Tools](./tools.md)
+- CLI without an agent: see the footnote on [Quickstart](../quickstart.md#without-an-agent-cli)

package/docs/mcp/setup.md

@@ -0,0 +1,173 @@
+---
+title: Configure MCP in your agent
+description:
+  Install and wire the APItoGo MCP server in Cursor, Claude Desktop, Claude Code, Codex, and other
+  MCP hosts.
+sidebar_icon: plug
+---
+
+Connect **`@lukoweb/apitogo-mcp`** to your AI agent so it can shape and publish API products. The
+server is the same everywhere; only the host config file changes.
+
+## Prerequisites
+
+- **Node.js 20+** on the machine that runs the agent (scaffold, build, preview)
+- Platform API credentials from [apitogo.com](https://apitogo.com) (API key id + secret)
+
+## Shared server definition
+
+Every host launches the same stdio process:
+
+| Field     | Value                                      |
+| --------- | ------------------------------------------ |
+| Command   | `npx`                                      |
+| Args      | `-y`, `@lukoweb/apitogo-mcp`               |
+| Env       | `APITOGO_API_KEY_ID`, `APITOGO_API_SECRET` |
+
+Optional env: `APITOGO_API_URL`, `APITOGO_DOC_TOOL_PATH` (local doc-tool for scaffold).
+
+Never commit secrets. Prefer host env blocks or `${VAR}` expansion where the client supports it.
+
+## Cursor
+
+Add to `~/.cursor/mcp.json` (user) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "apitogo": {
+      "command": "npx",
+      "args": ["-y", "@lukoweb/apitogo-mcp"],
+      "env": {
+        "APITOGO_API_KEY_ID": "apk_...",
+        "APITOGO_API_SECRET": "..."
+      }
+    }
+  }
+}
+```
+
+Restart Cursor (or reload MCP). Confirm the **apitogo** server is connected in MCP settings.
+
+### Optional: `apitogo-product` skill
+
+So agents prefer `apply_product_intent` for create / go-live:
+
+```bash
+# From the apitogo-local-mcp repo (or after npm pack of the package that ships skills/)
+mkdir -p ~/.cursor/skills
+cp -R skills/apitogo-product ~/.cursor/skills/apitogo-product
+```
+
+Or project-scoped under `.cursor/skills/apitogo-product`.
+
+## Claude Desktop
+
+Edit the Claude Desktop MCP config (same `mcpServers` shape as Cursor):
+
+| OS      | Path                                                                      |
+| ------- | ------------------------------------------------------------------------- |
+| macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json`         |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json`                             |
+
+```json
+{
+  "mcpServers": {
+    "apitogo": {
+      "command": "npx",
+      "args": ["-y", "@lukoweb/apitogo-mcp"],
+      "env": {
+        "APITOGO_API_KEY_ID": "apk_...",
+        "APITOGO_API_SECRET": "..."
+      }
+    }
+  }
+}
+```
+
+Fully quit and reopen Claude Desktop after saving.
+
+## Claude Code
+
+**CLI (user scope — all projects):**
+
+```bash
+claude mcp add --scope user --env APITOGO_API_KEY_ID=apk_... --env APITOGO_API_SECRET=... \
+  apitogo -- npx -y @lukoweb/apitogo-mcp
+```
+
+**Project scope** (committed `.mcp.json` — use `${VAR}` for secrets):
+
+```bash
+claude mcp add --scope project --env APITOGO_API_KEY_ID=${APITOGO_API_KEY_ID} \
+  --env APITOGO_API_SECRET=${APITOGO_API_SECRET} \
+  apitogo -- npx -y @lukoweb/apitogo-mcp
+```
+
+Or hand-edit `.mcp.json` in the project root:
+
+```json
+{
+  "mcpServers": {
+    "apitogo": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@lukoweb/apitogo-mcp"],
+      "env": {
+        "APITOGO_API_KEY_ID": "${APITOGO_API_KEY_ID}",
+        "APITOGO_API_SECRET": "${APITOGO_API_SECRET}"
+      }
+    }
+  }
+}
+```
+
+User/local scope without a project file lives in `~/.claude.json`. Start a new Claude Code session
+after changing config. Approve project-scoped servers when prompted.
+
+## OpenAI Codex
+
+Edit `~/.codex/config.toml` (or project `.codex/config.toml` in a trusted project). The key must be
+`mcp_servers` (not `mcpServers`):
+
+```toml
+[mcp_servers.apitogo]
+command = "npx"
+args = ["-y", "@lukoweb/apitogo-mcp"]
+
+[mcp_servers.apitogo.env]
+APITOGO_API_KEY_ID = "apk_..."
+APITOGO_API_SECRET = "..."
+```
+
+You can also use `codex mcp add` if your Codex version supports it, then confirm the TOML entry.
+Restart Codex / open a new session. See [Codex MCP docs](https://developers.openai.com/codex/mcp).
+
+## Other MCP hosts
+
+Any client that supports **stdio** MCP can run APItoGo:
+
+1. Set command `npx`, args `["-y", "@lukoweb/apitogo-mcp"]`
+2. Pass `APITOGO_API_KEY_ID` and `APITOGO_API_SECRET` in the server env
+3. Restart the host and confirm tools load
+
+Examples: Windsurf, VS Code Copilot Chat MCP, custom MCP clients — follow that product’s “add stdio
+server” UI and paste the same command/args/env.
+
+## Verify
+
+In a new agent chat:
+
+1. Ask the agent to list APItoGo tools, or call **`whoami`**.
+2. You should see platform tools such as `apply_product_intent`, `create_dev_portal`,
+   `publish_dev_portal`.
+
+If the server fails to start: confirm Node 20+, that `npx -y @lukoweb/apitogo-mcp` works in a
+terminal, and that the API key id/secret are correct.
+
+## Next
+
+- [Quickstart](../quickstart.md) — first shape prompt
+- [Shape](./shape.md) — local portal iteration
+- [Go live](./go-live.md) — publish
+- [Tools](./tools.md) — catalog

package/docs/mcp/shape.md

@@ -0,0 +1,76 @@
+---
+title: Shape with MCP
+description:
+  Scaffold and customize a developer portal locally with apply_product_intent (mode shape).
+sidebar_icon: pencil-ruler
+---
+
+**Shape** means: create or update a local portal site (OpenAPI, plans, auth flags, public routes)
+without publishing. You preview with `npm run dev`.
+
+## Happy path
+
+```text
+apply_product_intent({ mode: "shape", siteDirectory, backend?, openApi?, plans?, auth?, gatewayPolicies?, branding? })
+  → scaffold if needed
+  → wire OpenAPI / plans / auth / gateway.publicRoutes
+  → you run npm run dev
+```
+
+Example prompt:
+
+> Create a portal in `./dev-portal` for my API in `./api` with Free (100/min) and Pro (1000/min);
+> make `/health` public.
+
+Never invent Free + Pro gateway plans unless you ask for them. Never put OIDC or Stripe secrets in
+chat.
+
+## Scaffold only
+
+If you only want an empty site:
+
+> Create a dev portal in `./dev-portal-site`.
+
+The agent should call **`create_dev_portal`** (or `apply_product_intent` with shape when you also
+pass plans/backend). Then run:
+
+```bash
+cd ./dev-portal-site
+npm run dev
+```
+
+`create_dev_portal` does **not** start the preview server. Use `npm run dev` or
+`preview_dev_portal_site`.
+
+Optional: `bootstrapProject: true` on create (or `bootstrap_project`) to create the platform project
+without selecting a hosting plan yet.
+
+## What to collect
+
+Ask only for what is missing:
+
+1. **siteDirectory** — where to scaffold (e.g. `./dev-portal`)
+2. **backend** / **openApi** — source directory and/or OpenAPI path or URL
+3. **plans** — SKUs, prices, rate limits (your choice; not invented)
+4. **auth.mode** — `native` | `oidc` | `nativeAndOidc`
+5. **gatewayPolicies.publicRoutes** — e.g. `/health` (other routes stay subscription-key protected by
+   default)
+
+## Customize after shape
+
+Use MCP tools (see [Tools](./tools.md)):
+
+- Pages → `add_dev_portal_page` / `update_dev_portal_page` (TSX under Documentation nav by default)
+- OpenAPI → `set_dev_portal_openapi`
+- Plans / branding → `update_dev_portal_manifest`
+- Theme → `set_dev_portal_theme`
+
+Home page content: hand-edit `landing/LandingPage.tsx` after asking for real copy. Footer:
+`modules.landing.content.footer` in `apitogo.config.json`.
+
+Shape-phase edits hot-reload when the local preview is running. Pass `restartPreview: true` on
+manifest updates only when you need mock pricing refreshed.
+
+## Next
+
+When the site looks right, [go live](./go-live.md).

package/docs/mcp/tools.md

@@ -0,0 +1,102 @@
+---
+title: MCP tools
+description: APItoGo MCP tool catalog by category and hand-edit exceptions.
+sidebar_icon: wrench
+---
+
+Tools are exposed by the APItoGo MCP server. Prefer **`apply_product_intent`** for create / shape /
+go-live. Use granular tools for advanced edits, debugging, or CI.
+
+## Lifecycle (prefer these)
+
+| Tool                         | Role                                                |
+| ---------------------------- | --------------------------------------------------- |
+| `apply_product_intent`       | Shape or goLive from a product intent               |
+| `create_dev_portal`          | Scaffold site (+ optional project bootstrap)        |
+| `check_dev_portal_publish_readiness` | Pre-publish checklist                      |
+| `publish_dev_portal`         | Publish portal + plans (+ optional backend)         |
+| `verify_dev_portal_live`     | Post-publish verification                           |
+| `bootstrap_dev_portal`       | CI one-shot provision + deploy                      |
+| `bootstrap_project`          | Create platform project only (plan unselected)      |
+| `teardown_project`           | Tear down a project                                 |
+
+## Site shaping
+
+| Tool                              | Role                                      |
+| --------------------------------- | ----------------------------------------- |
+| `update_dev_portal_manifest`      | Plans, branding, backend, projectId       |
+| `set_dev_portal_openapi`          | OpenAPI / API reference                   |
+| `set_dev_portal_theme`            | Colors and fonts                          |
+| `add_dev_portal_page`             | Add a docs page (TSX under Documentation nav) |
+| `update_dev_portal_page`          | Edit a docs page                          |
+| `scaffold_dev_portal_landing_page`| Scaffold missing landing file             |
+| `get_dev_portal_landing_guide`    | Landing component catalog                 |
+| `preview_dev_portal_site`         | Start / restart local preview             |
+| `build_dev_portal_site`           | Production build                          |
+
+Hosted page CRUD also exists (`list/create/delete/rename/reorder_dev_portal_pages`) for the platform
+API surface.
+
+## Projects and platform billing
+
+| Tool                         | Role                                      |
+| ---------------------------- | ----------------------------------------- |
+| `whoami`, `list_projects`, `get_project`, … | Tenant / project CRUD          |
+| `list_platform_plans`        | Free / Starter / Professional + quota     |
+| `ensure_platform_plan`       | Select or checkout platform plan          |
+| `wait_for_platform_plan`     | Poll until active                         |
+| `get_subscription`           | Current subscription                      |
+| `select_free_plan`           | Free hosting                              |
+| `create_checkout_session`    | Stripe checkout for paid hosting          |
+
+## Backend and OpenAPI
+
+| Tool                    | Role                            |
+| ----------------------- | ------------------------------- |
+| `validate_openapi`      | Validate OpenAPI                |
+| `update_openapi`        | Update stored OpenAPI           |
+| `package_backend`       | Package backend artifact        |
+| `deploy_backend`        | Deploy API hub                  |
+| `get_backend_summary`   | Backend status                  |
+| `get_deployment_status` | Deployment job status           |
+| `get_gateway_readiness` | Gateway readiness               |
+
+## Gateway
+
+| Tool                                   | Role                          |
+| -------------------------------------- | ----------------------------- |
+| `list/get/create/update/patch_gateway_plan` | Plan CRUD                |
+| `add_actions_to_gateway_plan` / `remove_actions_from_gateway_plan` | Attach ops |
+| `set_action_public`                    | Public routes                 |
+| `upsert_entitlement`                   | Entitlements                  |
+| `configure_gateway_baseline`           | Baseline policies             |
+| `get/update_gateway_settings`          | Settings                      |
+| `get/update_gateway_auth`              | Gateway auth                  |
+| `sync_gateway_plans_from_manifest`     | Post-publish action sync      |
+| `reorder_gateway_plans_from_manifest`  | Plan order                    |
+
+## Infrastructure and deploy
+
+| Tool                              | Role                         |
+| --------------------------------- | ---------------------------- |
+| `activate_module`                 | Activate modules             |
+| `get_infrastructure_status` / Azure variants | Infra status      |
+| `list_provisioning_jobs`, `wait_for_job` | Jobs                  |
+| `get_deployment_token`            | CLI deploy token             |
+| `get/set/delete_custom_domain`    | Custom domain                |
+| `get_dev_portal_deploy_config`, `deploy_dev_portal`, … | SWA deploy     |
+
+## Hand-edit exceptions
+
+| Change            | Where                                              |
+| ----------------- | -------------------------------------------------- |
+| Home page content | `landing/LandingPage.tsx`                          |
+| Site footer       | `apitogo.config.json` → `modules.landing.content.footer` |
+
+There is **no** `update_dev_portal_landing` tool for arbitrary home content.
+
+## Related
+
+- [Overview](./overview.md)
+- [Shape](./shape.md)
+- [Go live](./go-live.md)

package/docs/plugins.md

@@ -2,4 +2,23 @@
 title: APIToGo Plugins
 ---
 
-APIToGo can be extended using plugins.
+APIToGo is extended with **plugins** registered in your site config. JSON cannot
+hold React or functions.
+
+Common uses:
+
+- Search (Pagefind built-in; Algolia / Inkeep plugins) — [Search](./configuration/search.md)
+- Billing UI — `@lukoweb/apitogo-plugin-dev-portal-billing` with `buildApitogoConfig`
+- Custom behavior — [Custom plugins](./custom-plugins.md)
+- Config transforms — `transformConfig` on a plugin (slots, syntax highlighting, etc.)
+
+```tsx title=config
+import { buildApitogoConfig } from "@lukoweb/apitogo";
+import { devPortalBillingPlugin } from "@lukoweb/apitogo-plugin-dev-portal-billing";
+
+export default buildApitogoConfig({
+  plugins: [devPortalBillingPlugin()],
+});
+```
+
+See also [Extending / events](./extending/events.md) and [Slots](./configuration/slots.mdx).