@cloudgrid-io/mcp 0.4.7 → 0.5.0

package/src/corpus/skill-feedback.md

@@ -0,0 +1,49 @@
+---
+version: 0.2.0
+name: feedback
+description: |
+  Read the CloudGrid feedback feed. Use when the user wants to see feedback, check
+  what people said, review reactions, or read recent feedback events for their org.
+  Wraps cloudgrid feedback list.
+argument-hint: "[--since 7d]"
+allowed-tools: Bash
+---
+
+# CloudGrid Feedback
+
+List recent feedback events for the active org. Wraps `cloudgrid feedback list`.
+
+## 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. Summarize the feed; do not paste every event verbatim.
+- Detect the user's language from their first message and reply in it. Keep
+  technical flags in English.
+
+## How to run it
+
+```
+cloudgrid feedback list
+```
+
+The feed is scoped to the active org. It is not filtered by entity. Useful flags:
+
+- `--since <duration>` — only events newer than this, for example `24h`, `7d`.
+- `--limit <n>` — number of events. Default 50, max 200.
+- `--org <slug>` — read another org's feed (where you have access).
+
+## Reading the output
+
+Each event has a time, an id, an org, and a message. Group or summarize by theme
+when there are many. Surface the ones that look like bugs or blockers first.
+
+## Note: reading vs sending
+
+This skill reads the feed. `cloudgrid feedback "<message>"` does the opposite: it
+sends feedback to the CloudGrid team. Do not send feedback unless the user clearly
+asks to report something.

package/src/corpus/skill-init.md

@@ -0,0 +1,72 @@
+---
+version: 0.2.0
+name: init
+description: |
+  Scaffold a new CloudGrid app or agent. Use when the user wants to start a new
+  project, create a new entity, set up a new app or agent, or seed a web service
+  (node, nextjs, python, or static) before deploying. Wraps cloudgrid init.
+argument-hint: "[app|agent] [name]"
+allowed-tools: Bash
+---
+
+# CloudGrid Init
+
+Register a new app or agent in the active org and, optionally, seed a web service
+to deploy. Wraps `cloudgrid init`. After this, `cloudgrid:plug` deploys it.
+
+## 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. No raw IDs, no JSON dumps in chat.
+- Detect the user's language from their first message and reply in it. Keep
+  technical flags in English.
+- Pick sane defaults. Ask one thing at a time, only when something is missing.
+
+## What to ask
+
+You need two things: the kind and the name.
+
+- **Kind:** `app` or `agent`. Default to `app` unless the user describes an agent
+  (something that acts on its own, calls tools, or runs on a schedule).
+- **Name:** a slug, 3 to 40 lowercase letters, numbers, or hyphens. If the user
+  gives a title, derive a slug from it. Confirm the slug before running.
+
+Optional, only if the user implies them:
+
+- `--type` to seed a web service: `node`, `nextjs`, `python`, or `static`.
+- `--dir` to scaffold somewhere other than `./<name>`.
+- `--description` for a one-line description.
+
+## Usage
+
+Register an app and seed a static site:
+
+```
+cloudgrid init app my-thing --type static
+```
+
+Register an agent:
+
+```
+cloudgrid init agent my-helper
+```
+
+Register without seeding any files (you will add your own):
+
+```
+cloudgrid init app my-thing
+```
+
+## After init
+
+Tell the user the entity is registered and what is next: `cd` into the directory
+(if seeded) and run `cloudgrid plug` to deploy. Hand off to `cloudgrid:plug`.
+
+## References
+
+- [./references/options.md](./references/options.md) — full flag list and the four service types.

package/src/corpus/skill-login.md

