@zibby/skills 0.1.25 → 0.1.27

package/docs/packages/mcp-cli.md

@@ -0,0 +1,176 @@
+---
+sidebar_position: 7
+title: "@zibby/mcp-cli"
+---
+
+# @zibby/mcp-cli
+
+A Model Context Protocol (MCP) server that exposes the Zibby CLI surface — deploy, run, debug, trigger — to any MCP-aware AI agent. Install once, drive Zibby from Claude Code / Cursor / OpenAI Codex / Gemini CLI / Continue / Cline / Aider / Goose without leaving chat.
+
+```bash
+# Not installed manually — the agent's `npx` invocation handles it.
+# See "Install" below for per-agent config.
+```
+
+## What it exposes
+
+13 MCP tools, all wrapping the underlying `@zibby/cli`:
+
+| Tool | What it does |
+|---|---|
+| `zibby_login` | Opens the user's browser for device-code OAuth. Saves session to `~/.zibby/config.json`. |
+| `zibby_logout` | Clears the saved session. |
+| `zibby_status` | Who is logged in, how many projects are cached, whether the session is still valid. |
+| `zibby_list_projects` | List the Zibby projects the user has access to. |
+| `zibby_list_templates` | List official workflow templates (browser-test-automation, code-analysis, generate-test-cases, …). |
+| `zibby_scaffold_workflow` | Scaffold `.zibby/workflows/<name>/` from an official template. |
+| `zibby_validate_workflow` | Static-check a local workflow (~30 ms, no API call). |
+| `zibby_list_workflows` | List workflows: local, remote, or both. |
+| `zibby_deploy_workflow` | Deploy a local workflow to a project. |
+| `zibby_trigger_workflow` | Trigger a deployed workflow by UUID. Returns `jobId`. |
+| `zibby_workflow_logs` | Fetch the latest N log lines from a run (one-shot — call again for newer lines). |
+| `zibby_run_workflow_local` | Run a workflow on the user's machine one-shot, for debugging. No cloud. |
+| `zibby_download_workflow` | Pull a deployed workflow back to local. Requires explicit `confirm: true` from the agent. |
+
+**Destructive operations are intentionally not exposed.** Workflow deletion, env-var mutation, schedule changes, and credential management stay in the `zibby` CLI directly. The agent has to involve the user out-of-band for those.
+
+## Install
+
+`@zibby/mcp-cli` ships as a stdio MCP server. The agent's host process spawns it via `npx -y` — no global install needed. The user just needs **Node.js ≥ 18** on their machine.
+
+### Claude Code
+
+`~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "command": "npx",
+      "args": ["-y", "@zibby/mcp-cli"]
+    }
+  }
+}
+```
+
+### 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
+
+If your agent on Windows can't find `npx`, wrap with `cmd /c`:
+
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@zibby/mcp-cli"]
+    }
+  }
+}
+```
+
+## A typical agent chat
+
+```
+User:  Deploy the browser-test template to my "playhouse" project.
+Agent: → zibby_list_projects
+       → zibby_scaffold_workflow (browser-test-automation → .zibby/workflows/playhouse-tests/)
+       → zibby_validate_workflow
+       → zibby_deploy_workflow
+       → "Deployed v1 of playhouse-tests. UUID 988…"
+
+User:  Run it against staging.zibby.dev.
+Agent: → zibby_trigger_workflow (input: { url: "https://staging.zibby.dev" })
+       → zibby_workflow_logs (lines: 200, jobId: "abc-123")
+       → "Run completed. Found 0 errors."
+```
+
+## Auth model
+
+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 at login time 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 same file `zibby login` writes — so if you've already done `zibby login` from a terminal, the MCP server picks up that session.
+
+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.
+
+## Security guarantees
+
+- **No shell interpolation** — every CLI invocation uses `execFile` with argv arrays.
+- **Minimum env passthrough** — only `HOME`, `USER`, `PATH`, and the project-scoped `ZIBBY_API_KEY` reach the child CLI process.
+- **API tokens never returned to the agent** — they live in `~/.zibby/config.json` only, read server-side per call.
+- **Destructive ops excluded** — see the table above.
+- **`zibby_download_workflow` requires `confirm: true`** — the schema rejects calls without it. Agents must explicitly opt in after confirming the destination path with the user.
+
+## 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. |
+| `npx -y` hangs on first install | First-time download. Subsequent invocations are cached by npm. |
+| Tool times out on long deploys | The wrapped CLI command exceeded 10 min. Re-run from a terminal to see live output. |
+
+## Versioning
+
+`@zibby/mcp-cli` pins a specific `@zibby/cli` version in its `dependencies`. Upgrading the MCP package upgrades the bundled CLI in lockstep. Users get the right CLI automatically — no need to coordinate two installs.
+
+## Source
+
+[github.com/ZibbyHQ/zibby-agent → packages/mcps/cli](https://github.com/ZibbyHQ/zibby-agent/tree/main/packages/mcps/cli)

package/docs/recipes/test.md

@@ -185,6 +185,6 @@ For workflows triggered remotely (rather than per-CI-run), use [`workflow trigge
 
 ## See also
 
-- [Recipes overview](./index)
+- [Recipes overview](./)
 - [Concepts: graph](../concepts/graph) — the primitives this recipe uses
 - [Cloud triggering](../cloud/triggering) — fire workflows from CI/CD

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/skills",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Built-in skill definitions for Zibby test automation framework",
   "type": "module",
   "main": "dist/index.js",
@@ -8,6 +8,7 @@
     ".": "./dist/index.js",
     "./bin/mcp-sentry.mjs": "./bin/mcp-sentry.mjs",
     "./bin/mcp-lark.mjs": "./bin/mcp-lark.mjs",
+    "./bin/mcp-slack.mjs": "./bin/mcp-slack.mjs",
     "./browser": "./dist/browser.js",
     "./jira": "./dist/jira.js",
     "./github": "./dist/github.js",
@@ -15,7 +16,10 @@
     "./lark": "./dist/lark.js",
     "./memory": "./dist/memory.js",
     "./function": "./dist/function-skill.js",
-    "./integrations": "./dist/integrations.js"
+    "./integrations": "./dist/integrations.js",
+    "./report": "./dist/report.js",
+    "./llm-billing": "./dist/llm-billing.js",
+    "./sentry": "./dist/sentry.js"
   },
   "scripts": {
     "build": "node ../scripts/build.mjs",
@@ -35,10 +39,10 @@
   "homepage": "https://zibby.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ZibbyHQ/zibby-agent"
+    "url": "https://github.com/ZibbyHQ/skills"
   },
   "bugs": {
-    "url": "https://github.com/ZibbyHQ/zibby-agent/issues"
+    "url": "https://github.com/ZibbyHQ/skills/issues"
   },
   "files": [
     "dist/",
@@ -63,6 +67,9 @@
     "@zibby/mcp-memory": "*"
   },
   "devDependencies": {
-    "esbuild": "^0.28.0"
+    "@eslint/js": "^10.0.1",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.0.2",
+    "globals": "^17.4.0"
   }
 }