@lukoweb/apitogo 0.2.22 → 0.2.24

package/docs/mcp/setup.md

@@ -1,173 +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
+---
+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

@@ -1,77 +1,77 @@
----
-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 `npx apitogo run`.
-
-## 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 npx apitogo run
-```
-
-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 a local 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
-npx apitogo run
-```
-
-`create_dev_portal` does **not** start the preview server. Use `npx apitogo run` 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 only; `template`:
-  docs|guide|marketing)
-- 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).
+---
+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 `npx apitogo run`.
+
+## 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 npx apitogo run
+```
+
+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 a local 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
+npx apitogo run
+```
+
+`create_dev_portal` does **not** start the preview server. Use `npx apitogo run` 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 only; `template`:
+  docs|guide|marketing)
+- 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).