@zibby/mcp-cli 0.2.0 → 0.3.1

package/README.md

@@ -1,28 +1,26 @@
 # @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.
+Zibby's **local-essential** CLI as a Model Context Protocol server. Lets any MCP-aware AI agent — Claude Code, Cursor, OpenAI Codex, Gemini CLI, Continue, Cline, Aider, Goose — log in to Zibby, scaffold/validate/run workflows on local disk, and deploy or download workflows from a chat session.
+
+> **Looking for `list_projects`, `trigger_workflow`, `workflow_logs`, marketplace apps, ticket/integration browsing, etc.?** Those tools moved to the **Zibby Remote MCP** at `https://api-prod.zibby.app/mcp` (HTTP transport, 71 tools, no install). Hook your agent up to both — this stdio package for the things that touch your filesystem, the remote MCP for everything else. The remote MCP picks up server-side changes without you having to re-publish or upgrade npm.
 
 ## What you get
 
-13 MCP tools wrapping the same things `@zibby/cli` does:
+9 MCP tools, every one of them genuinely local:
 
-| Tool | What it does |
+| Tool | Why it has to be local |
 |---|---|
-| `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.
+| `zibby_login` | Opens the user's browser (device-code OAuth) and writes the session token + cached project API tokens to `~/.zibby/config.json`. |
+| `zibby_logout` | Clears the saved session from `~/.zibby/config.json`. |
+| `zibby_status` | Reads `~/.zibby/config.json` to show which login is active on **this machine**. (The remote MCP also has a `zibby_status`, but only this one sees the local file.) |
+| `zibby_list_templates` | Lists workflow templates bundled with the local `@zibby/cli` — no network. |
+| `zibby_scaffold_workflow` | Writes `.zibby/workflows/<name>/` files to local disk. |
+| `zibby_validate_workflow` | Reads local workflow files + runs the validator (~30ms, no API). |
+| `zibby_run_workflow_local` | Spawns a local node process to run a workflow against local data. |
+| `zibby_deploy_workflow` | Bundles the local workflow folder + dependencies, then uploads. Bundling is local. |
+| `zibby_download_workflow` | Downloads a deployed workflow back to local disk. 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, or via the Zibby Remote MCP where they exist.
 
 ## Prerequisites
 
@@ -43,6 +41,10 @@ That's it. No global `npm install` needed — `npx` handles the bundle (which in
     "zibby": {
       "command": "npx",
       "args": ["-y", "@zibby/mcp-cli"]
+    },
+    "zibby-remote": {
+      "type": "http",
+      "url": "https://api-prod.zibby.app/mcp"
     }
   }
 }
@@ -125,7 +127,9 @@ If your agent on Windows can't find `npx`, wrap it in `cmd /c`:
 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`.
+2. **Per-project API tokens** — fetched by `zibby_login` and cached locally in `~/.zibby/config.json`. The MCP server picks the right token automatically when you call a project-scoped tool like `zibby_deploy_workflow` or `zibby_download_workflow`.
+
+If you grant your account access to a new project, re-run `zibby_login` (or `zibby_logout` + `zibby_login`) to refresh the cached project list.
 
 All credentials live in `~/.zibby/config.json` (mode `0600`). The MCP server reads/writes that file directly — no separate credential store.
 
@@ -135,16 +139,16 @@ The user's password never touches the MCP server: login is OAuth in the browser,
 
 ```
 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)
+Agent: → (via Remote MCP) zibby_list_projects   (finds projectId)
+       → zibby_scaffold_workflow                (browser-test-automation → .zibby/workflows/playhouse-tests/)
+       → zibby_validate_workflow                (catches obvious errors locally)
+       → zibby_deploy_workflow                  (bundles local folder, uploads, 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" })
+Agent: → (via Remote MCP) zibby_trigger_workflow    (input: { url: "https://staging.zibby.dev" })
        → returns { jobId: "abc-123" }
-       → zibby_workflow_logs              (lines: 200, jobId: "abc-123")
+       → (via Remote MCP) zibby_get_workflow_job_logs   (jobId: "abc-123")
        → "Run completed. Found 0 errors."
 ```
 