@@ -0,0 +1,86 @@
+---
+version: 0.2.0
+name: login
+description: |
+  Sign in to CloudGrid, with or without the CLI. Use when the user wants to log in,
+  sign in, authenticate, connect their account, or claim an anonymous drop they made
+  earlier. Uses CloudGrid's existing OAuth. No new account needed.
+argument-hint: ""
+allowed-tools: Bash
+---
+
+# CloudGrid Login
+
+Get the user a CloudGrid identity token. This is the step that turns an anonymous
+user into an owned one — and the step that lets them claim earlier anonymous drops.
+
+There are two paths. Pick the first that fits.
+
+## Path 1 — the CLI is installed
+
+If `cloudgrid` is on `$PATH`, this is the simplest and safest:
+
+```
+cloudgrid login
+```
+
+It opens the browser, handles the OAuth flow, and stores the token. Stop here.
+
+## Path 2 — no CLI (the CLI-free flow)
+
+Reproduce the same OAuth flow by hand. It writes the same credentials file the CLI
+uses (`~/.cloudgrid/credentials`), so the two share one identity.
+
+1. Make a session code and give the user the sign-in URL:
+
+   ```
+   CODE=$(uuidgen | tr 'A-Z' 'a-z')
+   echo "Open this and sign in with Google: https://api.cloudgrid.io/auth/login?code=$CODE"
+   ```
+
+   Show the user the URL. Wait for them to say they finished.
+
+2. Poll for the token (the window is 5 minutes; it is single-use):
+
+   ```
+   curl -sS "https://api.cloudgrid.io/auth/status?code=$CODE"
+   ```
+
+   - `{"status":"pending"}` or `404` — not done yet. Ask the user to finish, retry.
+   - `{"status":"authenticated","jwt":"..."}` — capture the `jwt`. Continue.
+   - `{"status":"expired"}` — the window closed. Start over from step 1.
+
+3. Save the token in the CLI's format, readable only by the user:
+
+   ```
+   umask 077 && mkdir -p ~/.cloudgrid
+   # JWT holds the token captured above
+   PAYLOAD=$(printf '%s' "$JWT" | cut -d. -f2 | tr '_-' '/+')
+   EMAIL=$(printf '%s==' "$PAYLOAD" | base64 -d 2>/dev/null | (jq -r .email 2>/dev/null || true))
+   UID=$(printf '%s==' "$PAYLOAD" | base64 -d 2>/dev/null | (jq -r .sub 2>/dev/null || true))
+   printf '{"jwt":"%s","issued_at":"%s","email":"%s","user_id":"%s"}\n' \
+     "$JWT" "$(date -u +%FT%TZ)" "$EMAIL" "$UID" > ~/.cloudgrid/credentials
+   chmod 600 ~/.cloudgrid/credentials
+   ```
+
+   If `jq` is not available, leave `email` and `user_id` empty — only the `jwt`
+   matters; the server reads identity from the token itself.
+
+## UX rules
+
+- Be concise. The user does one thing: open a link and sign in.
+- Detect the user's language from their first message and reply in it.
+- Never write the token anywhere except `~/.cloudgrid/credentials`. Never print it.
+
+## After login
+
+Confirm the user is signed in (`cloudgrid whoami` if the CLI is present). If they
+made an anonymous drop earlier, this is the moment to offer to claim it.
+
+## Notes
+
+- Enterprise single sign-on is not supported in this flow yet; those users sign in
+  through the Console for now.
+- The MCP server exposes the same flow as `cloudgrid_login` and
+  `cloudgrid_login_status`, which handle the polling and the credentials write for
+  you.

package/src/corpus/skill-logs.md

@@ -0,0 +1,52 @@
+---
+version: 0.2.0
+name: logs
+description: |
+  Tail logs for a CloudGrid entity. Use when the user wants to see logs, watch
+  output, follow a running app, debug a deploy, or check why something is failing.
+  Wraps cloudgrid logs.
+argument-hint: "[name]"
+allowed-tools: Bash
+---
+
+# CloudGrid Logs
+
+Stream or tail logs from an entity's pods. Wraps `cloudgrid logs`.
+
+## 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. Show the relevant lines, not the whole buffer.
+- Detect the user's language from their first message and reply in it. Keep
+  technical flags and log output in their original form.
+
+## How to run it
+
+Tail the recent logs for an entity by name:
+
+```
+cloudgrid logs my-thing
+```
+
+With no name, it uses the entity linked to the current directory.
+
+Useful flags:
+
+- `--tail <n>` — number of recent lines. Default 100.
+- `--since <duration>` — only logs newer than this, for example `5m`, `1h`, `2d`.
+- `--follow` — stream continuously.
+
+Use `--follow` only when the user asks to watch live. It does not return on its
+own, so do not use it for a one-time check. For a quick look, use `--tail` or
+`--since` instead.
+
+## Reading the output
+
+If the user is debugging, summarize what the logs show: the error, the failing
+request, or that the service is healthy. Quote the key lines. Do not paste pages
+of output into chat.

