@zibby/mcp-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zibby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# @zibby/mcp-cli
+
+Zibby's CLI as a Model Context Protocol server. Lets any MCP-aware AI agent — Claude Code, Cursor, OpenAI Codex, Gemini CLI, Continue, Cline, Aider, Goose — deploy, run, debug, and trigger Zibby workflows from chat.
+
+## What you get
+
+13 MCP tools wrapping the same things `@zibby/cli` does:
+
+| Tool | What it does |
+|---|---|
+| `zibby_login` | Opens the user's browser to log in (device-code OAuth). Saves session to `~/.zibby/config.json`. |
+| `zibby_logout` | Clears the saved session. |
+| `zibby_status` | Shows who's logged in + cached projects + whether the session is still valid. |
+| `zibby_list_projects` | Lists the user's Zibby projects. |
+| `zibby_list_templates` | Lists official workflow templates (browser-test-automation, code-analysis, generate-test-cases, …). |
+| `zibby_scaffold_workflow` | Scaffolds `.zibby/workflows/<name>/` from an official template. |
+| `zibby_validate_workflow` | Static-checks a local workflow (~30ms, no API). |
+| `zibby_list_workflows` | Lists workflows (local, remote, or both). |
+| `zibby_deploy_workflow` | Deploys a local workflow to a project. |
+| `zibby_trigger_workflow` | Triggers a deployed workflow by UUID. Returns `jobId`. |
+| `zibby_workflow_logs` | Fetches the latest N log lines from a run (one-shot). |
+| `zibby_run_workflow_local` | Runs a workflow locally one-shot for debugging — no cloud. |
+| `zibby_download_workflow` | Downloads a deployed workflow back to local. Requires explicit user confirmation. |
+
+Destructive ops (`workflow delete`, `env set/unset`, `schedule set/clear`, `creds`) are **intentionally not exposed**. Manage those from the `zibby` CLI directly.
+
+## Prerequisites
+
+- **Node.js ≥ 18** on the user's machine
+- A Zibby account (sign up at [zibby.dev](https://zibby.dev))
+
+That's it. No global `npm install` needed — `npx` handles the bundle (which includes `@zibby/cli`).
+
+## Install (per agent)
+
+### Claude Code
+
+`~/.claude/settings.json` (or `~/.claude.json` on older versions):
+
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "command": "npx",
+      "args": ["-y", "@zibby/mcp-cli"]
+    }
+  }
+}
+```
+
+Then in Claude Code: "log in to Zibby" → it'll call `zibby_login` and open the browser.
+
+### Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "command": "npx",
+      "args": ["-y", "@zibby/mcp-cli"]
+    }
+  }
+}
+```
+
+### OpenAI Codex CLI
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.zibby]
+command = "npx"
+args = ["-y", "@zibby/mcp-cli"]
+```
+
+### Gemini CLI
+
+`~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "command": "npx",
+      "args": ["-y", "@zibby/mcp-cli"]
+    }
+  }
+}
+```
+
+### Claude Desktop (macOS)
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "command": "npx",
+      "args": ["-y", "@zibby/mcp-cli"]
+    }
+  }
+}
+```
+
+### Windows note
+
+If your agent on Windows can't find `npx`, wrap it in `cmd /c`:
+
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@zibby/mcp-cli"]
+    }
+  }
+}
+```
+
+## Authentication
+
+Two-stage by design (mirrors how the `zibby` CLI works):
+
+1. **Session token** (`zibby_login`) — device-code OAuth via browser. Identifies the user.
+2. **Per-project API tokens** — fetched by `zibby_login` / `zibby_list_projects` and cached locally. The MCP server picks the right token automatically when you call a project-scoped tool like `zibby_deploy_workflow`.
+
+All credentials live in `~/.zibby/config.json` (mode `0600`). The MCP server reads/writes that file directly — no separate credential store.
+
+The user's password never touches the MCP server: login is OAuth in the browser, and only the resulting session token comes back to the local file.
+
+## How a typical agent chat flow looks
+
+```
+User:  Deploy the browser-test template to my "playhouse" project.
+Agent: → zibby_list_projects             (finds projectId)
+       → zibby_scaffold_workflow         (browser-test-automation → .zibby/workflows/playhouse-tests/)
+       → zibby_validate_workflow          (catches obvious errors)
+       → zibby_deploy_workflow           (returns UUID + version)
+       → "Deployed v1 of playhouse-tests. UUID 988…"
+
+User:  Run it against staging.zibby.dev.
+Agent: → zibby_trigger_workflow          (input: { url: "https://staging.zibby.dev" })
+       → returns { jobId: "abc-123" }
+       → zibby_workflow_logs              (lines: 200, jobId: "abc-123")
+       → "Run completed. Found 0 errors."
+```
+
+## Troubleshooting
+
+| Problem | Likely cause |
+|---|---|
+| `Not logged in` on every call | `~/.zibby/config.json` missing or corrupted. Call `zibby_login`. |
+| `No API token cached for project` | Project list out of date. Call `zibby_list_projects` to refresh. |
+| Tool returns text with ANSI color codes | Some agent UIs don't strip them. We set `NO_COLOR=1` already; if you still see them, your agent's display is the issue. |
+| `npx -y` hangs on first install | First-time download. Subsequent invocations are cached. |
+| Tool times out on long deploys | The wrapped CLI command exceeded 10 min. Re-run from a terminal with `zibby workflow deploy` to see live output. |
+
+## Security model
+
+- **No shell interpolation** — all CLI invocations use `execFile` with argv arrays
+- **Minimum env passthrough** — only `HOME`, `USER`, `PATH`, and the project-scoped `ZIBBY_API_KEY` are forwarded to the child CLI process
+- **Destructive ops excluded** — see "What you get" above
+- **`zibby_download_workflow` requires `confirm: true`** — agent must explicitly opt in after confirming dest path with the user
+- **API tokens never returned to the agent** — they live in `~/.zibby/config.json` only
+
+## Versioning
+
+`@zibby/mcp-cli` pins a specific `@zibby/cli` version in its `dependencies`. Upgrading the MCP package upgrades the bundled CLI in lockstep. To check which CLI version is bundled:
+
+```bash
+npx -y @zibby/mcp-cli --version          # MCP server version
+node -p "require('@zibby/cli/package.json').version"   # bundled CLI version (after first npx run)
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,505 @@
+#!/usr/bin/env node
+/* global process */
+/**
+ * Zibby CLI MCP Server
+ *
+ * Exposes the @zibby/cli surface (workflow deploy / run / trigger / logs / …)
+ * as MCP tools so AI agents (Claude Code, Cursor, OpenAI Codex, Gemini, …)
+ * can drive Zibby workflows from chat.
+ *
+ * Distribution model: stdio MCP server published to npm. Spawned by the
+ * agent's host process via `npx -y @zibby/mcp-cli`. The agent's stdin/stdout
+ * is the MCP transport. All HTTP API traffic goes user-machine → api-prod.zibby.app,
+ * authenticated with a project-scoped API token read from ~/.zibby/config.json
+ * (the same file `zibby login` writes).
+ *
+ * Implementation: shell-out to the bundled @zibby/cli binary. We resolve the
+ * CLI through our own node_modules so the version is pinned via package.json
+ * (independent of any global PATH install).
+ *
+ * Auth: login is implemented in-process via the device-code OAuth flow
+ * against api-prod.zibby.app/cli/login/{initiate,poll}. We mirror the file
+ * format that @zibby/cli's saveSessionToken / saveProjects write, so the
+ * shelled-out CLI commands pick up credentials automatically.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+
+const exec = promisify(execFile);
+const require = createRequire(import.meta.url);
+
+// ── Constants ───────────────────────────────────────────────────────────
+
+// Pinned via our package.json's @zibby/cli dependency. Using
+// require.resolve so we always pick the CLI in our own node_modules,
+// not whichever version a user happens to have installed globally.
+const ZIBBY_BIN = require.resolve('@zibby/cli/bin/zibby.js');
+
+// Mirrors @zibby/cli's config storage. We read/write the same file so the
+// CLI commands we shell out to pick up our login state, and vice versa.
+const CONFIG_DIR  = join(homedir(), '.zibby');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+const API_BASE = process.env.ZIBBY_API_URL || 'https://api-prod.zibby.app';
+
+// ── Config file helpers (matches @zibby/cli/src/config/config.js shape) ─
+
+function loadConfig() {
+  if (!existsSync(CONFIG_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8')) || {};
+  } catch {
+    return {};
+  }
+}
+
+function saveConfig(cfg) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+}
+
+function getSessionToken() { return loadConfig().sessionToken || null; }
+function getUserInfo()     { return loadConfig().user         || null; }
+function getProjects()     { return loadConfig().projects     || []; }
+
+function clearSession() {
+  const cfg = loadConfig();
+  delete cfg.sessionToken;
+  delete cfg.user;
+  delete cfg.projects;
+  delete cfg.proxyUrl;
+  delete cfg.mem0ProxyUrl;
+  saveConfig(cfg);
+}
+
+/**
+ * Look up a project's per-project API token (project-scoped, what workflow
+ * commands need). Returns null when the project isn't in the saved list
+ * (caller should prompt the user to log in / re-run zibby_list_projects).
+ */
+function getProjectApiToken(projectId) {
+  return getProjects().find((p) => p.projectId === projectId)?.apiToken || null;
+}
+
+// ── Shell helpers ───────────────────────────────────────────────────────
+
+/**
+ * Run the bundled @zibby/cli with the given argv. Uses execFile so there's
+ * no shell interpretation — every value in args is a literal argv entry.
+ * Returns { code, stdout, stderr }. Never throws (we want to surface the
+ * exit code + stderr to the agent rather than crashing the MCP server).
+ */
+async function runCli(args, opts = {}) {
+  try {
+    const { stdout, stderr } = await exec(process.execPath, [ZIBBY_BIN, ...args], {
+      // Inherit HOME so the CLI finds ~/.zibby/config.json, and PATH so
+      // sub-tools (npm, node, dolt) are reachable. Anything else stays
+      // out — we don't want stray env vars leaking into the deploy.
+      env: {
+        HOME: process.env.HOME,
+        USER: process.env.USER,
+        PATH: process.env.PATH,
+        TERM: 'dumb',                                  // suppress ora spinners
+        NO_COLOR: '1',                                 // strip chalk colors
+        DOTENV_CONFIG_QUIET: 'true',
+        ...(opts.extraEnv || {}),
+      },
+      cwd: opts.cwd || process.cwd(),
+      timeout: opts.timeout || 600_000,                // 10 min default
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    return { code: 0, stdout, stderr };
+  } catch (err) {
+    // execFile rejects with { code, stdout, stderr } on non-zero exit.
+    return {
+      code: typeof err.code === 'number' ? err.code : 1,
+      stdout: err.stdout || '',
+      stderr: err.stderr || String(err.message || err),
+    };
+  }
+}
+
+/** Format a runCli result as an MCP tool response. */
+function cliResult(r) {
+  const body =
+    r.code === 0
+      ? r.stdout || '(command produced no output)'
+      : `Command failed (exit ${r.code})\n\nSTDOUT:\n${r.stdout || '(empty)'}\n\nSTDERR:\n${r.stderr || '(empty)'}`;
+  return {
+    isError: r.code !== 0,
+    content: [{ type: 'text', text: body }],
+  };
+}
+
+/** Convert a plain JSON object into a text MCP response. */
+function jsonResult(obj) {
+  return { content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }] };
+}
+
+/** Convert a string into a text MCP response. */
+function textResult(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+/**
+ * Cross-platform "open URL in the user's default browser". Detached so
+ * the MCP server doesn't block waiting for the browser process. Safe
+ * (no shell interpolation).
+ */
+function openBrowser(url) {
+  try {
+    const platform = process.platform;
+    let cmd; let args;
+    if (platform === 'darwin')      { cmd = 'open'; args = [url]; }
+    else if (platform === 'win32')  { cmd = 'cmd';  args = ['/c', 'start', '', url]; }
+    else                            { cmd = 'xdg-open'; args = [url]; }
+    spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+    return true;
+  } catch { return false; }
+}
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+// ── MCP server ─────────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: 'zibby-cli',
+  version: '0.1.0',
+});
+
+// ── 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).
+// Writes session + projects to ~/.zibby/config.json on success.
+server.tool(
+  'zibby_login',
+  'Log in to Zibby. Opens the user\'s browser to the Zibby login page. The user authorizes in the browser; this tool polls until the auth completes and saves the session to ~/.zibby/config.json. Subsequent tool calls in the same MCP session use the saved credentials automatically.',
+  {},
+  async () => {
+    // If already logged in, short-circuit — agent shouldn't trigger a
+    // fresh login dance every time the session is good.
+    const existing = getSessionToken();
+    if (existing) {
+      const user = getUserInfo();
+      return textResult(`Already logged in as ${user?.email || 'unknown'}. Call zibby_logout first if you want to switch accounts.`);
+    }
+
+    // 1. Request device code.
+    const initRes = await fetch(`${API_BASE}/cli/login/initiate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+    });
+    if (!initRes.ok) {
+      const errText = await initRes.text().catch(() => '');
+      return { isError: true, content: [{ type: 'text', text: `Failed to initiate login: ${initRes.status} ${errText}` }] };
+    }
+    const init = await initRes.json();
+    const { deviceCode, verificationUrl, expiresIn, interval } = init;
+
+    // 2. Open browser. Don't fail if the OS can't open one — agent surfaces
+    //    the URL so the user can paste it manually.
+    const opened = openBrowser(verificationUrl);
+
+    // 3. Poll until authorized / denied / timeout. expiresIn is in seconds.
+    const pollIntervalMs = (interval || 3) * 1000;
+    const deadline = Date.now() + expiresIn * 1000;
+    while (Date.now() < deadline) {
+      await sleep(pollIntervalMs);
+      const pollRes = await fetch(`${API_BASE}/cli/login/poll`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ deviceCode }),
+      });
+      if (pollRes.status === 202) continue; // still waiting
+      if (!pollRes.ok) {
+        const errText = await pollRes.text().catch(() => '');
+        return { isError: true, content: [{ type: 'text', text: `Login poll failed: ${pollRes.status} ${errText}` }] };
+      }
+      const result = await pollRes.json();
+      if (result.status === 'denied') {
+        return { isError: true, content: [{ type: 'text', text: 'User denied the login authorization in the browser.' }] };
+      }
+      if (result.status === 'authorized') {
+        // Fetch projects to seed the saved list (workflow ops need per-
+        // project apiTokens). Best-effort — if it fails we still save the
+        // session token and the user can rerun zibby_list_projects.
+        let projects = [];
+        try {
+          const pRes = await fetch(`${API_BASE}/projects`, {
+            headers: { Authorization: `Bearer ${result.token}` },
+          });
+          if (pRes.ok) {
+            const data = await pRes.json();
+            projects = (data.projects || []).map((p) => ({
+              name: p.name,
+              projectId: p.projectId,
+              apiToken: p.apiToken,
+            }));
+          }
+        } catch { /* non-fatal */ }
+        saveConfig({
+          ...loadConfig(),
+          sessionToken: result.token,
+          user: result.user,
+          proxyUrl: result.proxyUrl,
+          mem0ProxyUrl: result.mem0ProxyUrl,
+          projects,
+        });
+        return textResult(
+          `Logged in as ${result.user?.email || 'unknown'} (${projects.length} project${projects.length !== 1 ? 's' : ''} cached).${opened ? '' : `\n\nBrowser could not open automatically. Verification URL was: ${verificationUrl}`}`
+        );
+      }
+    }
+    return { isError: true, content: [{ type: 'text', text: 'Login timed out before the user completed authorization. Call zibby_login again to retry.' }] };
+  }
+);
+
+// ── Tool: logout ────────────────────────────────────────────────────────
+server.tool(
+  'zibby_logout',
+  'Clear the saved session and project tokens from ~/.zibby/config.json. After logout, zibby_login is required before any other tool call.',
+  {},
+  async () => {
+    if (!getSessionToken()) return textResult('Not logged in.');
+    const email = getUserInfo()?.email;
+    clearSession();
+    return textResult(`Logged out${email ? ` (${email})` : ''}.`);
+  }
+);
+
+// ── Tool: status ────────────────────────────────────────────────────────
+server.tool(
+  'zibby_status',
+  'Show current login status: who is logged in, how many projects are cached locally, and whether the session token is still valid against the Zibby API.',
+  {},
+  async () => {
+    const token = getSessionToken();
+    if (!token) return textResult('Not logged in. Call zibby_login.');
+    const user = getUserInfo();
+    const projects = getProjects();
+    // Validate token by hitting a cheap authed endpoint.
+    let apiOk = null;
+    try {
+      const res = await fetch(`${API_BASE}/projects`, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      apiOk = res.ok;
+    } catch { apiOk = false; }
+    return jsonResult({
+      loggedIn: true,
+      user: { email: user?.email, name: user?.name },
+      cachedProjects: projects.length,
+      tokenValid: apiOk,
+    });
+  }
+);
+
+// ── Tool: list projects ─────────────────────────────────────────────────
+server.tool(
+  'zibby_list_projects',
+  'List the Zibby projects the logged-in user has access to. Returns {projectId, name} pairs. Use the projectId in subsequent workflow tool calls.',
+  {},
+  async () => {
+    const token = getSessionToken();
+    if (!token) return { isError: true, content: [{ type: 'text', text: 'Not logged in. Call zibby_login first.' }] };
+    // Pull fresh from API and refresh the local cache while we're at it.
+    const res = await fetch(`${API_BASE}/projects`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+      return { isError: true, content: [{ type: 'text', text: `Failed to list projects: ${res.status}` }] };
+    }
+    const data = await res.json();
+    const projects = (data.projects || []).map((p) => ({
+      projectId: p.projectId,
+      name: p.name,
+      apiToken: p.apiToken,                              // saved locally for shell-out, not surfaced below
+    }));
+    saveConfig({ ...loadConfig(), projects });
+    return jsonResult(projects.map(({ projectId, name }) => ({ projectId, name })));
+  }
+);
+
+// ── Tool: list templates ────────────────────────────────────────────────
+server.tool(
+  '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.',
+  {},
+  async () => cliResult(await runCli(['template', 'list']))
+);
+
+// ── Tool: scaffold workflow ─────────────────────────────────────────────
+server.tool(
+  '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. Use zibby_list_templates first to see options.',
+  {
+    name: z.string().min(1).describe('Local workflow 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'),
+  },
+  async ({ name, template, skipInstall }) => {
+    const args = ['g', 'workflow', name, '-t', template, '--no-agent-helpers'];
+    if (skipInstall) args.push('--skip-install');
+    return cliResult(await runCli(args));
+  }
+);
+
+// ── Tool: validate workflow ─────────────────────────────────────────────
+server.tool(
+  'zibby_validate_workflow',
+  'Static-check a local workflow (.zibby/workflows/<name>/): graph topology, state schema, skill references. Fast (~30ms) — runs entirely locally, no API call. Run this before deploy to catch obvious errors.',
+  {
+    name: z.string().min(1).describe('Workflow folder name under .zibby/workflows/'),
+  },
+  async ({ name }) => cliResult(await runCli(['workflow', 'validate', name]))
+);
+
+// ── Tool: list workflows ────────────────────────────────────────────────
+server.tool(
+  'zibby_list_workflows',
+  'List workflows. Defaults to interleaving local (.zibby/workflows/) and remote (deployed to a project). Pass projectId to filter remote to a specific project.',
+  {
+    projectId: z.string().optional().describe('Optional — limit remote results to this project'),
+    scope: z.enum(['all', 'local', 'remote']).optional().default('all')
+      .describe('all = local + remote (default), local = only local files, remote = only deployed'),
+  },
+  async ({ projectId, scope }) => {
+    const args = ['workflow', 'list'];
+    if (scope === 'local')  args.push('--local-only');
+    if (scope === 'remote') args.push('--remote-only');
+    if (projectId)          args.push('--project', projectId);
+    const apiKey = projectId ? getProjectApiToken(projectId) : null;
+    return cliResult(await runCli(args, {
+      extraEnv: apiKey ? { ZIBBY_API_KEY: apiKey } : {},
+    }));
+  }
+);
+
+// ── Tool: deploy workflow ───────────────────────────────────────────────
+server.tool(
+  'zibby_deploy_workflow',
+  'Deploy a local workflow (.zibby/workflows/<name>/) to Zibby Cloud under the given project. Returns the workflow UUID + version on success. Use zibby_validate_workflow first to catch errors fast.',
+  {
+    name: z.string().min(1).describe('Local workflow folder name'),
+    projectId: z.string().min(1).describe('Project to deploy under (see zibby_list_projects)'),
+    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'),
+  },
+  async ({ name, projectId, force, warm }) => {
+    const apiKey = getProjectApiToken(projectId);
+    if (!apiKey) {
+      return { isError: true, content: [{ type: 'text', text: `No API token cached for project ${projectId}. Run zibby_list_projects to refresh, or zibby_login if not logged in.` }] };
+    }
+    const args = ['workflow', 'deploy', name, '--project', projectId];
+    if (force) args.push('--force');
+    if (warm)  args.push('--warm', String(warm));
+    return cliResult(await runCli(args, { extraEnv: { ZIBBY_API_KEY: apiKey } }));
+  }
+);
+
+// ── Tool: trigger workflow ──────────────────────────────────────────────
+server.tool(
+  'zibby_trigger_workflow',
+  'Trigger an already-deployed workflow by UUID. Pass input params as a JSON object. Returns the jobId — pass to zibby_workflow_logs to read execution output.',
+  {
+    uuid: z.string().min(1).describe('Workflow UUID (from zibby_list_workflows or zibby_deploy_workflow output)'),
+    projectId: z.string().min(1).describe('Project the workflow lives under'),
+    input: z.record(z.string(), z.any()).optional().default({})
+      .describe('Input params for the workflow — shape depends on the workflow\'s state schema'),
+    idempotencyKey: z.string().optional()
+      .describe('Optional idempotency key — same key + same input = same job, no duplicate execution'),
+  },
+  async ({ uuid, projectId, input, idempotencyKey }) => {
+    const apiKey = getProjectApiToken(projectId);
+    if (!apiKey) {
+      return { isError: true, content: [{ type: 'text', text: `No API token cached for project ${projectId}. Run zibby_list_projects.` }] };
+    }
+    const args = ['workflow', 'trigger', uuid, '--project', projectId, '--input', JSON.stringify(input || {})];
+    if (idempotencyKey) args.push('--idempotency-key', idempotencyKey);
+    return cliResult(await runCli(args, { extraEnv: { ZIBBY_API_KEY: apiKey } }));
+  }
+);
+
+// ── Tool: workflow logs ─────────────────────────────────────────────────
+server.tool(
+  'zibby_workflow_logs',
+  'Fetch the most recent N log lines from a workflow execution. One-shot — does NOT stream. For long-running runs, call repeatedly. Either jobId OR workflowName is required.',
+  {
+    projectId: z.string().min(1).describe('Project the run lives under'),
+    jobId: z.string().optional().describe('Specific job to fetch logs for (returned by zibby_trigger_workflow)'),
+    workflowName: z.string().optional().describe('Alternative to jobId — fetches the latest run for this workflow name'),
+    lines: z.number().int().min(1).max(5000).optional().default(500)
+      .describe('Max log lines to fetch'),
+  },
+  async ({ projectId, jobId, workflowName, lines }) => {
+    if (!jobId && !workflowName) {
+      return { isError: true, content: [{ type: 'text', text: 'Either jobId or workflowName is required.' }] };
+    }
+    const apiKey = getProjectApiToken(projectId);
+    if (!apiKey) {
+      return { isError: true, content: [{ type: 'text', text: `No API token cached for project ${projectId}. Run zibby_list_projects.` }] };
+    }
+    const args = ['workflow', 'logs'];
+    if (jobId) args.push(jobId);
+    args.push('--project', projectId, '--lines', String(lines));
+    if (workflowName) args.push('--workflow', workflowName);
+    return cliResult(await runCli(args, { extraEnv: { ZIBBY_API_KEY: apiKey } }));
+  }
+);
+
+// ── Tool: run workflow locally ──────────────────────────────────────────
+server.tool(
+  '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.',
+  {
+    name: z.string().min(1).describe('Local workflow folder name'),
+    input: z.record(z.string(), z.any()).optional().default({})
+      .describe('Input params (same shape as zibby_trigger_workflow)'),
+  },
+  async ({ name, input }) => {
+    const args = ['workflow', 'run', name, '--input', JSON.stringify(input || {})];
+    return cliResult(await runCli(args, { timeout: 30 * 60 * 1000 }));   // local runs can be longer
+  }
+);
+
+// ── Tool: download workflow ─────────────────────────────────────────────
+// 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(
+  '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.',
+  {
+    uuid: z.string().min(1).describe('Workflow UUID to download'),
+    projectId: z.string().min(1).describe('Project the workflow 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)
+      .describe('Overwrite without prompting + bypass uuid-mismatch guard (set only after the user explicitly authorizes overwriting existing files)'),
+  },
+  async ({ uuid, projectId, dest, force }) => {
+    const apiKey = getProjectApiToken(projectId);
+    if (!apiKey) {
+      return { isError: true, content: [{ type: 'text', text: `No API token cached for project ${projectId}. Run zibby_list_projects.` }] };
+    }
+    const args = ['workflow', 'download', uuid, '--dest', dest];
+    if (force) args.push('--force');
+    return cliResult(await runCli(args, { extraEnv: { ZIBBY_API_KEY: apiKey } }));
+  }
+);
+
+// ── Connect ─────────────────────────────────────────────────────────────
+
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@zibby/mcp-cli",
+  "version": "0.1.0",
+  "description": "Zibby CLI MCP Server — expose Zibby workflow deploy/run/debug to AI agents (Claude, Cursor, Codex, Gemini)",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "mcp-cli-zibby": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix ."
+  },
+  "keywords": [
+    "mcp",
+    "zibby",
+    "workflow",
+    "agent",
+    "deploy",
+    "playwright"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ZibbyHQ/zibby-agent"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@zibby/cli": "^0.4.30",
+    "zod": "^4.3.6"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "author": "Zibby",
+  "homepage": "https://zibby.dev"
+}