@@ -153,10 +157,11 @@ Agent: → zibby_trigger_workflow          (input: { url: "https://staging.zibby
 | 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. |
+| `No API token cached for project` | Project list out of date. Re-run `zibby_login` (or `zibby_logout` + `zibby_login`) 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. |
+| Wanting `list_projects` / `trigger_workflow` / `workflow_logs` | Those live in the Zibby Remote MCP. Add it as a second `mcpServers` entry (`https://api-prod.zibby.app/mcp`). |
 
 ## Security model
 

package/index.js

@@ -1,21 +1,29 @@
 #!/usr/bin/env node
 /* global process */
 /**
- * Zibby CLI MCP Server
+ * Zibby CLI MCP Server (local-essential tools only)
  *
- * 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.
+ * This stdio MCP server exposes the @zibby/cli surface that genuinely needs
+ * to run on the user's local machine — login (OAuth browser flow), local
+ * workflow scaffolding/validate/run, deploy (bundles local files), and
+ * download (writes files locally).
+ *
+ * Every pure-API tool (list projects, list/trigger workflows, fetch logs,
+ * marketplace apps, etc.) is served by the Zibby Remote MCP at
+ * https://api-prod.zibby.app/mcp — point your agent there for those. The
+ * remote MCP picks up server-side changes without an npm publish/upgrade,
+ * so we deliberately do NOT duplicate that surface here.
  *
  * 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).
+ * is the MCP transport. All HTTP traffic for the OAuth flow goes
+ * user-machine → api-prod.zibby.app. Project-scoped API tokens are cached
+ * in ~/.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).
+ * Implementation: shell-out to the bundled @zibby/cli binary for the local
+ * file-touching commands. 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
@@ -38,10 +46,19 @@ 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');
+// Resolve @zibby/cli's bin path via ITS package.json "bin" field (not a
+// hard-coded subpath). Dev workspace has bin/zibby.js at the top level;
+// the npm-published package ships dist/bin/zibby.js — so the literal
+// `@zibby/cli/bin/zibby.js` subpath only works in dev and throws
+// MODULE_NOT_FOUND under npx. Reading package.json + dirname + bin entry
+// works in both layouts.
+const ZIBBY_BIN = (() => {
+  const pkgPath = require.resolve('@zibby/cli/package.json');
+  const pkg = require(pkgPath);
+  const binEntry = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.zibby || pkg.bin?.zb;
+  if (!binEntry) throw new Error('@zibby/cli package.json: missing "bin" field');
+  return join(pkgPath.replace(/[/\\]package\.json$/, ''), binEntry);
+})();
 
 // 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.
@@ -83,7 +100,8 @@ function clearSession() {
 /**
  * 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).
+ * (caller should prompt the user to re-run zibby_login to refresh the
+ * cached project list).
  */
 function getProjectApiToken(projectId) {
   return getProjects().find((p) => p.projectId === projectId)?.apiToken || null;
@@ -172,7 +190,7 @@ function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
 
 const server = new McpServer({
   name: 'zibby-cli',
-  version: '0.1.0',
+  version: '0.3.0',
 });
 
 // ── Tool: login ─────────────────────────────────────────────────────────
@@ -181,7 +199,7 @@ const server = new McpServer({
 // 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.',
+  '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 + project API tokens to ~/.zibby/config.json. Subsequent local tool calls (deploy, download) use the saved credentials automatically. Re-run to refresh the cached project list after granting access to a new project.',
   {},
   async () => {
     // If already logged in, short-circuit — agent shouldn't trigger a
@@ -230,7 +248,7 @@ server.tool(
       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.
+        // session token; the user can re-run zibby_login to refresh.
         let projects = [];
         try {
           const pRes = await fetch(`${API_BASE}/projects`, {
@@ -276,9 +294,13 @@ server.tool(
 );
 
 // ── Tool: status ────────────────────────────────────────────────────────
+// Local-only inspector for which session is active on this machine.
+// (There is also a remote zibby_status served by the Zibby Remote MCP,
+// but only this one can see the local file state — i.e. which login the
+// shelled-out CLI commands will use.)
 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.',
+  'Show the local Zibby session info from ~/.zibby/config.json: who is logged in, how many projects are cached locally for shell-out commands (deploy/download), and whether the session token is still valid against the Zibby API. Use this to confirm WHICH account/session the local tools (deploy/download/scaffold) will use.',
   {},
   async () => {
     const token = getSessionToken();
@@ -302,44 +324,21 @@ server.tool(
   }
 );
 
-// ── 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 ────────────────────────────────────────────────
+// Local because @zibby/cli reads the bundled template manifest from its
+// own node_modules (no network call).
 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.',
+  '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.',
   {},
   async () => cliResult(await runCli(['template', 'list']))
 );
 
 // ── Tool: scaffold workflow ─────────────────────────────────────────────
+// Writes files to .zibby/workflows/<name>/ in the user's cwd.
 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.',
+  '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.',
   {
     name: z.string().min(1).describe('Local workflow folder name (kebab-case)'),
     template: z.enum(['browser-test-automation', 'code-analysis', 'generate-test-cases'])
@@ -355,43 +354,26 @@ server.tool(
 );
 
 // ── Tool: validate workflow ─────────────────────────────────────────────
+// Reads local workflow files + spawns the local validator.
 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.',
+  '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.',
   {
     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 ───────────────────────────────────────────────
+// 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(
   '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.',
+  '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.',
   {
     name: z.string().min(1).describe('Local workflow folder name'),
-    projectId: z.string().min(1).describe('Project to deploy under (see zibby_list_projects)'),
+    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()
@@ -400,7 +382,7 @@ server.tool(
   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.` }] };
+      return { isError: true, content: [{ type: 'text', text: `No API token cached for project ${projectId}. Run zibby_login (or zibby_logout + zibby_login) to refresh the local project list.` }] };
     }
     const args = ['workflow', 'deploy', name, '--project', projectId];
     if (force) args.push('--force');
@@ -409,64 +391,15 @@ server.tool(
   }
 );
 
-// ── 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 ──────────────────────────────────────────
+// Spawns a local node process to run the workflow against local files.
 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)'),
+      .describe('Input params (JSON object passed to the workflow\'s entry node)'),
   },
   async ({ name, input }) => {
     const args = ['workflow', 'run', name, '--input', JSON.stringify(input || {})];
@@ -492,7 +425,7 @@ server.tool(
   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.` }] };
+      return { isError: true, content: [{ type: 'text', text: `No API token cached for project ${projectId}. Run zibby_login (or zibby_logout + zibby_login) to refresh the local project list.` }] };
     }
     const args = ['workflow', 'download', uuid, '--dest', dest];
     if (force) args.push('--force');
@@ -500,243 +433,6 @@ server.tool(
   }
 );
 
-// ─────────────────────────────────────────────────────────────────────────
-// agent-ops integration tools
-//
-// These wrap the (currently in development) Zibby control-plane endpoints
-// for deploying / managing hosted app instances. Each instance runs the
-// open-source agent-ops daemon (github.com/ZibbyHQ/agent-ops) as a sidecar
-// — the daemon's own MCP server is what the user's local agent talks to
-// for per-instance operations. The tools here cover the cross-instance
-// surface that lives in Zibby's control plane.
-//
-// Backend endpoints these wrap are still being built; the MCP tools are
-// shipped now so client-side wiring lands first. Each tool will surface a
-// clear "control plane not yet deployed" error until the backend ships.
-
-const APPS_API_BASE = `${API_BASE}/apps`;
-
-async function callAppsAPI(path, opts = {}) {
-  const token = getSessionToken();
-  if (!token) return { error: 'not logged in', status: 401 };
-  const url = `${APPS_API_BASE}${path}`;
-  const init = {
-    method: opts.method || 'GET',
-    headers: {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${token}`,
-      ...(opts.headers || {}),
-    },
-  };
-  if (opts.body) init.body = JSON.stringify(opts.body);
-  try {
-    const res = await fetch(url, init);
-    const text = await res.text().catch(() => '');
-    let body = null;
-    try { body = text ? JSON.parse(text) : null; } catch { body = text; }
-    return { status: res.status, body, ok: res.ok };
-  } catch (err) {
-    return { error: err.message, status: 0 };
-  }
-}
-
-// ── Tool: deploy app ────────────────────────────────────────────────────
-server.tool(
-  'zibby_deploy_app',
-  'Deploy a marketplace app (n8n, Grafana, Open WebUI, …) into a Zibby project. ' +
-    'Returns 202 + the instanceId + the public URL. Once provisioning finishes the URL serves the app; ' +
-    'use the zibby_app_* tools to interact with its ops agent. No second MCP install needed — every ' +
-    'app tool proxies through the Zibby backend.',
-  {
-    appType: z.string().min(1).describe('Catalog id (use zibby_list_app_catalog to see options, e.g. "n8n")'),
-    projectId: z.string().min(1).describe('Zibby project to deploy under'),
-    name: z.string().optional().describe('Optional display name for the instance'),
-  },
-  async ({ appType, projectId, name }) => {
-    const res = await callAppsAPI('/deploy', {
-      method: 'POST',
-      body: { appType, projectId, name },
-    });
-    if (res.error) return { isError: true, content: [{ type: 'text', text: `Network: ${res.error}` }] };
-    if (!res.ok) {
-      const detail = typeof res.body === 'string' ? res.body : JSON.stringify(res.body || {});
-      return { isError: true, content: [{ type: 'text', text: `Deploy failed (${res.status}): ${detail}` }] };
-    }
-    return jsonResult(res.body);
-  }
-);
-
-// ── Tool: list marketplace catalog ──────────────────────────────────────
-server.tool(
-  'zibby_list_app_catalog',
-  'List every app available in the Zibby marketplace. Returns tile metadata (appType, displayName, ' +
-    'tagline, category, version, ratingAvg, installCount). Public — no Zibby login required.',
-  {},
-  async () => {
-    const res = await callAppsAPI('/catalog');
-    if (res.error) return { isError: true, content: [{ type: 'text', text: `Network: ${res.error}` }] };
-    if (!res.ok) return { isError: true, content: [{ type: 'text', text: `Catalog failed (${res.status})` }] };
-    return jsonResult(res.body);
-  }
-);
-
-// ── Tool: list apps ──────────────────────────────────────────────────────
-server.tool(
-  'zibby_list_apps',
-  'List hosted app instances in a project. Returns each instance\'s id, template, status, and MCP endpoint URL.',
-  {
-    projectId: z.string().min(1).describe('Zibby project to scope to'),
-  },
-  async ({ projectId }) => {
-    const res = await callAppsAPI(`?projectId=${encodeURIComponent(projectId)}`);
-    if (res.error) return { isError: true, content: [{ type: 'text', text: `Network: ${res.error}` }] };
-    if (!res.ok) return { isError: true, content: [{ type: 'text', text: `List failed (${res.status})` }] };
-    return jsonResult(res.body);
-  }
-);
-
-// ── Tool: app status ─────────────────────────────────────────────────────
-server.tool(
-  'zibby_app_status',
-  'Show detailed status of one hosted app instance: task state, sidecar version, agent-ops heartbeat, last incident.',
-  {
-    instanceId: z.string().min(1).describe('Instance id (from zibby_list_apps or zibby_deploy_app)'),
-  },
-  async ({ instanceId }) => {
-    const res = await callAppsAPI(`/${encodeURIComponent(instanceId)}`);
-    if (res.error) return { isError: true, content: [{ type: 'text', text: `Network: ${res.error}` }] };
-    if (!res.ok) return { isError: true, content: [{ type: 'text', text: `Status failed (${res.status})` }] };
-    return jsonResult(res.body);
-  }
-);
-
-// ── Tool: app logs ───────────────────────────────────────────────────────
-server.tool(
-  'zibby_app_logs',
-  'Tail the latest N log lines from one hosted app instance. Both the main app container and the agent-ops sidecar log to the same stream; pass `container` to scope.',
-  {
-    instanceId: z.string().min(1).describe('Instance id'),
-    container: z.enum(['app', 'agent-ops']).optional().describe('Which container; defaults to interleaved'),
-    lines: z.number().int().min(1).max(5000).optional().default(200).describe('How many recent lines'),
-  },
-  async ({ instanceId, container, lines }) => {
-    const qs = new URLSearchParams();
-    if (container) qs.set('container', container);
-    if (lines) qs.set('lines', String(lines));
-    const res = await callAppsAPI(`/${encodeURIComponent(instanceId)}/logs?${qs.toString()}`);
-    if (res.error) return { isError: true, content: [{ type: 'text', text: `Network: ${res.error}` }] };
-    if (!res.ok) return { isError: true, content: [{ type: 'text', text: `Logs failed (${res.status})` }] };
-    return textResult(typeof res.body === 'string' ? res.body : JSON.stringify(res.body, null, 2));
-  }
-);
-
-// ── Daemon MCP proxy ─────────────────────────────────────────────────────
-//
-// Every tool below routes through POST /apps/{id}/mcp on the Zibby
-// backend, which forwards the JSON-RPC body to the per-instance
-// agent-ops daemon using the bridgeToken stored in DDB. This means
-// users never copy a per-instance token into a local mcp.json — one
-// MCP install (@zibby/mcp-cli) covers every instance they own.
-//
-// Each tool wraps `tools/call` with the daemon's matching agent_*
-// builtin (agent_run_now, agent_set_mission, etc.). Helper below
-// keeps the JSON-RPC shape and error handling in one place.
-async function callDaemonTool(instanceId, daemonToolName, args = {}) {
-  const body = {
-    jsonrpc: '2.0',
-    id: Date.now(),
-    method: 'tools/call',
-    params: { name: daemonToolName, arguments: args },
-  };
-  const res = await callAppsAPI(`/${encodeURIComponent(instanceId)}/mcp`, {
-    method: 'POST',
-    body,
-  });
-  if (res.error) return { isError: true, content: [{ type: 'text', text: `Network: ${res.error}` }] };
-  if (!res.ok) {
-    const detail = typeof res.body === 'string' ? res.body : JSON.stringify(res.body || {});
-    return { isError: true, content: [{ type: 'text', text: `Daemon ${daemonToolName} failed (${res.status}): ${detail}` }] };
-  }
-  // The daemon returns a JSON-RPC envelope; surface `result` if present,
-  // otherwise the raw body.
-  const payload = res.body?.result ?? res.body;
-  return jsonResult(payload);
-}
-
-server.tool(
-  'zibby_app_history',
-  'Return the recent run history for an instance: each prior task invocation, exit status, and elapsed time. ' +
-    'Useful for "did the nightly health-check pass?" type questions.',
-  {
-    instanceId: z.string().min(1).describe('Instance id'),
-    limit: z.number().int().min(1).max(100).optional().default(20),
-  },
-  async ({ instanceId, limit }) => callDaemonTool(instanceId, 'agent_history', { limit })
-);
-
-server.tool(
-  'zibby_app_list_tasks',
-  'List scheduled tasks configured on an instance (hourly health checks, weekly upgrades, custom cron jobs ' +
-    'the user added). Returns name, cron expression, prompt template.',
-  {
-    instanceId: z.string().min(1).describe('Instance id'),
-  },
-  async ({ instanceId }) => callDaemonTool(instanceId, 'agent_list_tasks', {})
-);
-
-server.tool(
-  'zibby_app_run_task_now',
-  'Trigger an existing scheduled task to run immediately, out-of-cron. The task name comes from ' +
-    'zibby_app_list_tasks. The daemon kicks off the LLM run async; poll zibby_app_history to see the result.',
-  {
-    instanceId: z.string().min(1).describe('Instance id'),
-    taskName: z.string().min(1).describe('Task name from zibby_app_list_tasks'),
-  },
-  async ({ instanceId, taskName }) => callDaemonTool(instanceId, 'agent_run_now', { name: taskName })
-);
-
-server.tool(
-  'zibby_app_get_mission',
-  'Read the instance\'s persistent "mission" — a free-text instruction the agent-ops daemon ' +
-    'carries across every scheduled task run (e.g. "keep n8n on the latest LTS, never auto-major-upgrade").',
-  {
-    instanceId: z.string().min(1).describe('Instance id'),
-  },
-  async ({ instanceId }) => callDaemonTool(instanceId, 'agent_get_mission', {})
-);
-
-server.tool(
-  'zibby_app_set_mission',
-  'Set the instance\'s persistent mission. Replaces the prior value. Confirm with the user before calling — ' +
-    'changing the mission alters the daemon\'s autonomous behavior on every subsequent task.',
-  {
-    instanceId: z.string().min(1).describe('Instance id'),
-    mission: z.string().min(1).max(4000).describe('Free-text instruction the daemon carries forward'),
-  },
-  async ({ instanceId, mission }) => callDaemonTool(instanceId, 'agent_set_mission', { mission })
-);
-
-// ── Tool: destroy app (guarded) ──────────────────────────────────────────
-server.tool(
-  'zibby_destroy_app',
-  'PERMANENTLY destroy a hosted app instance: stops the Fargate task, detaches EFS, revokes the agent-ops MCP token. ' +
-    'DESTRUCTIVE — the agent MUST confirm with the user and pass confirm:true.',
-  {
-    instanceId: z.string().min(1).describe('Instance id to destroy'),
-    confirm: z.literal(true).describe('Must be true. Set only after user has explicitly authorized destroying this instance.'),
-    keepData: z.boolean().optional().default(false).describe('If true, snapshots the EFS before detach so a future redeploy can restore.'),
-  },
-  async ({ instanceId, keepData }) => {
-    const res = await callAppsAPI(`/${encodeURIComponent(instanceId)}`, {
-      method: 'DELETE',
-      body: { keepData },
-    });
-    if (res.error) return { isError: true, content: [{ type: 'text', text: `Network: ${res.error}` }] };
-    if (!res.ok) return { isError: true, content: [{ type: 'text', text: `Destroy failed (${res.status})` }] };
-    return jsonResult(res.body);
-  }
-);
-
 // ── Connect ─────────────────────────────────────────────────────────────
 
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zibby/mcp-cli",
-  "version": "0.2.0",
-  "description": "Zibby CLI MCP Server — expose Zibby workflow deploy/run/debug to AI agents (Claude, Cursor, Codex, Gemini)",
+  "version": "0.3.1",
+  "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",
   "bin": {