@lukoweb/apitogo 0.2.57 → 0.2.59

package/docs/mcp/setup.md

@@ -1,173 +1,169 @@
----
-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 create, shape and deploy APItoGo
+projects. The server is the same everywhere; only the host config file changes.
+
+## Prerequisites
+
+- **Node.js 20+** on the machine that runs the agent
+- Signed in to APItoGo: run `npx @lukoweb/apitogo login` once in a terminal. Or give the server API
+  credentials (API key id and secret from [apitogo.com](https://apitogo.com)) in its env.
+
+## Shared server definition
+
+Every host launches the same stdio process:
+
+| Field   | Value                                                |
+| ------- | ---------------------------------------------------- |
+| Command | `npx`                                                |
+| Args    | `-y`, `@lukoweb/apitogo-mcp`                         |
+| Env     | Optional: `APITOGO_API_KEY_ID`, `APITOGO_API_SECRET` |
+
+The tools run the `apitogo` CLI the project installed (`node_modules/@lukoweb/apitogo`), or the
+latest one through npx in a folder without it. Optional env: `APITOGO_API_KEY_ID` and
+`APITOGO_API_SECRET` instead of `apitogo login`, `APITOGO_API_URL`, and `APITOGO_CLI_PATH` (a local
+doc-tool checkout, for CLI development).
+
+The server runs the commands in the folder your host starts it in, unless a tool gets a `directory`.
+Start it in your workspace, or tell the agent where the project is.
+
+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.
+
+## 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. Sign in with `npx @lukoweb/apitogo login`, or 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 the APItoGo tools: they all start with `apitogo_`, such as
+   `apitogo_create`, `apitogo_deploy` and `apitogo_status`.
+2. Ask it for the status of your project; it calls `apitogo_status`.
+
+If the server fails to start: confirm Node 20+ and that `npx -y @lukoweb/apitogo-mcp` works in a
+terminal. If a tool says you are not logged in, run `npx @lukoweb/apitogo login` or check the API
+key id and secret.
+
+## Next
+
+- [Shape a project](./shape.md) — make and change the project folder
+- [Go live](./go-live.md) — deploy
+- [Tools](./tools.md) — every tool

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 a project with MCP
+description:
+  Create an APItoGo project folder and shape its portal, API and plans with the MCP tools, before
+  anything is deployed.
+sidebar_icon: pencil-ruler
+---
+
+**Shaping** is everything before a deploy: making the project folder, choosing the services, and
+setting the portal's name, the API, the docs pages and the plans. It only changes files in the
+folder; nothing reaches the platform yet.
+
+## Start a project
+
+A new project with every service and a sample backend, ready to deploy:
+
+> Create an APItoGo project called Books in `./books`.
+
+The agent calls **`apitogo_create`** with `template: "full"`. For empty services it uses
+`template: "blank"`, and `services` picks only some of them:
+
+| Service    | What it is                                               |
+| ---------- | -------------------------------------------------------- |
+| `portal`   | The developer website: landing page, docs, API reference |
+| `gateway`  | API protection: keys, rate limits, quotas                |
+| `identity` | Login for the people who use your API                    |
+| `plans`    | Pricing and API keys                                     |
+
+**An existing API repository?** The agent calls **`apitogo_init`** in that folder, then
+**`apitogo_add`** for each service, for example a gateway in front of an API that already runs:
+
+```json
+{
+  "service": "gateway",
+  "options": { "origin": "proxy", "url": "https://api.example.com", "spec": ["openapi.yaml"] }
+}
+```
+
+## Change it
+
+**`apitogo_config`** makes the common changes, with the flags of
+[`apitogo config`](../configuration/make-config.mdx):
+
+| Change                      | Options                                                     |
+| --------------------------- | ----------------------------------------------------------- |
+| Portal name                 | `title`                                                     |
+| Add an OpenAPI file         | `openapi`                                                   |
+| A docs page                 | `pageSlug`, `pageTitle`, `pageContent` (markdown)           |
+| A plan                      | `planSku`, `planName`, `planPrice`, `planRate`, `planQuota` |
+| A contact-us plan           | `planSku`, `planPrice: "custom"`                            |
+| Take a plan out             | `removePlan`                                                |
+| Anything else in the config | `patch` (an object merged into `apitogo.config.json`)       |
+
+Example prompt:
+
+> Add a Team plan at 49 USD a month with 120 calls a minute and 200,000 calls a month.
+
+The agent sends
+`{"planSku":"team","planName":"Team","planPrice":"49","planRate":"120/60","planQuota":"200000/30"}`.
+
+The landing page (`apitogo/portal/landing/LandingPage.tsx`), the footer, the theme and the pages are
+your project's files: the agent edits them directly, like any code.
+
+Selling paid plans needs a **Starter** or **Professional** project and your Stripe keys, which you
+set yourself; see [Plans](../configuration/plans.md) and the
+[Stripe guide](../guides/stripe-setup.mdx).
+
+## Check and look
+
+- **`apitogo_check`** finds mistakes in the config and its files before a deploy. With `offline` it
+  asks the platform nothing.
+- To see the portal locally, run `npx apitogo run` in the folder yourself; it keeps running, so it
+  is not an MCP tool.
+
+## Next
+
+When it looks right, [go live](./go-live.md).