package/src/corpus/skill-plug.md

@@ -0,0 +1,57 @@
+---
+version: 0.2.0
+name: plug
+description: |
+  Deploy a directory or URL to CloudGrid. Use when the user wants to ship, deploy,
+  publish, or go live with the current project, or turn a URL into a hosted entity.
+  Live in about 30 seconds. Wraps cloudgrid plug.
+argument-hint: "[path-or-url]"
+allowed-tools: Bash
+---
+
+# CloudGrid Plug
+
+Build and deploy a directory, a path, or a URL. Prints the live URL when it is
+done. This is the center of the build-and-ship loop. Wraps `cloudgrid plug`.
+
+## 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. No raw IDs, no JSON dumps in chat.
+- Detect the user's language from their first message and reply in it. Keep
+  technical flags in English.
+- The deploy streams build progress. Let it run. Do not interrupt it.
+
+## How to run it
+
+Most of the time, run it from the project directory with no arguments:
+
+```
+cloudgrid plug
+```
+
+It uses the entity linked to the directory, builds, deploys, and prints the URL.
+A first deploy usually takes about 30 seconds; larger builds take longer.
+
+Other shapes:
+
+- **A specific path:** `cloudgrid plug ./site`
+- **A URL as an inspiration:** `cloudgrid plug https://example.com`
+- **Bind to an existing entity first:** `cloudgrid plug --existing <entity-id>`
+
+If this is the user's first deploy in the org, the CLI may ask which org to use.
+Pass `--org <slug>` to skip that prompt.
+
+## After plug
+
+Print the live URL plainly. Then offer the next steps: `cloudgrid:logs` to watch
+it, or `cloudgrid:share` to make it reachable by others.
+
+## References
+
+- [./references/options.md](./references/options.md) — flags, URL inspirations, and first-deploy behavior.

package/src/corpus/skill-share.md

@@ -0,0 +1,55 @@
+---
+version: 0.2.0
+name: share
+description: |
+  Make a CloudGrid entity shareable and print its URL. Use when the user wants to
+  share a link, make something public, send an app to someone, or get a shareable
+  URL. Wraps cloudgrid visibility.
+argument-hint: "[name]"
+allowed-tools: Bash
+---
+
+# CloudGrid Share
+
+Set an entity's visibility so others can reach it, then print the URL. Wraps
+`cloudgrid visibility set`.
+
+## 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. The result the user wants is the URL. Print it plainly.
+- Detect the user's language from their first message and reply in it. Keep
+  technical flags in English.
+
+## How to run it
+
+To make an entity reachable by anyone with the link:
+
+```
+cloudgrid visibility set my-thing link
+```
+
+The command prints the outlet URL. Hand that URL to the user.
+
+## Visibility modes
+
+`cloudgrid visibility set <slug> <mode>` accepts:
+
+- `link` — anyone with the URL can open it. Use this for sharing.
+- `private` — only the owner.
+- `authenticated` — any logged-in user.
+- `org` — members of the org.
+- `space` — members of the entity's space.
+
+Default to `link` when the user says "share" or "make it public". Confirm before
+using a wider mode than they asked for.
+
+## After share
+
+Print the outlet URL on its own line, by itself, so it can be copied in one go.
+Then, if it fits, offer the `feedback` skill to see what people say about it.

package/src/corpus/skills-readme.md

