@cloudgrid-io/mcp 0.4.7 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.4.7",
-  "description": "MCP server for CloudGrid. Two editions: a local stdio server (full toolset) and a hosted web server (light, CLI-free toolset) over MCP Streamable HTTP.",
+  "version": "0.5.0",
+  "description": "MCP server for CloudGrid. Three editions: a local stdio server (full toolset), a hosted web server (light, CLI-free toolset), and a public docs server (search_cloudgrid_documentation) over MCP Streamable HTTP.",
   "type": "module",
   "bin": {
     "cloudgrid-mcp": "src/index.js"
@@ -23,6 +23,9 @@
     "smoke:redrop": "node test/smoke-redrop.mjs",
     "smoke:oauth": "node test/smoke-oauth.mjs",
     "test:auth": "node test/auth.test.mjs",
+    "smoke:docs": "node test/smoke-docs.mjs",
+    "start:docs": "node src/docs.js",
+    "snapshot:corpus": "node scripts/snapshot-corpus.mjs",
     "build:mcpb": "node scripts/build-mcpb.mjs"
   },
   "dependencies": {

package/src/corpus/cli-reference.md

@@ -0,0 +1,148 @@
+# CloudGrid CLI
+
+[![release](https://img.shields.io/badge/release-v0.9.13-black)](https://github.com/cloudgrid-io/cli/releases)
+[![npm](https://img.shields.io/badge/npm-v0.9.13-cb3837)](https://www.npmjs.com/package/@cloudgrid-io/cli)
+[![license](https://img.shields.io/badge/license-Apache--2.0-green)](./LICENSE)
+
+> Draft for the public `cloudgrid-io/cli` distribution repo. Structure mirrors
+> `higgsfield-ai/cli`, fit to CloudGrid. Source stays private in the monorepo; this
+> repo holds the installer + docs only.
+
+Build, ship, and run apps and agents on CloudGrid from your terminal. A directory or a
+URL becomes a live, addressable thing in about 30 seconds — deploy, tail logs, share,
+read feedback, all without leaving your shell.
+
+## Contents
+
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Examples](#examples)
+- [Commands](#commands)
+- [Flags](#flags)
+- [Updating](#updating)
+- [Uninstall](#uninstall)
+- [Troubleshooting](#troubleshooting)
+- [Support](#support)
+- [License](#license)
+
+## Install
+
+**macOS / Linux — curl**
+```
+curl -fsSL https://raw.githubusercontent.com/cloudgrid-io/cli/main/install.sh | sh
+```
+
+**macOS / Linux — Homebrew**
+```
+brew install cloudgrid-io/tap/cloudgrid
+```
+
+**Cross-platform (incl. Windows) — npm**
+```
+npm install -g @cloudgrid-io/cli
+```
+
+**Manual** — download the latest from [Releases](https://github.com/cloudgrid-io/cli/releases), extract, and put `cloudgrid` on your `$PATH`.
+
+Verify: `cloudgrid --version` and `cloudgrid doctor`. The shorthand `cg` works for every command.
+
+## Quickstart
+
+```
+cloudgrid login          # Google OAuth in the browser
+cloudgrid whoami         # confirm user + active org
+cloudgrid plug           # build + deploy the current directory, prints the live URL
+cloudgrid open           # open it in the browser
+```
+
+No account needed to try a one-off share: `cloudgrid plug ./index.html` drops a public link.
+
+## Examples
+
+```
+# Scaffold and deploy a Node app
+cloudgrid init app my-api --type node
+cd my-api && cloudgrid plug
+
+# Deploy the current directory and tail its logs
+cloudgrid plug
+cloudgrid logs --since 10m
+
+# Make a deploy public, then read feedback
+cloudgrid visibility set my-api link
+cloudgrid feedback
+
+# Switch org, list what's on the grid
+cloudgrid use atomic
+cloudgrid grid
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `login` / `logout` / `whoami` | Sign in (Google OAuth), sign out, show user + active org |
+| `use [slug]` | Set or show the active org |
+| `init <kind> <name>` | Register a new app or agent |
+| `plug [target]` | Build + deploy (or redeploy); prints the live URL |
+| `dev` | Run the linked entity locally with grid-injected resources |
+| `status [name]` | Org dashboard, entity detail, or a deploy snapshot |
+| `logs [name]` | Stream entity logs |
+| `open [name]` | Open the entity URL in the browser |
+| `info [name]` / `builds [name]` | Entity metadata; recent deploys |
+| `visibility set <slug> <mode>` | private \| authenticated \| org \| link |
+| `rollback` / `versions` | Roll back to a prior deploy; list/tag minted versions |
+| `env` / `secrets` | Manage runtime env vars and secrets (secret values are never printed) |
+| `grid` / `list` | List what's on your hub / org |
+| `rename` / `delete` / `unplug` | Rename, archive, take off the grid |
+| `pull` / `clone` / `fork` | Download source; clone or fork an entity |
+| `feedback [message]` | Send feedback to the CloudGrid team |
+| `brain refresh <name>` | Re-run Grid Brain metadata (description, tags, diagram) |
+| `doctor` | Diagnostic checks (Node, Docker, API reachability, auth) |
+| `completion <shell>` | Shell completion script |
+
+Run `cloudgrid <command> --help` for the full flag set of any command.
+
+## Flags
+
+Global:
+- `-V, --version` — print the CLI version
+- `-v, --verbose` — detailed output
+- `-h, --help` — help for any command
+
+Common per-command:
+- `--org <slug>` — pick/override the org
+- `--json` — machine-readable output (where supported)
+- `--no-clipboard` / `--no-notify` — suppress clipboard copy / OS notification on `plug`
+- `--since <dur>` / `--tail <n>` — `logs` window
+
+## Updating
+
+```
+npm update -g @cloudgrid-io/cli      # npm
+brew upgrade cloudgrid               # homebrew
+```
+`cloudgrid doctor` warns when a newer version is available.
+
+## Uninstall
+
+```
+npm uninstall -g @cloudgrid-io/cli   # npm
+brew uninstall cloudgrid             # homebrew
+rm -rf ~/.cloudgrid                  # remove stored credentials + config
+```
+
+## Troubleshooting
+
+- **`cloudgrid: command not found`** — ensure the npm global bin (or Homebrew bin) is on `$PATH`; re-run the installer.
+- **Auth errors / 401** — `cloudgrid login` again; check `cloudgrid whoami` shows the expected org, switch with `cloudgrid use <org>`.
+- **Deploy fails** — run `cloudgrid doctor`; check `cloudgrid logs` and `cloudgrid status <name>` for the trace.
+
+## Support
+
+- Skills + MCP: [cloudgrid-io/skills](https://github.com/cloudgrid-io/skills)
+- Issues: [cloudgrid-io/cli/issues](https://github.com/cloudgrid-io/cli/issues)
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/src/corpus/cookbook.md

@@ -0,0 +1,89 @@
+# Cookbook
+
+Canonical chains you can run end to end. Each step is one skill. Together they are
+the "I built a thing and shipped it" loop.
+
+## Prerequisite
+
+The CLI is installed and you are logged in:
+
+```
+npm install -g @cloudgrid-io/cli
+cloudgrid login
+```
+
+## The build-and-ship loop
+
+```
+init  ->  plug  ->  logs  ->  share  ->  feedback
+```
+
+### 1. Scaffold
+
+Register a new app and seed a static web service:
+
+```
+cloudgrid init app my-thing --type static
+```
+
+`--type` accepts `node`, `nextjs`, `python`, or `static`. For an agent, use
+`cloudgrid init agent my-thing`.
+
+### 2. Deploy
+
+From the project directory, deploy it:
+
+```
+cloudgrid plug
+```
+
+`cloudgrid plug` also takes a path or a URL. It builds and deploys, then prints the
+live URL. This usually takes about 30 seconds.
+
+### 3. Watch the logs
+
+```
+cloudgrid logs my-thing --follow
+```
+
+Drop `--follow` for a one-time tail. `--since 5m` limits how far back to read.
+
+### 4. Share
+
+Make the entity reachable by anyone with the link. The command prints the URL:
+
+```
+cloudgrid visibility set my-thing link
+```
+
+### 5. Read feedback
+
+```
+cloudgrid feedback list
+```
+
+## Share an artifact with no account
+
+The fastest chain has one step and no login. Drop an HTML file, get a public URL:
+
+```
+curl -sS -X POST https://api.cloudgrid.io/api/v2/drop/auto \
+  -F "artifact=@./index.html;type=text/html"
+```
+
+The response includes `url` (the live link) and `claim_url` (sign in within 7 days
+to keep it). This is what the `cloudgrid-drop` skill and the `cloudgrid_drop` MCP
+tool do for you. It is anonymous and serves inspirations only; a full app needs the
+signed-in `plug` flow above.
+
+## Shorter chains
+
+- **Ship an existing directory:** `plug`
+- **Deploy a URL as an inspiration:** `plug https://example.com`
+- **Refresh discovery metadata after a change:** `cloudgrid brain refresh my-thing --wait`
+
+## Notes
+
+- Every command uses the active org and linked entity when you omit the name. Run
+  `cloudgrid whoami` to see the active context.
+- These skills wrap the CLI. Anything the CLI can do, a skill can drive.

package/src/corpus/install-for-agents.md

@@ -0,0 +1,63 @@
+# Install (for agents)
+
+You are an agent. These are steps to execute, not prose to summarize. Run them in
+order. Stop and ask the user only where a step says to.
+
+## 1. Ensure the CLI is present
+
+Check whether `cloudgrid` is on `$PATH`:
+
+```
+cloudgrid --version
+```
+
+If that fails, install it:
+
+```
+npm install -g @cloudgrid-io/cli
+```
+
+## 2. Ensure the user is logged in
+
+```
+cloudgrid whoami
+```
+
+If that fails, tell the user to run `cloudgrid login` and wait for them to confirm.
+Do not attempt to log in for them. Do not invent an auth flow.
+
+## 3. Confirm the skills are available
+
+The skills live in this repo, one directory per skill, each with a `SKILL.md`.
+Load the `SKILL.md` for the action the user wants:
+
+- `skills/drop/SKILL.md` — share an artifact, get a URL (no login needed)
+- `skills/login/SKILL.md` — sign in, with or without the CLI
+- `skills/claim/SKILL.md` — claim an anonymous drop into the account
+- `skills/init/SKILL.md` — scaffold a new app or agent
+- `skills/plug/SKILL.md` — deploy a directory or URL
+- `skills/logs/SKILL.md` — tail logs
+- `skills/share/SKILL.md` — make an entity shareable
+- `skills/feedback/SKILL.md` — read the feedback feed
+- `skills/brain/SKILL.md` — refresh Grid Brain metadata
+
+## 4. Follow the skill
+
+Each `SKILL.md` carries its own steps. Follow them exactly. The common rules:
+
+- Wrap only the `cloudgrid` CLI. Do not call the API directly.
+- Detect the user's language from their first message and reply in it. Keep
+  technical flags in English.
+- Print results concisely: URLs and short summaries. Never dump raw JSON or IDs.
+- Pick sane defaults. Ask one thing at a time, only when something is genuinely
+  missing.
+
+## 5. The canonical chain
+
+For a full build-and-ship loop, run the skills in this order:
+
+```
+init -> plug -> logs -> share -> feedback
+```
+
+See `COOKBOOK.md` for the worked example.

package/src/corpus/install.md

@@ -0,0 +1,117 @@
+# Install
+
+CloudGrid Skills work in any agent that reads `SKILL.md` files. The steps below
+cover the CLI prerequisite, then each agent.
+
+## Prerequisite: the CloudGrid CLI
+
+Every skill drives the `cloudgrid` CLI. Install it once and log in:
+
+```
+npm install -g @cloudgrid-io/cli
+cloudgrid login
+```
+
+`cloudgrid whoami` confirms you are logged in.
+
+## Add the skills
+
+Pick the method that matches your agent.
+
+### Any agent (gh skill extension)
+
+```
+gh skill install cloudgrid-io/skills
+```
+
+### Any agent (skills CLI)
+
+```
+npx skills add cloudgrid-io/skills
+```
+
+### Claude Code
+
+```
+/plugin marketplace add cloudgrid-io/skills
+```
+
+The marketplace manifest lives in `.claude-plugin/`.
+
+### Codex
+
+Three routes:
+
+```
+codex plugin marketplace add cloudgrid-io/skills      # plugin (manifest: .codex-plugin/)
+npx skills add cloudgrid-io/skills -a codex           # skills only (-> ~/.agents/skills)
+```
+
+Or the MCP server, in `~/.codex/config.toml` — local or the hosted URL:
+
+```toml
+[mcp_servers.cloudgrid]
+command = "npx"
+args = ["-y", "@cloudgrid-io/mcp"]
+
+# or remote, nothing installed:
+# [mcp_servers.cloudgrid]
+# url = "https://mcp.cloudgrid.io/mcp"
+```
+
+### Cursor
+
+Cursor reads Agent Skills natively (v2.4+):
+
+```
+npx skills add cloudgrid-io/skills -a cursor          # -> ~/.cursor/skills + ~/.agents/skills
+```
+
+Or install the plugin from Cursor's in-app marketplace (manifest: `.cursor-plugin/`).
+Or the MCP server, in `~/.cursor/mcp.json`:
+
+```json
+{ "mcpServers": { "cloudgrid": { "command": "npx", "args": ["-y", "@cloudgrid-io/mcp"] } } }
+```
+
+Remote variant, nothing installed: `{ "mcpServers": { "cloudgrid": { "url": "https://mcp.cloudgrid.io/mcp" } } }`
+
+### Manual
+
+```
+git clone https://github.com/cloudgrid-io/skills.git
+```
+
+Then point your agent at the cloned directory.
+
+## MCP server
+
+The `@cloudgrid-io/mcp` package is published on npm:
+
+```
+npx -y @cloudgrid-io/mcp
+```
+
+It wraps the same `cloudgrid` CLI and uses the same credentials, so no extra login
+is needed. Remote-capable clients can point at `https://mcp.cloudgrid.io/mcp`
+instead. See [USAGE.md](USAGE.md) for per-client snippets.
+
+### Claude Desktop — one-click install
+
+Claude Desktop users can install the MCP as a Desktop Extension with no terminal,
+no Node, and no JSON editing. Download the bundle and double-click it (or in Claude
+Desktop: Settings, Extensions, Install from file):
+
+```
+https://github.com/cloudgrid-io/mcp/releases/latest/download/cloudgrid.mcpb
+```
+
+The bundle carries the full local toolset (including the `cloudgrid` CLI), so deploy
+and secrets tools work without a separate install. Sign in from chat with the
+`cloudgrid_login` tool on first use.
+
+## For agents
+
+If you are an agent reading this to install the skills yourself, read
+[INSTALL_FOR_AGENTS.md](INSTALL_FOR_AGENTS.md) instead. It is written as steps you
+can execute directly.

package/src/corpus/skill-brain.md

@@ -0,0 +1,49 @@
+---
+version: 0.2.0
+name: brain
+description: |
+  Refresh a CloudGrid entity's Grid Brain metadata. Use when the user wants to
+  re-classify an entity, regenerate its description, tags, or diagram, or update
+  how it appears in discovery after a change. Wraps cloudgrid brain refresh.
+argument-hint: "[name]"
+allowed-tools: Bash
+---
+
+# CloudGrid Brain
+
+Re-run the Grid Brain hooks for an entity to re-classify its description, tags, and
+diagram. Use this after a change so discovery reflects the current state. Wraps
+`cloudgrid brain refresh`.
+
+## Step 0 — Bootstrap
+
+1. If `cloudgrid` is not on `$PATH`: `npm install -g @cloudgrid-io/cli`
+2. If `cloudgrid whoami` fails: ask the user to run `cloudgrid login`. Wait for
+   confirmation.
+
+## UX rules
+
+- Be concise. Report what changed, not the full hook trace.
+- Detect the user's language from their first message and reply in it. Keep
+  technical flags in English.
+
+## How to run it
+
+```
+cloudgrid brain refresh my-thing --wait
+```
+
+`--wait` polls until the refresh finishes, up to about 60 seconds. Without it, the
+refresh runs in the background and the command returns right away. Use `--wait`
+when the user wants to see the result now.
+
+Other flags:
+
+- `--org <slug>` — target an entity in another org.
+- `--json` — machine-readable output.
+
+## Reading the output
+
+The refresh reports each hook: classify (description and tags), identification, and
+the diagram. Summarize the outcome in one line, for example "Re-classified with 3
+tags." Suggest `cloudgrid status <name>` if the user wants the full updated entity.

package/src/corpus/skill-claim.md

@@ -0,0 +1,53 @@
+---
+version: 0.2.0
+name: claim
+description: |
+  Claim an anonymous CloudGrid drop into the user's account. Use when the user
+  dropped something anonymously and now wants to keep it, own it, or stop it from
+  expiring after signing in. The public URL does not change.
+argument-hint: "[claim-url-or-token]"
+allowed-tools: Bash
+---
+
+# CloudGrid Claim
+
+Turn an anonymous drop into an owned one. After an anonymous drop, the user has a
+`claim_url` (or token). Once they sign in, claiming transfers ownership to them and
+extends the expiry from 7 days to 30. The shareable URL stays the same, so any link
+already shared keeps working.
+
+## Step 0 — sign in first
+
+Claiming needs an identity. If the user is not signed in, run the `cloudgrid:login`
+skill (or `cloudgrid login` with the CLI) first.
+
+## What you need
+
+The claim token from the anonymous drop. It is the `token` query parameter inside
+the `claim_url` the drop returned, for example
+`https://console.cloudgrid.io/claim?token=<TOKEN>`.
+
+## How to run it
+
+```
+JWT=$(jq -r .jwt ~/.cloudgrid/credentials 2>/dev/null)
+# TOKEN is the claim token (from claim_url's ?token=...)
+curl -sS -X POST https://api.cloudgrid.io/api/v2/anon-claim \
+  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
+  -d "{\"claim_token\":\"$TOKEN\"}"
+```
+
+The response is `{ "claimed": [ { "url", "new_expires_at" }, ... ] }`.
+
+## Reading the result
+
+- A non-empty `claimed` list means it worked. Tell the user the drop is now theirs,
+  the URL is unchanged, and the new expiry.
+- An empty `claimed` list means there was nothing to claim — it may already be
+  claimed or expired. Say so plainly.
+
+## Notes
+
+- One token claims one drop. To claim several, repeat with each token.
+- The MCP `cloudgrid_claim` tool does this for you, and remembers the token from the
+  last anonymous drop so you can claim with no arguments.

package/src/corpus/skill-drop.md

@@ -0,0 +1,111 @@
+---
+version: 0.2.0
+name: drop
+description: |
+  Share an artifact and get a public URL. Use when the user wants to share,
+  publish, send, or deploy an HTML page or file, or wants a link for a friend.
+  Works with no login (anonymous, 7-day, claimable later) or signed in (published
+  into the user's org, owned, 30-day). Inspirations only.
+argument-hint: "[file]"
+allowed-tools: Bash
+---
+
+# CloudGrid Drop
+
+Publish an artifact and get a shareable URL — with no account and no CLI. This is
+the fastest path from "I made a thing" to "here is a link."
+
+It calls the CloudGrid API directly. It does **not** use the `cloudgrid` CLI and it
+does **not** require login. That is the point: anyone can drop.
+
+## When to use this vs cloudgrid:plug
+
+- **Drop (this skill):** the user is not signed in, or just wants a quick public
+  link for an HTML page or file. Anonymous. Inspirations only.
+- **Plug (`cloudgrid:plug`):** the user is signed in and wants a full app deploy in
+  their own org. Uses the CLI.
+
+If the user is signed in and asks to "share" a static artifact, this skill still
+works and is faster; offer `cloudgrid:plug` only when they want an app.
+
+## UX rules
+
+- Be concise. The result the user wants is the URL. Print it plainly.
+- Detect the user's language from their first message and reply in it.
+- Do not ask the user to log in. The whole value here is that they do not have to.
+
+## How to run it
+
+You need a single HTML file. If the user gave you inline HTML, write it to a file
+first. The content must be a full HTML document (start with `<!doctype html>` or
+`<html>`); if you only have a fragment, wrap it in a minimal document. HTML is
+capped at 2 MB for anonymous drops.
+
+Then POST it:
+
+```
+curl -sS -X POST https://api.cloudgrid.io/api/v2/drop/auto \
+  -F "artifact=@/path/to/index.html;type=text/html"
+```
+
+The response is JSON. Read two fields:
+
+- `url` — the live, shareable link. Give this to the user.
+- `claim_url` — the link to sign in and keep it past the 7-day expiry.
+
+## If the user is signed in
+
+A signed-in user can publish into their own org instead of anonymously — the drop
+is owned, lasts 30 days, and needs no claim. Add their token and org to the same
+request:
+
+```
+JWT=$(jq -r .jwt ~/.cloudgrid/credentials 2>/dev/null)
+ORG=$(grep -E '^\s*active_org_slug:' ~/.cloudgrid/config.yaml | awk '{print $2}')
+curl -sS -X POST https://api.cloudgrid.io/api/v2/drop/auto \
+  -H "Authorization: Bearer $JWT" -H "X-CloudGrid-Org: $ORG" \
+  -F "artifact=@/path/to/index.html;type=text/html" -F "org_slug=$ORG"
+```
+
+The response has `owned_by: "authenticated"` and no `claim_url`. If the user is a
+member of several orgs and `X-CloudGrid-Org` is missing, the API replies with the
+list of orgs to choose from. The MCP `cloudgrid_drop` tool does this automatically
+when credentials are present.
+
+## Re-dropping (update in place)
+
+A re-drop of the same artifact updates it in place — same URL, new version, views
+and reactions intact. The platform matches ownership through the anon-session
+cookie, so keep a cookie jar across drops:
+
+```
+curl -sS -c jar.txt -X POST https://api.cloudgrid.io/api/v2/drop/auto \
+  -F "artifact=@index.html;type=text/html"                      # first drop
+curl -sS -b jar.txt -X POST https://api.cloudgrid.io/api/v2/drop/auto \
+  -F "previous_id=<entity_id from the first response>" \
+  -F "artifact=@index.html;type=text/html"                      # re-drop
+```
+
+Send `previous_id` before the artifact part. Read the status:
+
+- `200` — updated in place; the same `url` now serves the new bytes.
+- `202` — no change; this exact content is already live.
+- `201` — created new: no `previous_id`, or the previous drop was claimed, expired,
+  or not yours — the server falls back to create and never hard-fails.
+
+Omit `previous_id` to start a separate new drop. The MCP `cloudgrid_drop` tool does
+all of this for you (re-drops update in place; `fresh: true` forces a new one).
+
+## After the drop
+
+Print the `url` on its own line, by itself, so it can be copied in one go. Then add
+one line of context: an anonymous drop lasts 7 days and can be claimed to keep it;
+a signed-in drop is already owned. Do not bury the URL in prose.
+
+## Limits and errors
+
+- Anonymous drops are **inspirations only**. A full app needs sign-in — if the
+  artifact is an app, the API returns 401; switch to `cloudgrid:plug`.
+- HTML over 2 MB is rejected. Trim it or suggest signing in.
+- There is a per-IP and per-device daily cap. If you hit 429, tell the user to try
+  again later.