@worfilo/mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Worfilo
+
+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,266 @@
+# Worfilo MCP
+
+[![npm version](https://img.shields.io/npm/v/@worfilo/mcp.svg)](https://www.npmjs.com/package/@worfilo/mcp)
+[![CI](https://github.com/Worfilo/mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Worfilo/mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Connect coding agents to [Worfilo](https://worfilo.com) so they can design, build, test and ship AI workflows, then integrate them into your codebase.
+
+This repository contains:
+
+- **`@worfilo/mcp`**: a command-line tool that configures Claude Code, Cursor, Antigravity, VS Code and Windsurf to use the hosted Worfilo MCP server. It also includes a local stdio bridge for clients that cannot authenticate to remote servers.
+- **The `worfilo-workflows` skill**: guidance that teaches agents the Worfilo workflow model, so the workflows they produce validate the first time.
+- **A Claude Code plugin** that bundles the server configuration and the skill.
+
+## Contents
+
+- [What agents can do](#what-agents-can-do)
+- [Requirements](#requirements)
+- [Quick start](#quick-start)
+- [Installation options](#installation-options)
+- [How it works](#how-it-works)
+- [Tools](#tools)
+- [Permissions](#permissions)
+- [CLI reference](#cli-reference)
+- [Security](#security)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [License](#license)
+
+## What agents can do
+
+With Worfilo connected, you can ask your agent for an automation in plain language, for example "when a support email arrives, classify it and open a Linear issue". The agent then:
+
+1. **Discovers** the available node types and the apps, credentials, APIs and MCP servers connected to your account.
+2. **Plans** a workflow graph from your description and shows you the steps before saving anything.
+3. **Builds** the workflow as a draft and resolves validation issues.
+4. **Tests** the draft with realistic input and repairs any failing nodes.
+5. **Publishes** a version once you approve it.
+6. **Integrates** it: creates an API key limited to that workflow, stores it in your environment file, and adds the API call to your code.
+
+Every workflow created this way is a standard Worfilo workflow. You can open it on the canvas, inspect its runs, and edit it like any other.
+
+## Requirements
+
+- A [Worfilo](https://worfilo.com) account.
+- Node.js 20 or later, for the installer and the stdio bridge.
+- One or more supported clients: Claude Code, Cursor, Antigravity, VS Code (agent mode) or Windsurf.
+
+## Quick start
+
+Run the installer from the root of your project:
+
+```sh
+npx @worfilo/mcp install
+```
+
+The installer detects your editors, adds the Worfilo server to each one, and installs the `/worfilo-workflows` guide. It writes configuration only, never credentials, so the generated files are safe to commit.
+
+The first time your agent calls Worfilo, a browser window opens. Sign in, review the permissions the agent is requesting, and approve. Then ask your agent to build a workflow, or invoke `/worfilo-workflows` directly.
+
+The installer runs with any package runner:
+
+```sh
+pnpm dlx @worfilo/mcp install
+yarn dlx @worfilo/mcp install
+bunx @worfilo/mcp install
+```
+
+## Installation options
+
+### Choose editors and scope
+
+```sh
+npx @worfilo/mcp install --client claude-code,cursor   # specific editors
+npx @worfilo/mcp install --scope user                  # all projects, not only this repository
+npx @worfilo/mcp install --dry-run                     # preview changes without writing
+npx @worfilo/mcp uninstall                             # remove the configuration
+```
+
+The installer writes to these locations:
+
+| Client | Server configuration | Guide |
+|---|---|---|
+| Claude Code | `.mcp.json`, or `claude mcp add` with `--scope user` | `.claude/skills/worfilo-workflows/SKILL.md` |
+| Cursor | `.cursor/mcp.json` | `.cursor/commands/` and `.cursor/rules/` |
+| Antigravity | `~/.gemini/antigravity/mcp_config.json` | `.agent/rules/` and `.agent/workflows/` |
+| VS Code | `.vscode/mcp.json` | `.github/prompts/worfilo-workflows.prompt.md` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `.windsurf/rules/` |
+
+Existing entries in these files are preserved. If a file contains comments and cannot be parsed as plain JSON, the installer leaves it unchanged and prints the entry to add manually.
+
+### Claude Code plugin
+
+In Claude Code, you can install Worfilo as a plugin. The plugin bundles the server configuration and the skill, and updates through the plugin system:
+
+```
+/plugin marketplace add Worfilo/mcp
+/plugin install worfilo@worfilo
+```
+
+### Manual configuration
+
+The server endpoint is `https://api.worfilo.com/mcp`, using the Streamable HTTP transport with OAuth 2.1.
+
+Claude Code:
+
+```sh
+claude mcp add --transport http --scope user worfilo https://api.worfilo.com/mcp
+```
+
+Cursor (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "worfilo": { "url": "https://api.worfilo.com/mcp" }
+  }
+}
+```
+
+VS Code (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "worfilo": { "type": "http", "url": "https://api.worfilo.com/mcp" }
+  }
+}
+```
+
+Clients without remote OAuth support can use the stdio bridge:
+
+```json
+{
+  "mcpServers": {
+    "worfilo": { "command": "npx", "args": ["-y", "@worfilo/mcp@latest", "serve"] }
+  }
+}
+```
+
+## How it works
+
+```
+Coding agent --- MCP over HTTPS ---------------------> api.worfilo.com/mcp ---> your Worfilo account
+      |                                                        ^
+      +--- stdio ---> worfilo-mcp serve (local bridge) -------+
+```
+
+- **Hosted server.** Worfilo runs the MCP server. Your agent connects over HTTPS, and nothing runs on your machine besides your editor, unless you use the bridge.
+- **Authentication.** The server is an OAuth 2.1 protected resource (RFC 9728).
+  - Clients register dynamically (RFC 7591) and sign in with the authorization code flow and PKCE.
+  - Access tokens expire after one hour and refresh automatically.
+  - Refresh tokens rotate on every use. Reusing an old refresh token revokes the connection.
+- **Stdio bridge.** `worfilo-mcp serve` reads JSON-RPC messages on stdin and relays them to the hosted server. It runs the OAuth flow itself through a loopback redirect and stores tokens locally.
+- **Guide.** The installer puts the `worfilo-workflows` skill into each editor in that editor's native format. The server also exposes it as the `design_workflow` prompt for any MCP client.
+
+## Tools
+
+The agent sees only the tools allowed by the permissions you grant. Publishing, activating versions and creating API keys are marked as consequential, so clients ask for confirmation before calling them.
+
+| Tool | Permission | Description |
+|---|---|---|
+| `list_node_types` | `workflows:read` | Node types available to workflow graphs |
+| `get_node_type` | `workflows:read` | Ports and configuration schema for one node type |
+| `list_integrations` | `workflows:read` | Connected apps and actions, credential names, custom APIs and MCP servers |
+| `list_workflows` | `workflows:read` | Workflows with publish state and latest run |
+| `get_workflow` | `workflows:read` | Draft graph, published versions and the active version |
+| `validate_workflow` | `workflows:read` | The checks that publishing runs |
+| `get_run` | `workflows:read` | Run status, output, and failing nodes |
+| `get_integration_snippet` | `workflows:read` | TypeScript, JavaScript, Python or curl code for the Workflow API |
+| `plan_workflow` | `workflows:write` | Drafts a graph and a readable plan without saving |
+| `create_workflow` | `workflows:write` | Saves a new draft and returns validation issues |
+| `update_workflow` | `workflows:write` | Replaces a draft graph and returns validation issues |
+| `publish_workflow` | `workflows:publish` | Publishes the draft as a new version, optionally activating it |
+| `activate_version` | `workflows:publish` | Selects the version the API runs |
+| `run_workflow` | `runs:write` | Runs the draft or published version and returns the result |
+| `create_api_key` | `api_keys:write` | Creates an API key limited to specific workflows |
+
+## Permissions
+
+You choose the permissions on the consent screen when the agent first connects.
+
+| Scope | Allows |
+|---|---|
+| `workflows:read` | Reading workflows, node types, integrations and credential names. Always granted. |
+| `workflows:write` | Planning, creating and editing draft workflows. |
+| `workflows:publish` | Publishing versions and changing the active version. |
+| `runs:write` | Running workflows and reading their results. |
+| `api_keys:write` | Creating API keys restricted to chosen workflows. |
+
+To review or revoke connected agents, open **API keys > Connected agents** in Worfilo. Revocation takes effect immediately.
+
+## CLI reference
+
+```
+worfilo-mcp <command> [options]
+```
+
+| Command | Description |
+|---|---|
+| `install` | Configure detected or selected editors (the default when run in a terminal) |
+| `uninstall` | Remove the configuration and guides |
+| `serve` | Run the stdio bridge (the default when started by an editor) |
+| `login` | Sign in for the stdio bridge ahead of time |
+| `logout` | Revoke the bridge's tokens and delete them locally |
+| `status` | Show the bridge's sign-in state |
+| `skill` | Print the workflow guide |
+
+| Option | Description |
+|---|---|
+| `--client <ids>` | Comma-separated: `claude-code`, `cursor`, `antigravity`, `vscode`, `windsurf` |
+| `--scope <scope>` | `project` (default) or `user` |
+| `--url <url>` | MCP server URL |
+| `--bridge` | Configure editors to use the stdio bridge instead of HTTP |
+| `--no-skill` | Skip installing the guide |
+| `--dry-run` | Show changes without writing files |
+| `--yes` | Use detected editors without prompting |
+
+| Environment variable | Description |
+|---|---|
+| `WORFILO_MCP_URL` | MCP server URL, for example `http://localhost:8000/mcp` |
+| `WORFILO_API_URL` | API base URL; `/mcp` is appended |
+| `WORFILO_CONFIG_DIR` | Directory for the bridge's credentials file |
+
+## Security
+
+- The installer writes server URLs and guides only. It never writes tokens or API keys.
+- The bridge stores tokens in `~/.config/worfilo/credentials.json`, or `%APPDATA%\worfilo` on Windows, readable only by your user.
+- On the server, tokens are stored as SHA-256 hashes, and you can revoke any grant from your account.
+- Agents are instructed to keep API keys in untracked environment files, out of source control.
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## Troubleshooting
+
+**The browser did not open during sign-in.** The bridge prints the authorization URL to stderr. Open it manually.
+
+**A configuration file was not updated.** The installer does not modify files that contain comments. Add the printed entry by hand.
+
+**The agent reports a missing permission.** Reconnect Worfilo from your editor and grant the scope named in the message. With the bridge, run `npx @worfilo/mcp logout`, then `login`.
+
+**Connecting to a local or self-hosted deployment.** Set `WORFILO_MCP_URL`, or pass `--url` to `install`. Server URLs must use https; plain http is accepted only for `localhost`, so tokens are never sent unencrypted.
+
+## Development
+
+```sh
+git clone https://github.com/Worfilo/mcp.git
+cd mcp
+npm ci
+npm test
+npm run build
+WORFILO_MCP_URL=http://localhost:8000/mcp node dist/cli.js install --dry-run
+```
+
+`skills/worfilo-workflows/SKILL.md` is the single source for the guide. The installer, the Claude Code plugin and the Worfilo server's `design_workflow` prompt all derive from it.
+
+### Releasing
+
+1. Update the version in `package.json`, `src/constants.ts`, `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`. The test suite fails if they differ.
+2. Push a matching tag, for example `v0.1.2`.
+
+The release workflow publishes to npm through trusted publishing, with provenance.
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.js

@@ -0,0 +1,753 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { spawnSync } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { homedir as homedir2 } from "os";
+import { delimiter, join as join3, relative } from "path";
+import { createInterface as createInterface2 } from "readline/promises";
+import { parseArgs } from "util";
+
+// src/auth.ts
+import { createHash, randomBytes } from "crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { createServer } from "http";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+// src/constants.ts
+var PACKAGE = "@worfilo/mcp";
+var VERSION = "0.2.0";
+var SERVER_NAME = "worfilo";
+var SKILL_NAME = "worfilo-workflows";
+var DEFAULT_URL = "https://api.worfilo.com/mcp";
+var DOCS_URL = "https://worfilo.com/developers/mcp";
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+var SHELL_UNSAFE = /[\s"'`^|<>&;$\\]/;
+function checkUrl(value, what = "URL", strict = true) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${what} is not a valid URL: ${value}`);
+  }
+  const local = url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+  if (url.protocol !== "https:" && !local) {
+    throw new Error(`${what} must use https (http is allowed only for localhost): ${value}`);
+  }
+  if (url.username || url.password) throw new Error(`${what} must not contain credentials: ${value}`);
+  const checked = strict ? value : value.split(/[?#]/)[0] ?? "";
+  if (SHELL_UNSAFE.test(checked)) throw new Error(`${what} contains characters that are not allowed: ${value}`);
+  return value;
+}
+function serverUrl(flag, env = process.env) {
+  let url = DEFAULT_URL;
+  if (flag) url = flag.replace(/\/$/, "");
+  else if (env.WORFILO_MCP_URL) url = env.WORFILO_MCP_URL.replace(/\/$/, "");
+  else if (env.WORFILO_API_URL) url = `${env.WORFILO_API_URL.replace(/\/$/, "")}/mcp`;
+  return checkUrl(url, "The Worfilo server URL");
+}
+function log(message) {
+  process.stderr.write(`${message}
+`);
+}
+
+// src/auth.ts
+var REFRESH_MARGIN_MS = 6e4;
+function defaultStorePath(env = process.env, platform = process.platform) {
+  if (env.WORFILO_CONFIG_DIR) return join(env.WORFILO_CONFIG_DIR, "credentials.json");
+  if (platform === "win32" && env.APPDATA) return join(env.APPDATA, "worfilo", "credentials.json");
+  return join(env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "worfilo", "credentials.json");
+}
+var TokenStore = class {
+  constructor(path) {
+    this.path = path;
+  }
+  readAll() {
+    if (!existsSync(this.path)) return {};
+    try {
+      return JSON.parse(readFileSync(this.path, "utf8"));
+    } catch {
+      return {};
+    }
+  }
+  get(url) {
+    return this.readAll()[url] ?? {};
+  }
+  set(url, tokens) {
+    mkdirSync(dirname(this.path), { recursive: true, mode: 448 });
+    writeFileSync(this.path, `${JSON.stringify({ ...this.readAll(), [url]: tokens }, null, 2)}
+`, { mode: 384 });
+    chmodSync(this.path, 384);
+  }
+  delete(url) {
+    const all = this.readAll();
+    if (!(url in all)) return;
+    delete all[url];
+    writeFileSync(this.path, `${JSON.stringify(all, null, 2)}
+`, { mode: 384 });
+  }
+};
+var b64url = (buffer) => buffer.toString("base64url");
+function pkce() {
+  const verifier = b64url(randomBytes(48));
+  return { verifier, challenge: b64url(createHash("sha256").update(verifier).digest()) };
+}
+async function firstJson(fetchFn, urls) {
+  for (const url of urls) {
+    try {
+      const response = await fetchFn(url, { headers: { Accept: "application/json" } });
+      if (response.ok) return await response.json();
+    } catch {
+    }
+  }
+  return void 0;
+}
+async function discover(url, fetchFn) {
+  const resource = new URL(url);
+  const path = resource.pathname === "/" ? "" : resource.pathname;
+  const prm = await firstJson(fetchFn, [
+    `${resource.origin}/.well-known/oauth-protected-resource${path}`,
+    `${resource.origin}/.well-known/oauth-protected-resource`
+  ]);
+  const servers = prm?.authorization_servers;
+  const issuer = new URL(
+    checkUrl(Array.isArray(servers) && typeof servers[0] === "string" ? servers[0] : resource.origin, "The authorization server")
+  );
+  const issuerPath = issuer.pathname === "/" ? "" : issuer.pathname.replace(/\/$/, "");
+  const metadata = await firstJson(fetchFn, [
+    `${issuer.origin}/.well-known/oauth-authorization-server${issuerPath}`,
+    ...issuerPath ? [`${issuer.origin}${issuerPath}/.well-known/oauth-authorization-server`] : [],
+    `${issuer.origin}/.well-known/openid-configuration${issuerPath}`
+  ]);
+  if (!metadata?.authorization_endpoint || !metadata.token_endpoint) {
+    throw new Error(`Could not find the sign-in endpoints for ${url}. Check the URL, or that the server is up.`);
+  }
+  for (const key of ["authorization_endpoint", "token_endpoint", "registration_endpoint", "revocation_endpoint"]) {
+    const value = metadata[key];
+    if (value !== void 0) checkUrl(String(value), `The server's ${key}`);
+  }
+  return metadata;
+}
+async function postForm(fetchFn, url, form) {
+  const response = await fetchFn(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+    body: new URLSearchParams(form).toString()
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(String(body.error_description ?? body.error ?? `sign-in failed with ${response.status}`));
+  }
+  return body;
+}
+function toTokens(clientId, body) {
+  return {
+    clientId,
+    accessToken: String(body.access_token),
+    refreshToken: body.refresh_token ? String(body.refresh_token) : void 0,
+    expiresAt: Date.now() + Number(body.expires_in ?? 3600) * 1e3,
+    scope: body.scope ? String(body.scope) : void 0
+  };
+}
+var DONE_PAGE = (message) => `<!doctype html><meta charset="utf-8"><title>Worfilo</title><body style="font:16px system-ui;padding:3rem;max-width:32rem;margin:auto"><h1 style="font-size:1.25rem">${message}</h1><p>You can close this tab and return to your editor.</p></body>`;
+async function login(url, deps) {
+  const metadata = await discover(url, deps.fetch);
+  const { verifier, challenge } = pkce();
+  const state = b64url(randomBytes(16));
+  let settle;
+  const received = new Promise((resolve, reject) => settle = { resolve, reject });
+  const server = createServer((request, response) => {
+    const query = new URL(request.url ?? "/", "http://127.0.0.1").searchParams;
+    if (!request.url?.startsWith("/callback")) {
+      response.writeHead(404).end();
+      return;
+    }
+    const error = query.get("error");
+    const ok = !error && query.get("state") === state && query.get("code");
+    response.writeHead(ok ? 200 : 400, { "Content-Type": "text/html; charset=utf-8" });
+    response.end(DONE_PAGE(ok ? "Worfilo is connected" : "Worfilo was not connected"));
+    if (error) settle?.reject(new Error(query.get("error_description") ?? error));
+    else if (query.get("state") !== state) settle?.reject(new Error("The sign-in response did not match this request."));
+    else settle?.resolve(query.get("code") ?? "");
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  const redirectUri = `http://127.0.0.1:${typeof address === "object" && address ? address.port : 0}/callback`;
+  try {
+    let clientId = deps.store.get(url).clientId;
+    if (!clientId) {
+      if (!metadata.registration_endpoint) throw new Error("This server does not support client registration.");
+      const response = await deps.fetch(metadata.registration_endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({
+          client_name: `Worfilo MCP CLI ${VERSION}`,
+          redirect_uris: [redirectUri],
+          grant_types: ["authorization_code", "refresh_token"],
+          response_types: ["code"],
+          token_endpoint_auth_method: "none"
+        })
+      });
+      const body = await response.json();
+      if (!response.ok) throw new Error(String(body.error_description ?? "client registration failed"));
+      clientId = String(body.client_id);
+    }
+    const authorize = new URL(metadata.authorization_endpoint);
+    for (const [key, value] of Object.entries({
+      response_type: "code",
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      state,
+      resource: url
+    })) {
+      authorize.searchParams.set(key, value);
+    }
+    deps.log(`Opening your browser to sign in to Worfilo. If it does not open, visit:
+${authorize.toString()}`);
+    deps.open(authorize.toString());
+    const timeout = new Promise(
+      (_, reject) => setTimeout(() => reject(new Error("Timed out waiting for sign-in.")), deps.timeoutMs ?? 5 * 6e4).unref()
+    );
+    const code = await Promise.race([received, timeout]);
+    const tokens = toTokens(
+      clientId,
+      await postForm(deps.fetch, metadata.token_endpoint, {
+        grant_type: "authorization_code",
+        code,
+        code_verifier: verifier,
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        resource: url
+      })
+    );
+    deps.store.set(url, tokens);
+    return tokens;
+  } finally {
+    server.close();
+  }
+}
+async function refresh(url, deps) {
+  const stored = deps.store.get(url);
+  if (!stored.refreshToken || !stored.clientId) return void 0;
+  try {
+    const metadata = await discover(url, deps.fetch);
+    const tokens = toTokens(
+      stored.clientId,
+      await postForm(deps.fetch, metadata.token_endpoint, {
+        grant_type: "refresh_token",
+        refresh_token: stored.refreshToken,
+        client_id: stored.clientId,
+        resource: url
+      })
+    );
+    deps.store.set(url, tokens);
+    return tokens;
+  } catch (error) {
+    deps.log(`Could not refresh the Worfilo session: ${error.message}`);
+    deps.store.set(url, { clientId: stored.clientId });
+    return void 0;
+  }
+}
+async function accessToken(url, deps) {
+  const stored = deps.store.get(url);
+  if (stored.accessToken && (stored.expiresAt ?? 0) - REFRESH_MARGIN_MS > Date.now()) return stored.accessToken;
+  return (await refresh(url, deps))?.accessToken;
+}
+async function logout(url, deps) {
+  const stored = deps.store.get(url);
+  const token = stored.refreshToken ?? stored.accessToken;
+  if (token) {
+    try {
+      const metadata = await discover(url, deps.fetch);
+      if (metadata.revocation_endpoint) await postForm(deps.fetch, metadata.revocation_endpoint, { token });
+    } catch {
+    }
+  }
+  deps.store.delete(url);
+  return Boolean(token);
+}
+
+// src/bridge.ts
+import { createInterface } from "readline";
+var Bridge = class {
+  constructor(url, deps, write) {
+    this.url = url;
+    this.deps = deps;
+    this.write = write;
+  }
+  signingIn;
+  protocolVersion;
+  async token() {
+    const token = await accessToken(this.url, this.deps);
+    if (token) return token;
+    this.signingIn ??= login(this.url, this.deps).finally(() => this.signingIn = void 0);
+    await this.signingIn;
+    return await accessToken(this.url, this.deps) ?? "";
+  }
+  post(message, token) {
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+      Authorization: `Bearer ${token}`
+    };
+    if (this.protocolVersion) headers["MCP-Protocol-Version"] = this.protocolVersion;
+    return this.deps.fetch(this.url, { method: "POST", headers, body: JSON.stringify(message) });
+  }
+  async relay(message) {
+    const expectsAnswer = message.method !== void 0 && message.id !== void 0 && message.id !== null;
+    try {
+      let response = await this.post(message, await this.token());
+      if (response.status === 401) {
+        const renewed = (await refresh(this.url, this.deps))?.accessToken ?? await this.token();
+        response = await this.post(message, renewed);
+      }
+      if (response.status === 202 || !expectsAnswer) return;
+      const type = response.headers.get("content-type") ?? "";
+      const text = await response.text();
+      const answers = type.includes("text/event-stream") ? fromEventStream(text) : [text];
+      for (const answer of answers) {
+        if (message.method === "initialize") this.rememberVersion(answer);
+        this.write(answer);
+      }
+      if (!answers.length) this.fail(message, `Worfilo answered ${response.status} with no body.`);
+    } catch (error) {
+      if (expectsAnswer) this.fail(message, error.message);
+    }
+  }
+  rememberVersion(answer) {
+    try {
+      this.protocolVersion = JSON.parse(answer).result?.protocolVersion;
+    } catch {
+    }
+  }
+  fail(message, detail) {
+    this.write(JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: -32603, message: `Worfilo: ${detail}` } }));
+  }
+};
+function fromEventStream(text) {
+  return text.split(/\r?\n\r?\n/).map(
+    (event) => event.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n")
+  ).filter(Boolean);
+}
+async function serve(url, deps) {
+  const bridge = new Bridge(url, deps, (line) => process.stdout.write(`${line}
+`));
+  const pending = /* @__PURE__ */ new Set();
+  const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      deps.log("Ignored a line that is not JSON.");
+      continue;
+    }
+    const task = bridge.relay(message).finally(() => pending.delete(task));
+    pending.add(task);
+  }
+  await Promise.all(pending);
+}
+
+// src/browser.ts
+import { spawn } from "child_process";
+function browserCommand(url, platform = process.platform) {
+  checkUrl(url, "The sign-in URL", false);
+  if (platform === "darwin") return ["open", [url]];
+  if (platform === "win32") return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+  return ["xdg-open", [url]];
+}
+function openBrowser(url) {
+  try {
+    const [command, args] = browserCommand(url);
+    spawn(command, args, { stdio: "ignore", detached: true }).on("error", () => void 0).unref();
+  } catch {
+  }
+}
+
+// src/clients.ts
+import { join as join2 } from "path";
+
+// src/skill.ts
+import { readFileSync as readFileSync2 } from "fs";
+function parseSkill(raw) {
+  const match = /^---\n([\s\S]*?)\n---\n+([\s\S]*)$/.exec(raw);
+  if (!match) throw new Error("SKILL.md has no frontmatter");
+  const field = (key) => new RegExp(`^${key}:\\s*(.+)$`, "m").exec(match[1] ?? "")?.[1]?.trim() ?? "";
+  return { name: field("name"), description: field("description"), body: match[2] ?? "", raw };
+}
+function loadSkill() {
+  return parseSkill(readFileSync2(new URL("../skills/worfilo-workflows/SKILL.md", import.meta.url), "utf8"));
+}
+var frontmatter = (fields) => `---
+${Object.entries(fields).map(([key, value]) => `${key}: ${typeof value === "string" ? JSON.stringify(value) : value}`).join("\n")}
+---
+
+`;
+var variants = {
+  claudeSkill: (skill) => skill.raw,
+  cursorRule: (skill) => frontmatter({ description: skill.description, alwaysApply: false }) + skill.body,
+  plainCommand: (skill) => skill.body,
+  modelDecisionRule: (skill) => frontmatter({ trigger: "model_decision", description: skill.description }) + skill.body,
+  antigravityWorkflow: (skill) => frontmatter({ description: skill.description }) + skill.body,
+  vscodePrompt: (skill) => frontmatter({ description: skill.description, mode: "agent" }) + skill.body
+};
+
+// src/clients.ts
+var bridgeEntry = (url) => ({
+  command: "npx",
+  args: ["-y", `${PACKAGE}@latest`, "serve", "--url", url]
+});
+function vscodeUserDir(place2) {
+  if (place2.platform === "win32") return join2(place2.appData ?? join2(place2.home, "AppData", "Roaming"), "Code", "User");
+  if (place2.platform === "darwin") return join2(place2.home, "Library", "Application Support", "Code", "User");
+  return join2(place2.home, ".config", "Code", "User");
+}
+var userOnly = (name) => ({
+  kind: "note",
+  text: `${name} reads the guide per project; run install with --scope project inside a repo to add it there.`
+});
+var CLIENTS = [
+  {
+    id: "claude-code",
+    name: "Claude Code",
+    detect: (place2, { onPath: onPath2, exists }) => onPath2("claude") || exists(join2(place2.home, ".claude")),
+    plan: (place2, options) => {
+      const entry = options.bridge ? bridgeEntry(options.url) : { type: "http", url: options.url };
+      const steps = options.scope === "project" ? [{ kind: "server", path: join2(place2.cwd, ".mcp.json"), key: "mcpServers", entry }] : [
+        {
+          kind: "command",
+          argv: options.bridge ? ["claude", "mcp", "add", "--scope", "user", SERVER_NAME, "--", "npx", "-y", `${PACKAGE}@latest`, "serve", "--url", options.url] : ["claude", "mcp", "add", "--transport", "http", "--scope", "user", SERVER_NAME, options.url],
+          undo: ["claude", "mcp", "remove", "--scope", "user", SERVER_NAME]
+        }
+      ];
+      if (options.withSkill) {
+        const root = options.scope === "project" ? place2.cwd : place2.home;
+        steps.push({
+          kind: "file",
+          path: join2(root, ".claude", "skills", SKILL_NAME, "SKILL.md"),
+          content: variants.claudeSkill(options.skill),
+          removeDir: true
+        });
+      }
+      steps.push({ kind: "note", text: `In Claude Code, run /mcp and choose ${SERVER_NAME} to sign in. Then use /${SKILL_NAME}.` });
+      return steps;
+    }
+  },
+  {
+    id: "cursor",
+    name: "Cursor",
+    detect: (place2, { onPath: onPath2, exists }) => onPath2("cursor") || exists(join2(place2.home, ".cursor")),
+    plan: (place2, options) => {
+      const root = options.scope === "project" ? place2.cwd : place2.home;
+      const entry = options.bridge ? bridgeEntry(options.url) : { url: options.url };
+      const steps = [{ kind: "server", path: join2(root, ".cursor", "mcp.json"), key: "mcpServers", entry }];
+      if (options.withSkill) {
+        steps.push({ kind: "file", path: join2(root, ".cursor", "commands", `${SKILL_NAME}.md`), content: variants.plainCommand(options.skill) });
+        if (options.scope === "project") {
+          steps.push({ kind: "file", path: join2(root, ".cursor", "rules", `${SKILL_NAME}.mdc`), content: variants.cursorRule(options.skill) });
+        }
+      }
+      steps.push({ kind: "note", text: `In Cursor, open Settings > MCP and select Connect on ${SERVER_NAME} to sign in. Then use /${SKILL_NAME}.` });
+      return steps;
+    }
+  },
+  {
+    id: "antigravity",
+    name: "Antigravity",
+    detect: (place2, { onPath: onPath2, exists }) => onPath2("antigravity") || exists(join2(place2.home, ".gemini", "antigravity")),
+    plan: (place2, options) => {
+      const entry = options.bridge ? bridgeEntry(options.url) : { serverUrl: options.url };
+      const steps = [
+        { kind: "server", path: join2(place2.home, ".gemini", "antigravity", "mcp_config.json"), key: "mcpServers", entry }
+      ];
+      if (options.withSkill) {
+        if (options.scope === "project") {
+          steps.push(
+            { kind: "file", path: join2(place2.cwd, ".agent", "rules", `${SKILL_NAME}.md`), content: variants.modelDecisionRule(options.skill) },
+            { kind: "file", path: join2(place2.cwd, ".agent", "workflows", `${SKILL_NAME}.md`), content: variants.antigravityWorkflow(options.skill) }
+          );
+        } else {
+          steps.push(userOnly("Antigravity"));
+        }
+      }
+      steps.push({ kind: "note", text: `In Antigravity, refresh the MCP servers panel and sign in when the browser opens. Then use /${SKILL_NAME}.` });
+      return steps;
+    }
+  },
+  {
+    id: "vscode",
+    name: "VS Code",
+    detect: (place2, { onPath: onPath2, exists }) => onPath2("code") || exists(vscodeUserDir(place2)),
+    plan: (place2, options) => {
+      const entry = options.bridge ? { type: "stdio", ...bridgeEntry(options.url) } : { type: "http", url: options.url };
+      const path = options.scope === "project" ? join2(place2.cwd, ".vscode", "mcp.json") : join2(vscodeUserDir(place2), "mcp.json");
+      const steps = [{ kind: "server", path, key: "servers", entry }];
+      if (options.withSkill) {
+        steps.push(
+          options.scope === "project" ? { kind: "file", path: join2(place2.cwd, ".github", "prompts", `${SKILL_NAME}.prompt.md`), content: variants.vscodePrompt(options.skill) } : { kind: "file", path: join2(vscodeUserDir(place2), "prompts", `${SKILL_NAME}.prompt.md`), content: variants.vscodePrompt(options.skill) }
+        );
+      }
+      steps.push({ kind: "note", text: `In VS Code, open mcp.json and select Start on ${SERVER_NAME} to sign in. Then use /${SKILL_NAME} in agent mode.` });
+      return steps;
+    }
+  },
+  {
+    id: "windsurf",
+    name: "Windsurf",
+    detect: (place2, { onPath: onPath2, exists }) => onPath2("windsurf") || exists(join2(place2.home, ".codeium", "windsurf")),
+    plan: (place2, options) => {
+      const entry = options.bridge ? bridgeEntry(options.url) : { serverUrl: options.url };
+      const steps = [
+        { kind: "server", path: join2(place2.home, ".codeium", "windsurf", "mcp_config.json"), key: "mcpServers", entry }
+      ];
+      if (options.withSkill) {
+        steps.push(
+          options.scope === "project" ? { kind: "file", path: join2(place2.cwd, ".windsurf", "rules", `${SKILL_NAME}.md`), content: variants.modelDecisionRule(options.skill) } : userOnly("Windsurf")
+        );
+      }
+      steps.push({ kind: "note", text: `In Windsurf, refresh MCP servers in Cascade and sign in when asked.` });
+      return steps;
+    }
+  }
+];
+var CLIENT_IDS = CLIENTS.map((client) => client.id);
+function findClient(id) {
+  const aliases = { claude: "claude-code", code: "vscode", "vs-code": "vscode", gemini: "antigravity" };
+  const wanted = aliases[id] ?? id;
+  return CLIENTS.find((client) => client.id === wanted);
+}
+
+// src/files.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2 } from "path";
+var ConfigError = class extends Error {
+};
+function readJson(path) {
+  if (!existsSync2(path)) return {};
+  const text = readFileSync3(path, "utf8");
+  if (!text.trim()) return {};
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+  } catch {
+  }
+  throw new ConfigError(`${path} is not plain JSON, so it was left untouched`);
+}
+function withServer(config, key, name, entry) {
+  const servers = config[key] && typeof config[key] === "object" ? config[key] : {};
+  return { ...config, [key]: { ...servers, [name]: entry } };
+}
+function withoutServer(config, key, name) {
+  const servers = config[key] && typeof config[key] === "object" ? { ...config[key] } : {};
+  delete servers[name];
+  return { ...config, [key]: servers };
+}
+function writeText(path, content) {
+  mkdirSync2(dirname2(path), { recursive: true });
+  writeFileSync2(path, content);
+}
+function writeJson(path, value) {
+  writeText(path, `${JSON.stringify(value, null, 2)}
+`);
+}
+function remove(path) {
+  if (!existsSync2(path)) return false;
+  rmSync(path, { recursive: true, force: true });
+  return true;
+}
+
+// src/cli.ts
+var HELP = `${PACKAGE} ${VERSION}: connect coding agents to Worfilo
+
+Usage
+  npx ${PACKAGE} install [options]    Add Worfilo and the /worfilo-workflows guide to your editors
+  npx ${PACKAGE} uninstall [options]  Remove them again
+  npx ${PACKAGE} login                Sign in for the local bridge
+  npx ${PACKAGE} logout               Sign out and revoke the bridge's tokens
+  npx ${PACKAGE} status               Show the bridge's sign-in state
+  npx ${PACKAGE} serve                Run the stdio bridge (editors start this for you)
+  npx ${PACKAGE} skill                Print the workflow guide
+
+Options
+  --client <ids>   ${CLIENT_IDS.join(", ")} (comma separated; default: detected)
+  --scope <scope>  project (this repo, default) or user (every project)
+  --url <url>      MCP server URL (default: WORFILO_MCP_URL, WORFILO_API_URL/mcp, or production)
+  --bridge         Connect through the local stdio bridge instead of over HTTP
+  --no-skill       Skip the /worfilo-workflows guide
+  --dry-run        Show what would change without writing anything
+  --yes            Do not ask; use detected editors
+
+Docs: ${DOCS_URL}`;
+function onPath(bin) {
+  const extensions = process.platform === "win32" ? ["", ".cmd", ".exe", ".bat"] : [""];
+  return (process.env.PATH ?? "").split(delimiter).some((dir) => dir && extensions.some((extension) => existsSync3(join3(dir, bin + extension))));
+}
+function authDeps() {
+  return { fetch: globalThis.fetch, store: new TokenStore(defaultStorePath()), open: openBrowser, log };
+}
+var place = () => ({ cwd: process.cwd(), home: homedir2(), platform: process.platform, appData: process.env.APPDATA });
+var shown = (path) => path.startsWith(process.cwd()) ? relative(process.cwd(), path) || "." : path.replace(homedir2(), "~");
+async function chooseClients(ids, yes) {
+  if (ids) {
+    return ids.split(",").map((id) => {
+      const client = findClient(id.trim());
+      if (!client) throw new Error(`Unknown client '${id}'. Choose from: ${CLIENT_IDS.join(", ")}.`);
+      return client;
+    });
+  }
+  const probe = { onPath, exists: existsSync3 };
+  const detected = CLIENTS.filter((client) => client.detect(place(), probe));
+  if (yes || !process.stdin.isTTY) {
+    if (!detected.length) throw new Error(`No supported editor found. Pass --client with one of: ${CLIENT_IDS.join(", ")}.`);
+    return detected;
+  }
+  log("Which editors should use Worfilo?");
+  CLIENTS.forEach((client, index) => log(`  ${index + 1}. ${client.name}${detected.includes(client) ? " (detected)" : ""}`));
+  const prompt = createInterface2({ input: process.stdin, output: process.stderr });
+  const fallback = detected.map((client) => CLIENTS.indexOf(client) + 1).join(",");
+  const answer = (await prompt.question(`Numbers, comma separated [${fallback || "1"}]: `)).trim() || fallback || "1";
+  prompt.close();
+  const chosen = answer.split(",").map((part) => CLIENTS[Number(part.trim()) - 1]).filter((client) => Boolean(client));
+  if (!chosen.length) throw new Error("No editor chosen.");
+  return chosen;
+}
+function apply(step, dryRun, undo) {
+  const prefix = dryRun ? "would " : "";
+  switch (step.kind) {
+    case "server": {
+      try {
+        const current = readJson(step.path);
+        const next = undo ? withoutServer(current, step.key, SERVER_NAME) : withServer(current, step.key, SERVER_NAME, step.entry);
+        if (!dryRun) writeJson(step.path, next);
+        return `${prefix}${undo ? "remove" : "add"} ${SERVER_NAME} in ${shown(step.path)}`;
+      } catch (error) {
+        if (!(error instanceof ConfigError)) throw error;
+        return `${error.message}. Add this under "${step.key}" by hand:
+  "${SERVER_NAME}": ${JSON.stringify(step.entry)}`;
+      }
+    }
+    case "file": {
+      if (undo) {
+        const path = step.removeDir ? join3(step.path, "..") : step.path;
+        if (!dryRun) remove(path);
+        return `${prefix}remove ${shown(path)}`;
+      }
+      if (!dryRun) writeText(step.path, step.content);
+      return `${prefix}write ${shown(step.path)}`;
+    }
+    case "command": {
+      const argv = undo ? step.undo : step.argv;
+      const [bin, ...args] = argv;
+      if (!bin || !onPath(bin)) return `run this yourself: ${argv.join(" ")}`;
+      if (dryRun) return `would run: ${argv.join(" ")}`;
+      const result = spawnSync(bin, args, { stdio: "inherit", shell: process.platform === "win32" });
+      return result.status === 0 ? `ran: ${argv.join(" ")}` : `this failed, run it yourself: ${argv.join(" ")}`;
+    }
+    case "note":
+      return void 0;
+  }
+}
+async function install(values, undo) {
+  const scope = values.scope ?? "project";
+  if (scope !== "project" && scope !== "user") throw new Error("--scope is project or user.");
+  const url = serverUrl(values.url);
+  const clients = await chooseClients(values.client, Boolean(values.yes));
+  const options = { url, scope, skill: loadSkill(), withSkill: !values["no-skill"], bridge: Boolean(values.bridge) };
+  const notes = [];
+  for (const client of clients) {
+    log(`
+${client.name}`);
+    for (const step of client.plan(place(), options)) {
+      if (step.kind === "note") {
+        if (!undo) notes.push(`${client.name}: ${step.text}`);
+        continue;
+      }
+      const line = apply(step, Boolean(values["dry-run"]), undo);
+      if (line) log(`  ${line}`);
+    }
+  }
+  if (undo) {
+    log(`
+Removed. To revoke access too, run: npx ${PACKAGE} logout, and disconnect the agent under API keys in Worfilo.`);
+    return;
+  }
+  log(`
+Worfilo MCP server: ${url}`);
+  for (const note of notes) log(`- ${note}`);
+  if (scope === "project") log("- Commit the new files to share the setup with your team; no secrets were written.");
+}
+async function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      client: { type: "string" },
+      scope: { type: "string" },
+      url: { type: "string" },
+      bridge: { type: "boolean" },
+      "no-skill": { type: "boolean" },
+      "dry-run": { type: "boolean" },
+      yes: { type: "boolean", short: "y" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" }
+    }
+  });
+  if (values.version) {
+    log(VERSION);
+    return 0;
+  }
+  const command = positionals[0] ?? (values.help ? "help" : process.stdin.isTTY ? "install" : "serve");
+  const url = serverUrl(values.url);
+  switch (command) {
+    case "install":
+    case "uninstall":
+      await install(values, command === "uninstall");
+      return 0;
+    case "serve":
+      await serve(url, authDeps());
+      return 0;
+    case "login": {
+      const tokens = await login(url, authDeps());
+      log(`Signed in to ${url} with: ${tokens.scope ?? "all permissions"}`);
+      return 0;
+    }
+    case "logout":
+      log(await logout(url, authDeps()) ? `Signed out of ${url}.` : `Not signed in to ${url}.`);
+      return 0;
+    case "status": {
+      const tokens = new TokenStore(defaultStorePath()).get(url);
+      if (!tokens.refreshToken && !tokens.accessToken) log(`Not signed in to ${url}. Run: npx ${PACKAGE} login`);
+      else log(`Signed in to ${url}
+Permissions: ${tokens.scope ?? "unknown"}
+Token refreshes: ${tokens.refreshToken ? "yes" : "no"}`);
+      return 0;
+    }
+    case "skill":
+      process.stdout.write(loadSkill().raw);
+      return 0;
+    case "help":
+      log(HELP);
+      return 0;
+    default:
+      log(`Unknown command '${command}'.
+
+${HELP}`);
+      return 1;
+  }
+}
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    log(`Error: ${error.message}`);
+    process.exitCode = 1;
+  }
+);
+export {
+  main
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@worfilo/mcp",
+  "version": "0.2.0",
+  "description": "Connect Claude Code, Cursor, Antigravity and other coding agents to Worfilo, so they can plan, build and integrate workflows.",
+  "keywords": [
+    "worfilo",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "cursor",
+    "antigravity",
+    "workflows",
+    "ai-agents"
+  ],
+  "homepage": "https://github.com/Worfilo/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/Worfilo/mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Worfilo/mcp.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "worfilo-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.0",
+    "vitest": "^5.0.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skills/worfilo-workflows/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: worfilo-workflows
+description: Plan, build, test, publish and integrate Worfilo AI workflows into this codebase through the Worfilo MCP server. Use when the user wants to automate a task, build an AI agent workflow, or call a Worfilo workflow from their code.
+---
+
+# Building Worfilo workflows
+
+Worfilo runs AI agent workflows: a trigger, then nodes (agents, app actions, HTTP calls, logic) joined by edges. You build them through the Worfilo MCP tools, then call them from the user's code through the public API.
+
+## Procedure
+
+1. **Understand the goal.** Ask what should start the workflow, what it must produce, and which apps it touches. Read the codebase to see where it will be called from and what input it can send.
+2. **Discover.** Call `list_integrations` to see connected apps, credentials, custom APIs and MCP servers. Call `list_node_types`, then `get_node_type` for each type you plan to use. Never invent node types, ports or config fields.
+3. **Plan.** Call `plan_workflow` with a precise description. It drafts a graph from the account's real integrations. Show the user the `steps` in plain words and agree on changes before saving. For revisions, pass `previous_graph` and an `instruction`.
+4. **Create.** Call `create_workflow` with the agreed graph. Fix every `error` in `issues` with `update_workflow` (it replaces the whole draft graph). Warnings do not block.
+5. **Test.** Call `run_workflow` on the draft with a realistic `input`. If it fails, read `failed_nodes`, fix the graph, and run again. Runs can call real apps and spend tokens, so say what a test run will do first.
+6. **Publish.** Ask the user, then call `publish_workflow`. It activates the new version by default, which is what the API runs.
+7. **Integrate.**
+   - Call `create_api_key` scoped to this workflow only, and write the key to an untracked env file as `WORFILO_API_KEY`. Check `.gitignore` covers it, and never print the key back or commit it.
+   - Call `get_integration_snippet` in the codebase's language, then adapt it to the project's HTTP client, types, config loading and error handling.
+   - Handle both answers: 200 means finished, and 202 means poll `status_url`.
+8. **Hand over.** Tell the user the workflow name, the `editor_url`, where the call site lives, and which env var to set in each deployment.
+
+## The graph
+
+```json
+{
+  "schema_version": 1,
+  "nodes": [
+    {"id": "trigger", "type": "manual_trigger", "name": "Trigger", "position": {"x": 0, "y": 0},
+     "config": {"test_payload": {"message": "Summarise this"}}},
+    {"id": "summarise", "type": "agent", "name": "Summarise", "position": {"x": 260, "y": 0},
+     "config": {"credential_id": "<an anthropic credential_id>", "model": "claude-haiku-4-5-20251001",
+                "user_prompt": "Summarise: {{ trigger.message }}"}},
+    {"id": "result", "type": "output", "name": "Result", "position": {"x": 520, "y": 0},
+     "config": {"value": "{{ nodes.summarise.output.text }}"}}
+  ],
+  "edges": [
+    {"id": "e1", "source": "trigger", "target": "summarise"},
+    {"id": "e2", "source": "summarise", "target": "result"}
+  ],
+  "settings": {}
+}
+```
+
+The example shows the shape only. Take each node's exact config fields from `get_node_type`.
+
+## Rules
+
+- **Trigger.** Exactly one trigger node. Use `manual_trigger` for workflows called from code through the API, with a realistic `config.test_payload`. `webhook_trigger` and `schedule_trigger` exist for other starts.
+- **Ids and names.** Node ids are unique lowercase slugs matching `^[a-z][a-z0-9_]*$`. Names are short Title Case labels.
+- **Config.** Every config must satisfy its node type's `config_schema`, required fields included.
+- **Edges.** An edge goes from an output port to an input port. Omit ports for the defaults (`out` to `in`).
+- **Branching.**
+  - An `if` node fires `true` or `false`; connect each branch with `source_port` set to that name.
+  - A `switch` node's `config.cases` each name a port, plus `default`.
+  - When branches rejoin, route them through a `merge` node.
+- **Flow.** Data flows forward only: no cycles, and every node is reachable from the trigger. End with an `output` node, whose value is what the API returns.
+- **Templates.**
+  - `{{ trigger.<field> }}` reads the trigger payload. `{{ nodes.<id>.output.<field> }}` reads an upstream node, and only upstream nodes may be referenced.
+  - `if` and `switch` expressions are bare, without braces, e.g. `nodes.classify.output.structured.urgency == 'high'`.
+- **Agents.**
+  - Set `credential_id` to an `anthropic` credential from `list_integrations`.
+  - An agent's output has `.text`, and `.structured` when `config.output_schema` is set. Set `output_schema` whenever later nodes branch on the answer.
+  - Use `claude-haiku-4-5-20251001` unless the task needs deeper reasoning, then `claude-sonnet-5`.
+- **Apps.**
+  - GitHub, Slack, Notion, Linear and Tavily use a `connector_action` node with `connector_id`, `action` and `args`. Set `connection_id` from `list_integrations`, and prefer it over `http_request`.
+  - The user's own APIs use `api_request` with `api_id`, `endpoint` and `args`. Their MCP servers use `mcp_tool`.
+- **Tools for agents.** An `http_request`, `connector_action` or `api_request` node can be attached to an agent with an edge of `kind: "tool"` and `target_port: "tools"`. A tool node has no other edges.
+- **Secrets.** Never put keys or tokens in a graph. Reference stored credentials and connections by id. If one is missing, send the user to `connect_more` from `list_integrations`.
+- **Size.** Prefer a few well-chosen nodes over many.
+
+## Guardrails
+
+- Confirm the plan before `create_workflow`, and ask before `publish_workflow`, `activate_version` and `create_api_key`.
+- Edit drafts freely. Published versions change only when you publish again.
+- Keep API keys out of source control, logs and chat.
+- If a tool says a permission was not granted, ask the user to reconnect Worfilo and allow it.