@@ -0,0 +1,92 @@
+# CloudGrid Skills
+
+Multi-agent skills for CloudGrid. Install them in Claude Code, Codex, or Cursor,
+and your agent can build, ship, and run things on CloudGrid through the
+`cloudgrid` CLI.
+
+## Why CloudGrid
+
+Claude Code and Codex removed the wall around writing code. CloudGrid removes the
+wall around shipping it. A directory or a URL becomes a live, addressable thing in
+about 30 seconds. These skills are how your agent crosses that second wall on your
+behalf: scaffold, deploy, tail logs, share, read feedback. Everything here is free.
+
+## Install in 3 steps
+
+1. Install the CLI:
+
+   ```
+   npm install -g @cloudgrid-io/cli
+   ```
+
+2. Log in:
+
+   ```
+   cloudgrid login
+   ```
+
+3. Add the skills. In Claude Code (recommended):
+
+   ```
+   /plugin marketplace add cloudgrid-io/skills
+   /plugin install cloudgrid
+   ```
+
+   They show under `/plugin` and `/skills` as `cloudgrid:drop`, `cloudgrid:login`,
+   … — or just say what you want ("drop this HTML to CloudGrid") and the right one
+   triggers.
+
+   Or install with the `gh skill` extension:
+
+   ```
+   gh skill install cloudgrid-io/skills
+   ```
+
+   Other agents (Cursor, Cline, Gemini CLI): `npx skills add cloudgrid-io/skills`.
+   They install as `drop`, `plug`, … — the CloudGrid brand comes from the plugin
+   namespace, which those agents don't have.
+
+   Claude Desktop, claude.ai, ChatGPT, and every route in one place: [USAGE.md](USAGE.md).
+
+## Share something in one step, no login
+
+```
+/cloudgrid:drop index.html
+```
+
+`cloudgrid:drop` publishes an HTML page or file and hands back a public URL. No
+account, no CLI. The link lasts 7 days, and you can sign in later to keep it.
+
+## Skills
+
+| Skill | Invoke | What it does |
+|---|---|---|
+| `drop` | `/cloudgrid:drop` | Share an HTML page or file, get a public URL. Login optional. |
+| `login` | `/cloudgrid:login` | Sign in to CloudGrid, with or without the CLI. |
+| `claim` | `/cloudgrid:claim` | Claim an anonymous drop into your account after signing in. |
+| `init` | `/cloudgrid:init` | Scaffold a new app or agent. |
+| `plug` | `/cloudgrid:plug` | Deploy a directory or URL. Live in about 30 seconds. |
+| `logs` | `/cloudgrid:logs` | Tail logs for an entity. |
+| `share` | `/cloudgrid:share` | Make an entity shareable and print its URL. |
+| `feedback` | `/cloudgrid:feedback` | Read the feedback feed. |
+| `brain` | `/cloudgrid:brain` | Refresh an entity's Grid Brain metadata. |
+
+## The canonical chain
+
+```
+init  ->  plug  ->  logs  ->  share  ->  feedback
+```
+
+That is the full "I built a thing and shipped it" loop. [COOKBOOK.md](COOKBOOK.md)
+walks through it end to end.
+
+## MCP server
+
+The `@cloudgrid-io/mcp` package exposes the same nine actions as MCP tools, for
+agents that speak the Model Context Protocol. It wraps the same `cloudgrid` CLI.
+Install it with `npx -y @cloudgrid-io/mcp`, or point a remote-capable client at
+`https://mcp.cloudgrid.io/mcp`. See [USAGE.md](USAGE.md) for per-client setup.
+
+## License
+
+Apache 2.0. See [LICENSE](LICENSE).

package/src/corpus/usage.md

