You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 35b5bda
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: MCP_QUICKSTART.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -37,7 +37,7 @@ If Cursor shows the plugin installed but `plugins/cache/agentstack` is empty, se
37
37
|**Plugin MCP** (`plugin-agentstack-*` in Cursor) | Marketplace install; click **Connect** (G-A174) | After OAuth Connect on plugin panel |
38
38
|**User MCP** (`~/.cursor/mcp.json` → `agentstack`) | Device Code `/agentstack-authorize` or profile API key | Bearer / X-API-Key in headers |
39
39
40
-
**Common trap:** Cursor agents call **plugin** MCP without Bearer. `/agentstack-authorize` writes `~/.cursor/mcp.json` only — run `node scripts/refresh-cursor-runtime.mjs --fix` (or re-authorize; device-code syncs cache) then **Reload Window**so plugin cache `mcp.json` gets the same Bearer. `mcp_auth` does **not** bridge Device Code. Fallback: Connect (G-A174) or `mcp-execute.mjs` below.
40
+
**Common trap:** Cursor agents call **plugin** MCP without OAuth Connect. `/agentstack-authorize` writes Bearer in `~/.cursor/mcp.json` only — plugin runtime stays **URL-only** until Connect (G-A174). Use `mcp-execute.mjs` for Bearer-backed probes, or click **Connect**then Reload Window. `mcp_auth` does **not** bridge Device Code.
41
41
42
42
OAuth 2.1 Device Code via `/agentstack-authorize` (or `/agentstack-init`) → Bearer in `~/.cursor/mcp.json`.
**Tenant workspace (OAuth / password):**Connect or Device Code mints a**user-scoped**Bearer (JWT may show ecosystem `project_id=1`). Before tenant **mutations**, run recipe `mcp_session_setup` → set **`context.project_id`** → confirm **`auth.get_profile`** → **`mutation_allowed`** or **`session_ready`**. Call **`auth.switch_project`** only when **`required_client_action`** is **`apply_bearer`** (typical: project-pinned API key). Cursor hook **`pre-mcp-session-handoff.mjs`** runs REST switch only when a batch includes **`auth.switch_project`**. **ChatGPT-only OAuth:** if switch tokens are redacted, Disconnect → Connect after picking workspace, or Device Code.
59
+
**Tenant workspace (OAuth / password):**One Bearer, many projects — set**`options.context.project_id`**per execute; **`jwt_project_aligned=false`** with **`mutation_allowed=true`** is normal (JWT often `project_id=1`). Do **not**`auth.switch_project` on every hop. SoT: monorepo `docs/architecture/MCP_UNIFIED_OPERATOR_SESSION.md` + recipe `mcp_session_setup` → **`auth.get_profile`** → **`preflight.check`**. **`auth.switch_project`** only when **`required_client_action=apply_bearer`** (project-pinned API key). Cursor hook **`pre-mcp-session-handoff.mjs`** runs REST switch only when a batch includes **`auth.switch_project`**. **ChatGPT-only OAuth:** if switch tokens are redacted, Disconnect → Connect after picking workspace, or Device Code.
|`env_uuid_project_only`| Omit env_uuid or set home=project and retry. self and project_self are the session row and cannot take a sandbox slice. |
220
220
|`graph_home_unknown`| home must be project, self, or project_self. Retry agents.plan_get or agents.plan_patch with one of those values. |
221
221
|`graph_home_address_required`| Personal home needs a resolved session address. Pass home on the tool and ensure the operator session has user_id before patch. |
222
-
|`plan_ops_parent_missing`| add_child parent_id is not in the graph — create the parent first or fix parent_id. |
222
+
|`plan_ops_parent_missing`| add_child parent_id is not in the graph — create the parent first or fix parent_id. On an empty project graph (revision 0, no tasks), omit parent_id and send {op:add_child, node:{id, title, kind}} with if_match_revision:0 from plan_get; do not use op set for new ids. |
223
223
|`plan_graph_children_exceeded`| Direct children per parent are capped (32). Flat parent_id storage counts siblings under each parent_id — not total graph nodes. Split into sub-groups or use agents.plan_propose decompose_node. |
224
224
|`plan_graph_too_large`| The merged graph does not fit the JSON leaf (see graph_limits.inline_write_hard_limit_bytes, typically 512 KiB). Bodies spill near chunk_spill_target_bytes (~400 KiB). For huge prose use node.prompt/detail (not only meta.description), append_storage_ref (stubs inline text), reorder_children {parent_id,child_ids}, or storage file maps in meta.storage_refs. Cards keep ~200-char stubs after spill. Read one node with plan_get detail=body and node_id. Archive completed nodes (op archive) if titles/meta still overflow. Do not retry the same blob. Leaf heal ladder: agents.plan_compaction_preview → agents.plan_heal_leaf dry_run=true → apply. |
225
225
|`plan_graph_oversize`| Plan graph exceeds size budget — agents.plan_compaction_preview then agents.plan_heal_leaf (dry_run then apply); archive completed subtrees or split objectives. |
Copy file name to clipboardExpand all lines: plugins/agentstack/skills/agentstack-backend/SKILL.md
+5-1Lines changed: 5 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -53,6 +53,10 @@ AgentStack is a **full backend ecosystem** exposed through ONE MCP tool: `agents
53
53
54
54
Pick the **primary** bucket first; consult others by reference for multi-step flows.
55
55
56
+
## MCP error recovery → operator report
57
+
58
+
When a failed `agentstack.execute` step includes `data.report_suggested`, offer a one-shot follow-up batch: `diagnostics.report` with the provided `prefill` (merge user summary). Distinct from `social.support.send` (tenant product) and `trust.feedback` (AgentNet). CLI: `mcp-execute.mjs` prints a hint when `report_suggested` is present.
59
+
56
60
**Disambiguation:** project treasury → `agentstack-project-wallet`; personal/commerce wallet → `agentstack-commerce`; inbound Stripe webhook → `agentstack-integrations` (never `@stripe/stripe-js` for AgentStack checkout); **SMTP/Resend email** → `agentstack-messaging` (`messaging.*`); in-app/Web Push → `agentstack-signals` (`notifications.send_push`). Cursor plugin sign-in → `/agentstack-authorize`, not `auth.login`. **Claude asks for scoped API key first** → stop — use MCP Connect (web) or Device Code `--scope-preset=full` per `auth.get_profile.auth_surface.client_auth_ladder`; scoped keys are for CI/automation (`apikeys.create` preset `agent_runner`) only. Product archetype first → `/agentstack-product-flow` or `docs/plugins/PRODUCT_BUILD_FLOW.md`.
57
61
58
62
## User request → action (hot paths)
@@ -226,7 +230,7 @@ Sync `agentstack.execute` is **60s for the whole batch** (`mcp_batch`) — not a
226
230
## MCP guidance
227
231
228
232
-**Catalog:**`GET https://agentstack.tech/mcp/actions` (or `/agentstack-capability-matrix`) — never hard-code action counts.
229
-
-**Execute:**one tool `agentstack.execute`; steps use canonical `action` ids from the catalog.
233
+
-**Execute:**`agentstack.execute` for writes; `agentstack.read` for read/evaluate (same batch body, short wire schema). Steps use canonical `action` ids from the catalog.
230
234
-**Prompts:**`agentstack_execute_budget`, `agentstack_write_modes`, `agentstack_read_bootstrap` via `GET /mcp/prompts/get`.
| "single HTML landing" | recipe `mcp_hosting_static_landing_v1`| deploy_files without recipe |
14
14
| "edit one CSS/HTML file on /s/" |`hosting.bucket.file.patch` (`search_replace`); recipe `mcp_hosting_edit_text_file_v1` — no prior GET; response `gzip_sibling: refreshed` + optional `cache_bust` — **never** manual gzip or `bulk_delete``.gz`|`storage.upload` or full `hosting.deploy_files`|
| "React/Vite dist upload" |`hosting.site.import_archive`, `hosting.site.upload_grant` + grant POST; recipe `mcp_hosting_react_dist_v1` for ready `dist/` ZIP |`hosting.deploy_files`, `hosting.storage.import_folder`|
16
+
| "App Studio game / WebGL after Vite build" |`ai_builder.build.enqueue` → `build.status` completed → `hosting.project.status` → **`ai_builder.publish`** — live URL = **`public_url_absolute`** (`https://agentstack.tech/s/{pid}/{slug}/`) |`hosting.site.quick_start` HTML stub for full SPA |
17
+
| "React/Vite sources / GitHub URL" | Same `hosting.site.import_archive` (source ZIP or git `source_url`) → poll `hosting.site.build_status` when response has `job_id`; recipe `mcp_hosting_workspace_build_v1`| Client-side `npm run build`; separate `pull_upstream` without import |
16
18
| "deploy ZIP" / "static site" |`hosting.site.import_archive` or `hosting.site.upload_grant`; CLI `agentstack hosting deploy --zip`|`hosting.deploy_files` (no unzip), Custom S3 |
-**Control panel:**`/dev/projects/{id}/storage/sites` (or `/user/...` for user shell) — not legacy `/hosting`.
71
-
-**Canonical URL:**`/s/{project_id}/{bucket_name}/` — wait for `edge_ready` before telling the user the site is live.
73
+
-**Canonical URL:**`https://agentstack.tech/s/{project_id}/{bucket_name}/` (`public_path` = `/s/{project_id}/{bucket_name}/`) — same as `hosting.project.status` → `sites.primary_public_url`. Wait for `edge_ready` before telling the user the site is live.
74
+
-**App Studio publish:** static landing only → `hosting.site.quick_start`; built Vite/game → `ai_builder.publish` after `build.status` = `completed` (omit `bucket_id` when primary site exists).
72
75
-**Quota triage:**`hosting.project.status` → `quota.artifact_bytes_used_gate` vs limit; then `hosting.quota.breakdown` (alias `hosting.bucket.usage`); if over limit → `hosting.gc.orphans` dry_run → `hosting.quota.recount` dry_run. Never bulk_delete `assets/` manually — use `hosting.site.prune` when available.
73
76
-**Deploy honesty:** if `publish_failed` or `success: false`, read `live_changed` and `next_action`; do not treat step as ✅.
74
77
- Site bytes count toward the owner storage pool — `storage.get_quota` + hosting gate fields on storage hub summary.
0 commit comments