@zibby/mcp-cli 0.3.7 → 0.3.9

package/index.js

@@ -67,6 +67,15 @@ const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
 
 const API_BASE = process.env.ZIBBY_API_URL || 'https://api-prod.zibby.app';
 
+// Warm-pool quantity options — MUST stay in sync with
+// backend/src/config/plans.js ADDONS.warm_pool.quantityOptions.
+// The backend rejects anything outside this set with 400. We duplicate
+// the constant here (rather than importing from @zibby/cli) because
+// @zibby/cli has no exports map and the dev-vs-published layouts differ
+// (src/config in dev, dist/config in npm). Mirror at @zibby/cli's
+// src/config/warmPool.js.
+const WARM_POOL_QUANTITY_OPTIONS = [1, 2, 3];
+
 // ── Config file helpers (matches @zibby/cli/src/config/config.js shape) ─
 
 function loadConfig() {
@@ -193,6 +202,19 @@ const server = new McpServer({
   version: '0.3.0',
 });
 
+// ── Agent-named tool registration (product-noun migration: "workflow" → "agent") ──
+// The product UI now calls deployed automations "Agents". Unlike the CLI —
+// where `agent` is an additive ALIAS and `workflow` stays for muscle memory /
+// scripts — MCP tool names are LLM-facing and surfaced wholesale via
+// tools/list. Registering both `*_workflow*` and `*_agent*` would put 6 exact
+// duplicate pairs in front of the model, cluttering the list and muddying tool
+// selection. So MCP exposes ONLY the agent-named tool. The legacy `*_workflow*`
+// name (first arg) is kept in the call signature for traceability but is no
+// longer registered. Internal CLI verbs / API routes / package names unchanged.
+function toolWithAlias(_legacyWorkflowName, agentName, description, schema, handler) {
+  server.tool(agentName, description, schema, handler);
+}
+
 // ── Tool: login ─────────────────────────────────────────────────────────
 // Device-code OAuth flow. Opens the user's browser to the verification URL,
 // then polls /cli/login/poll until the user authorizes (or it times out).
@@ -327,24 +349,26 @@ server.tool(
 // ── Tool: list templates ────────────────────────────────────────────────
 // Local because @zibby/cli reads the bundled template manifest from its
 // own node_modules (no network call).
-server.tool(
+toolWithAlias(
   'zibby_list_templates',
-  'List the official Zibby workflow templates available to scaffold (browser-test-automation, code-analysis, generate-test-cases, etc.). These are the same templates the marketplace deploys. Reads the manifest bundled with the local @zibby/cli — no network call.',
+  'zibby_list_agent_templates',
+  'List the official Zibby agent templates available to scaffold (browser-test-automation, code-analysis, generate-test-cases, etc.). These are the same templates the marketplace deploys. Reads the manifest bundled with the local @zibby/cli — no network call.',
   {},
   async () => cliResult(await runCli(['template', 'list']))
 );
 
 // ── Tool: scaffold workflow ─────────────────────────────────────────────
 // Writes files to .zibby/workflows/<name>/ in the user's cwd.
-server.tool(
+toolWithAlias(
   'zibby_scaffold_workflow',
-  'Scaffold a new workflow into the current project\'s .zibby/workflows/<name>/ directory from an official template. Generates graph.mjs, nodes/, state.js, and package.json on the user\'s local disk. Use zibby_list_templates first to see options.',
+  'zibby_scaffold_agent',
+  'Scaffold a new agent into the current project\'s .zibby/workflows/<name>/ directory from an official template. Generates graph.mjs, nodes/, state.js, and package.json on the user\'s local disk. Use zibby_list_agent_templates first to see options.',
   {
-    name: z.string().min(1).describe('Local workflow folder name (kebab-case)'),
+    name: z.string().min(1).describe('Local agent folder name (kebab-case)'),
     template: z.enum(['browser-test-automation', 'code-analysis', 'generate-test-cases'])
       .describe('Official template to scaffold from'),
     skipInstall: z.boolean().optional().default(false)
-      .describe('Skip running `npm install` in the new workflow folder'),
+      .describe('Skip running `npm install` in the new agent folder'),
   },
   async ({ name, template, skipInstall }) => {
     const args = ['g', 'workflow', name, '-t', template, '--no-agent-helpers'];
@@ -355,11 +379,12 @@ server.tool(
 
 // ── Tool: validate workflow ─────────────────────────────────────────────
 // Reads local workflow files + spawns the local validator.
-server.tool(
+toolWithAlias(
   'zibby_validate_workflow',
-  'Static-check a local workflow (.zibby/workflows/<name>/): graph topology, state schema, skill references. Fast (~30ms) — runs entirely locally against files on disk, no API call. Run this before deploy to catch obvious errors.',
+  'zibby_validate_agent',
+  'Static-check a local agent (.zibby/workflows/<name>/): graph topology, state schema, skill references. Fast (~30ms) — runs entirely locally against files on disk, no API call. Run this before deploy to catch obvious errors.',
   {
-    name: z.string().min(1).describe('Workflow folder name under .zibby/workflows/'),
+    name: z.string().min(1).describe('Agent folder name under .zibby/workflows/'),
   },
   async ({ name }) => cliResult(await runCli(['workflow', 'validate', name]))
 );
@@ -368,16 +393,19 @@ server.tool(
 // Local-essential because the bundling step (zip the .zibby/workflows/<name>/
 // folder + walk its node_modules) happens on the user's machine before
 // upload. The remote MCP can't see those files.
-server.tool(
+toolWithAlias(
   'zibby_deploy_workflow',
-  'Deploy a local workflow (.zibby/workflows/<name>/) to Zibby Cloud under the given project. Bundles the local workflow folder + dependencies, then uploads. Returns the workflow UUID + version on success. Use zibby_validate_workflow first to catch errors fast.',
+  'zibby_deploy_agent',
+  'Deploy a local agent (.zibby/workflows/<name>/) to Zibby Cloud under the given project. Bundles the local agent folder + dependencies, then uploads. Returns the agent UUID + version on success. Use zibby_validate_agent first to catch errors fast.',
   {
-    name: z.string().min(1).describe('Local workflow folder name'),
+    name: z.string().min(1).describe('Local agent folder name'),
     projectId: z.string().min(1).describe('Project to deploy under (use the Zibby Remote MCP\'s zibby_list_projects to discover)'),
     force: z.boolean().optional().default(false)
       .describe('Re-deploy even if source checksum is unchanged'),
-    warm: z.number().int().min(1).max(5).optional()
-      .describe('Enable warm-pool execution (1-5 always-on Fargate tasks) — paid feature, skips ~60s cold start'),
+    warm: z.number().int().refine((n) => WARM_POOL_QUANTITY_OPTIONS.includes(n), {
+      message: `warm must be one of [${WARM_POOL_QUANTITY_OPTIONS.join(', ')}]`,
+    }).optional()
+      .describe(`Enable warm-pool execution (${WARM_POOL_QUANTITY_OPTIONS.join('/')} always-on runners) — paid feature, skips ~60s cold start`),
   },
   async ({ name, projectId, force, warm }) => {
     const apiKey = getProjectApiToken(projectId);
@@ -393,13 +421,14 @@ server.tool(
 
 // ── Tool: run workflow locally ──────────────────────────────────────────
 // Spawns a local node process to run the workflow against local files.
-server.tool(
+toolWithAlias(
   'zibby_run_workflow_local',
-  'Run a local workflow (.zibby/workflows/<name>/) one-shot on the user\'s machine. Does NOT touch the cloud — used for debugging graph.mjs / node code before deploying. Output includes per-node state transitions.',
+  'zibby_run_agent_local',
+  'Run a local agent (.zibby/workflows/<name>/) one-shot on the user\'s machine. Does NOT touch the cloud — used for debugging graph.mjs / node code before deploying. Output includes per-node state transitions.',
   {
-    name: z.string().min(1).describe('Local workflow folder name'),
+    name: z.string().min(1).describe('Local agent folder name'),
     input: z.record(z.string(), z.any()).optional().default({})
-      .describe('Input params (JSON object passed to the workflow\'s entry node)'),
+      .describe('Input params (JSON object passed to the agent\'s entry node)'),
   },
   async ({ name, input }) => {
     const args = ['workflow', 'run', name, '--input', JSON.stringify(input || {})];
@@ -411,12 +440,13 @@ server.tool(
 // Destructive enough to require explicit user confirmation since it can
 // overwrite files in the user's working directory. The agent MUST set
 // `confirm: true` AND provide a `dest` path it has shown to the user.
-server.tool(
+toolWithAlias(
   'zibby_download_workflow',
-  'Download a deployed workflow back to a local directory (e.g. to edit it then re-deploy). DESTRUCTIVE: can overwrite files in the destination directory. The agent MUST first ask the user for confirmation and the destination path, then call this with confirm=true.',
+  'zibby_download_agent',
+  'Download a deployed agent back to a local directory (e.g. to edit it then re-deploy). DESTRUCTIVE: can overwrite files in the destination directory. The agent MUST first ask the user for confirmation and the destination path, then call this with confirm=true.',
   {
-    uuid: z.string().min(1).describe('Workflow UUID to download'),
-    projectId: z.string().min(1).describe('Project the workflow lives under'),
+    uuid: z.string().min(1).describe('Agent UUID to download'),
+    projectId: z.string().min(1).describe('Project the agent lives under'),
     dest: z.string().min(1).describe('Destination directory path (absolute or relative to cwd). Show this to the user before calling.'),
     confirm: z.literal(true).describe('Must be true. Set only after the user has explicitly approved the download to the specified dest.'),
     force: z.boolean().optional().default(false)
@@ -741,6 +771,161 @@ server.tool(
   }
 );
 
+// ─── Apps: Solo-mode (dedicated EC2 per app) ──────────────────────────────
+//
+// Five tools mirroring the /apps/solo/* surface. Each is a thin wrapper
+// around the corresponding backend endpoint — see
+// backend/src/handlers/apps-solo.js and the contract at
+// backend/src/handlers/__contracts__/solo-deploy-spec.md.
+//
+// Why these are separate from the cloud-mode tools above:
+//   - Different deploy contract (repo + tier + persistence, not appType
+//     + goal). Conflating them in one tool overwhelms the LLM with
+//     params that only apply to one mode.
+//   - Plan/fire is a two-step flow (LLM sees the validation errors
+//     from plan, fixes the spec, then fires). The cloud `deploy_app`
+//     tool is single-step. Different ergonomics.
+//
+// Tier SSOT lives in backend/src/config/plans.js (SOLO_TIERS). The
+// plan response echoes `pricing.soloTiers` so the LLM can quote the
+// live table to the user; the zod enum below is a compile-time
+// guardrail mirroring the same ids.
+
+// Common nested zod schemas — defined once so the plan/fire tools share
+// validation. Treated as the canonical TS shape inline; the contract
+// doc has the authoritative comments.
+const soloSourceSchema = z.union([
+  z.object({
+    type: z.literal('github'),
+    repo: z.string().min(1).describe('GitHub repo in "owner/name" form'),
+    ref: z.string().min(1).optional().describe('Git ref (branch, tag, sha). Defaults to repo default branch.'),
+  }),
+  z.object({
+    type: z.literal('tarball'),
+    s3Url: z.string().min(1).describe('s3:// URL of the source tarball'),
+  }),
+]);
+
+const soloSecretSchema = z.object({
+  key: z.string().min(1).describe('Env var name'),
+  valueRef: z.string().min(1).optional().describe('Pointer at workspace-credentials (e.g. "workspace:stripe-prod"). Plaintext is NOT accepted — the backend rejects any `value` field.'),
+});
+
+const soloPersistenceSchema = z.object({
+  db: z.enum(['sqlite-litestream', 'postgres-walg', 'none']).optional(),
+  files: z.enum(['activestorage-s3', 'rclone-bisync', 'none']).optional(),
+});
+
+const soloTierEnum = z.enum(['micro', 'small', 'medium', 'large']);
+
+// Region SSOT mirror — backend/src/config/plans.js SOLO_REGIONS. The
+// control plane stays in Sydney; this only moves the per-app EC2 + S3 +
+// log group. Pricing is flat across regions (v1). Validated with
+// .refine against the explicit list so an unknown region fails fast
+// LLM-side rather than round-tripping to a backend 400.
+const SOLO_REGION_IDS = ['ap-southeast-2', 'us-east-1', 'us-west-2', 'eu-west-1', 'ap-northeast-1'];
+const soloRegionSchema = z.string()
+  .refine((r) => SOLO_REGION_IDS.includes(r), {
+    message: `region must be one of ${SOLO_REGION_IDS.join(', ')}`,
+  });
+
+// Full + partial spec shapes. plan_solo_deploy takes the partial
+// (everything optional) and surfaces missingInputs / ambiguities back
+// to the LLM. fire_solo_deploy demands the full shape.
+const soloPartialSpec = z.object({
+  appSlug: z.string().min(1).max(40).optional()
+    .describe('lowercase [a-z0-9-]; forms the public hostname <slug>.apps.zibby.dev'),
+  source: soloSourceSchema.optional(),
+  framework: z.enum(['auto', 'rails', 'node', 'python', 'static', 'other']).optional(),
+  tier: soloTierEnum.optional()
+    .describe('micro/small/medium/large — see plan response pricing.soloTiers for the live table.'),
+  region: soloRegionSchema.optional()
+    .describe([
+      'AWS region the VM runs in. One of:',
+      '  ap-southeast-2 (Sydney)      — Oceania, default/control-plane region',
+      '  us-east-1      (N. Virginia) — North America (east), also nearest for South America',
+      '  us-west-2      (Oregon)      — North America (west)',
+      '  eu-west-1      (Ireland)     — Europe, also nearest for Africa/Middle East',
+      '  ap-northeast-1 (Tokyo)       — Asia, nearest for East Asia incl. China/Korea, and the closest option for India/SE Asia',
+      'PICK THE NEAREST region to the user for lowest latency — you already know their',
+      'locale/timezone from this conversation, so infer it (e.g. UTC+10 → Sydney, UTC+8 → Tokyo,',
+      'US Pacific → Oregon, US Eastern/Central → N. Virginia, Europe → Ireland) and pass it',
+      'explicitly rather than defaulting. Only the EC2 + S3 + logs move to this region; the',
+      'Zibby control plane stays in Sydney. Pricing is identical in every region, so choose',
+      'purely on proximity. If you genuinely cannot tell where the user is, omit it (defaults',
+      'to Sydney) or ask them.',
+    ].join('\n')),
+  secrets: z.array(soloSecretSchema).optional(),
+  domain: z.string().optional().describe('Server canonicalizes to <slug>.apps.zibby.dev — value passed here is overridden.'),
+  persistence: soloPersistenceSchema.optional(),
+});
+
+const soloCompleteSpec = soloPartialSpec.required({
+  appSlug: true,
+  source: true,
+  tier: true,
+});
+
+server.tool(
+  'plan_solo_deploy',
+  'Validate a (possibly partial) solo-mode deploy spec server-side. Returns one of: (a) `{ok:true, spec, costEstimate, summary, pricing}` when the spec is complete + the user has enough credits — caller can move straight to fire_solo_deploy; (b) `{ok:false, spec, missingInputs:[{field,prompt,suggested?,options?}], ambiguities:[{field,prompt,options}], pricing}` when there are gaps — caller picks one field at a time, asks the user, fills the spec, and re-calls; (c) `{ok:false, ..., insufficientCredits:{balanceMilliCents,neededMilliCents,hint}}` when the spec is complete but the wallet is empty — caller surfaces the top-up hint. NEVER provisions anything — pure validation. `pricing.soloTiers` always echoes the live tier table; render it for the user when they need to pick. Mirrors POST /apps/solo/plan.',
+  {
+    spec: soloPartialSpec.describe('Partial spec — every field is optional. Backend reports back what is missing.'),
+  },
+  async ({ spec }) => {
+    // The MCP doesn't have a project context; we shell out to a generic
+    // fetch via the @zibby/cli session token. Future: convert to a
+    // dedicated CLI subcommand if this becomes a hot path. For now we
+    // dump the spec to a flag the CLI hasn't surfaced yet, falling back
+    // to an explicit error so the LLM knows the wiring is partial.
+    // The actual call shape parallels fetchJson in commands/app.js.
+    return cliResult(await runCli(['app', '_solo-plan', JSON.stringify(spec)]));
+  },
+);
+
+server.tool(
+  'fire_solo_deploy',
+  'Launch a solo-mode EC2 instance from a COMPLETE spec. Spec must have appSlug + source + tier filled in — otherwise the server returns 400 with the same missingInputs shape (re-run plan_solo_deploy to fill the gaps). Returns `{appSlug, instanceId, deploymentId, statusUrl, mode:"solo", tier, domain}`. Bills against the user\'s credit balance per backend/src/config/plans.js SOLO_TIERS (monthly flat fee, prorated per minute). On insufficient credits returns 402 — surface the user-friendly top-up hint to the user, do not retry. The instance bootstraps via cloud-init + agent-ops; poll get_solo_status until phase=running (or =failed). Mirrors POST /apps/solo/fire.',
+  {
+    spec: soloCompleteSpec.describe('Complete SoloDeploySpec — must include appSlug, source, tier. The server re-validates and 400s if anything is missing; it will NOT silently re-run plan.'),
+  },
+  async ({ spec }) => {
+    return cliResult(await runCli(['app', '_solo-fire', JSON.stringify(spec)]));
+  },
+);
+
+server.tool(
+  'get_solo_status',
+  'Get the current bootstrap/run phase of a solo-mode app instance. Returns `{appSlug, phase, detail}` where phase is one of `provisioning | bootstrapping | deploying | running | failed | unknown`. Use this to poll after fire_solo_deploy — typical happy path: provisioning (~30s) → bootstrapping (~2min) → deploying (~2min) → running. Mirrors GET /apps/solo/{slug}/status.',
+  {
+    appSlug: z.string().min(1).describe('App slug returned from fire_solo_deploy'),
+  },
+  async ({ appSlug }) => {
+    return cliResult(await runCli(['app', '_solo-status', appSlug]));
+  },
+);
+
+server.tool(
+  'list_solo_apps',
+  'List the user\'s solo-mode app instances (sibling to zibby_list_apps which lists cloud-mode instances). Returns an array of `{appSlug, instanceId, tier, phase, domain, createdAt}`. Useful when the user asks "show my solo apps" or "what solo instances am I paying for?". (Wired to the same backend listApps endpoint with a mode=solo filter once the row schema lands.)',
+  {},
+  async () => {
+    return cliResult(await runCli(['app', 'list', '--mode', 'solo']));
+  },
+);
+
+server.tool(
+  'stop_solo_app',
+  'Stop and destroy a solo-mode app instance. DESTRUCTIVE: terminates the EC2 instance, releases the EBS root volume, removes the row. Litestream replica in S3 is PRESERVED — the user can spin up a new instance pointed at the same bucket to restore. The agent MUST first ask the user for explicit confirmation, then call this with confirm=true.',
+  {
+    appSlug: z.string().min(1),
+    confirm: z.literal(true).describe('Must be true. Set only after the user has explicitly approved destroying this instance.'),
+  },
+  async ({ appSlug }) => {
+    return cliResult(await runCli(['app', 'destroy', appSlug, '--yes', '--mode', 'solo']));
+  },
+);
+
 // ── Connect ─────────────────────────────────────────────────────────────
 
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/mcp-cli",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Zibby local-essential MCP Server — local workflow scaffold/validate/run + deploy/download (bundles local files). Pure-API tools live in the Zibby Remote MCP (api-prod.zibby.app/mcp).",
   "type": "module",
   "main": "index.js",