@@ -0,0 +1,138 @@
+# Using CloudGrid skills and MCP
+
+This repo ships two things that expose the **same** CloudGrid actions — drop, login,
+claim, init, plug, logs, share, feedback, brain:
+
+- **Skills** — `SKILL.md` files an agent loads. They trigger from natural language
+  (their `description`) or a slash command.
+- **MCP server** — the same actions as MCP tools, for clients that speak the Model
+  Context Protocol.
+
+Which one you use depends on the client. Pick your client below.
+
+## Prerequisites
+
+- **Node 18+** (for `npx`).
+- **No login needed to try it** — anonymous drop works out of the box. For owned
+  drops (into your org), run `cloudgrid login` once, or use the `login` skill / the
+  `cloudgrid_login` MCP tool.
+
+---
+
+## Claude Code (terminal, VS Code, JetBrains)
+
+Three install routes. They land in **different menus** — this is the most common
+point of confusion.
+
+### Route 1 — skills via the skills CLI
+```
+npx skills add cloudgrid-io/skills
+```
+- Installs into `~/.claude/skills/` (personal). Auto-loads, no restart.
+- **Find them under `/skills`** (labeled Personal). **Not** under `/plugin`.
+- Invoke as **`/drop`**, `/login`, … (bare — the personal route has no namespace), or describe the task.
+
+### Route 2 — skills as a plugin
+```
+/plugin marketplace add cloudgrid-io/skills
+/plugin install cloudgrid
+```
+- **Find it under `/plugin`**; the skills also show under `/skills` (labeled Plugin).
+- Invoke as **`/cloudgrid:drop`** (plugin namespace + short skill name, like `superpowers:brainstorming`), or describe the task.
+
+### Route 3 — the MCP server
+```
+claude mcp add cloudgrid -- npx -y @cloudgrid-io/mcp
+```
+- **Find it under `/mcp`.** Exposes tools `cloudgrid_drop`, `cloudgrid_login`, …
+- Invoke by describing the task; the model calls the tool.
+
+> Where did my install go? `/skills` (skills), `/plugin` (plugin), `/mcp` (MCP).
+> If you don't see something, you're probably looking in the wrong menu, or you
+> installed a different route than you're checking. `/doctor` flags real problems.
+
+### Sharing with a team (Claude Code)
+Commit a project-scoped MCP so teammates get it on clone:
+```
+cd your-shared-repo
+claude mcp add cloudgrid -s project -- npx -y @cloudgrid-io/mcp
+git add .mcp.json && git commit -m "add CloudGrid MCP"
+```
+Or each person runs Route 1 or `claude mcp add ... -s user` once.
+
+---
+
+## Claude Desktop (chat)
+
+Desktop chat extends via **MCP only** — it does not read a skills folder. Add to
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+```json
+{ "mcpServers": { "cloudgrid": { "command": "npx", "args": ["-y", "@cloudgrid-io/mcp"] } } }
+```
+Then **fully quit and reopen** Claude Desktop. The CloudGrid tools appear under the
+tools icon. Invoke by describing the task: "drop this HTML to CloudGrid."
+
+---
+
+## Codex, Cursor, Cline, Gemini CLI, and other coding agents
+
+```
+npx skills add cloudgrid-io/skills
+```
+Installs into the universal `.agents/skills/` location these agents read (Cursor
+also reads `~/.cursor/skills`; target one agent with `-a codex` / `-a cursor`).
+Codex and Cursor also take the plugin route (`codex plugin marketplace add
+cloudgrid-io/skills`; Cursor's in-app marketplace) and the MCP server — local
+(`npx -y @cloudgrid-io/mcp` in their MCP config) or remote with nothing installed
+(`https://mcp.cloudgrid.io/mcp` as a `url` entry in `~/.codex/config.toml` or
+`~/.cursor/mcp.json`). See INSTALL.md for exact snippets.
+
+---
+
+## claude.ai web and the ChatGPT app
+
+These connect to **remote** MCP servers (by URL), not local ones. The hosted web
+edition is live — add it as a custom connector:
+
+Two endpoints, two postures:
+
+```
+https://mcp.cloudgrid.io/mcp             anonymous-first: drop with no sign-in
+https://mcp-connected.cloudgrid.io/mcp   connected: native sign-in when you add it
+```
+
+The connected endpoint runs the client's own OAuth connect at add-time (sign in
+with CloudGrid right in the flow); every drop is owned from the first one. The
+anonymous endpoint needs no account; sign in later from inside the conversation.
+
+- **claude.ai web** — Settings → Connectors → add custom connector.
+- **ChatGPT** — add it as a custom connector (Developer Mode; availability depends
+  on plan / rollout).
+- **Codex and Cursor** accept the same URL — see the section above.
+
+---
+
+## Skill vs MCP — which should I use?
+
+Same capabilities; different surface.
+
+- **Skills** carry guidance (when to use, how to phrase results) and auto-trigger
+  from natural language. Best in agents that read skills (Claude Code, Cursor, …).
+- **MCP** exposes the actions as tools. Best where skills are not read (Claude
+  Desktop, claude.ai web, ChatGPT) or when you want explicit tools.
+
+You can install both; they do not conflict.
+
+## Capabilities (both surfaces)
+
+| Action | What it does |
+|---|---|
+| drop | Share an artifact, get a public URL. No login needed (anonymous, 7-day) or owned if signed in (30-day). |
+| login | Sign in to CloudGrid, with or without the CLI. |
+| claim | Claim an anonymous drop into your account; the URL stays the same. |
+| init | Scaffold a new app or agent. |
+| plug | Deploy a directory or URL. |
+| logs | Tail an entity's logs. |
+| share | Set visibility and print the URL. |
+| feedback | Read the feedback feed. |
+| brain | Refresh Grid Brain metadata. |