@novalinkai/mcp 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @novalinkai/mcp
+
+Connect Claude Code, Cursor, Antigravity, VS Code and Windsurf to [Novalink](https://novalink.live). Your coding agent can then plan AI workflows, build and test them, publish them, and wire them into your codebase.
+
+```sh
+npx @novalinkai/mcp install
+```
+
+Any package runner works:
+
+```sh
+pnpm dlx @novalinkai/mcp install
+yarn dlx @novalinkai/mcp install
+bunx @novalinkai/mcp install
+```
+
+The installer finds your editors, adds the Novalink MCP server (`https://api.novalink.live/mcp`) to each one, and adds the `/novalink-workflows` guide. The first time the agent uses Novalink, your browser opens so you can sign in and choose what it may do. The installer never writes secrets.
+
+## What gets written
+
+| Editor | Server config | Guide |
+|---|---|---|
+| Claude Code | `.mcp.json`, or `claude mcp add` for `--scope user` | `.claude/skills/novalink-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/novalink-workflows.prompt.md` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `.windsurf/rules/` |
+
+Existing servers in these files are kept. Files with comments are left alone, and the installer prints the entry for you to add by hand.
+
+## Options
+
+```
+npx @novalinkai/mcp install --client claude-code,cursor   # choose editors
+npx @novalinkai/mcp install --scope user                  # every project, not just this repo
+npx @novalinkai/mcp install --bridge                      # connect through the local stdio bridge
+npx @novalinkai/mcp install --dry-run                     # show changes only
+npx @novalinkai/mcp uninstall                             # remove them again
+```
+
+## The stdio bridge
+
+Some editors cannot sign in to a remote MCP server themselves. For those, `npx @novalinkai/mcp serve` runs locally over stdio and relays to Novalink. It runs the OAuth sign-in in your browser and keeps tokens in `~/.config/novalink/credentials.json`, which only you can read.
+
+```sh
+npx @novalinkai/mcp login    # sign in ahead of time
+npx @novalinkai/mcp status
+npx @novalinkai/mcp logout   # revoke and forget the tokens
+```
+
+Set `NOVALINK_MCP_URL` (or `NOVALINK_API_URL`) to point at another deployment, such as `http://localhost:8000/mcp` in development.
+
+## Permissions
+
+At sign-in you choose what the agent may do:
+
+- **workflows:read**: see workflows, node types, connections and credential names.
+- **workflows:write**: plan, create and edit drafts.
+- **workflows:publish**: publish versions and choose the active one.
+- **runs:write**: run workflows.
+- **api_keys:write**: create API keys limited to chosen workflows.
+
+To disconnect an agent at any time, go to **API keys > Connected agents** in Novalink.
+
+Docs: https://novalink.live/developers/mcp

package/dist/cli.js

@@ -0,0 +1,723 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { spawn, 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 = "@novalinkai/mcp";
+var VERSION = "0.1.0";
+var SERVER_NAME = "novalink";
+var SKILL_NAME = "novalink-workflows";
+var DEFAULT_URL = "https://api.novalink.live/mcp";
+var DOCS_URL = "https://novalink.live/developers/mcp";
+function serverUrl(flag, env = process.env) {
+  if (flag) return flag.replace(/\/$/, "");
+  if (env.NOVALINK_MCP_URL) return env.NOVALINK_MCP_URL.replace(/\/$/, "");
+  if (env.NOVALINK_API_URL) return `${env.NOVALINK_API_URL.replace(/\/$/, "")}/mcp`;
+  return DEFAULT_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.NOVALINK_CONFIG_DIR) return join(env.NOVALINK_CONFIG_DIR, "credentials.json");
+  if (platform === "win32" && env.APPDATA) return join(env.APPDATA, "novalink", "credentials.json");
+  return join(env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "novalink", "credentials.json");
+}
+var TokenStore = class {
+  constructor(path) {
+    this.path = 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(Array.isArray(servers) && typeof servers[0] === "string" ? servers[0] : resource.origin);
+  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.`);
+  }
+  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>Novalink</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 ? "Novalink is connected" : "Novalink 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: `Novalink 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 Novalink. 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 Novalink 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;
+  }
+  url;
+  deps;
+  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, `Novalink 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: `Novalink: ${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/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("../skill/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 Novalink
+
+Usage
+  npx ${PACKAGE} install [options]    Add Novalink and the /novalink-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: NOVALINK_MCP_URL, NOVALINK_API_URL/mcp, or production)
+  --bridge         Connect through the local stdio bridge instead of over HTTP
+  --no-skill       Skip the /novalink-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 openBrowser(url) {
+  const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url.replace(/&/g, "^&")]] : ["xdg-open", [url]];
+  try {
+    spawn(command, args, { stdio: "ignore", detached: true }).on("error", () => void 0).unref();
+  } catch {
+  }
+}
+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 Novalink?");
+  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 Novalink.`);
+    return;
+  }
+  log(`
+Novalink 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,40 @@
+{
+  "name": "@novalinkai/mcp",
+  "version": "0.1.0",
+  "description": "Connect Claude Code, Cursor, Antigravity and other coding agents to Novalink, so they can plan, build and integrate workflows.",
+  "keywords": ["novalink", "mcp", "model-context-protocol", "claude-code", "cursor", "antigravity", "workflows", "ai-agents"],
+  "homepage": "https://novalink.live/developers/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OshadhaVimuB/Nova-Link.git",
+    "directory": "packages/mcp"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "novalink-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skill"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "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": "^3.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: novalink-workflows
+description: Plan, build, test, publish and integrate Novalink AI workflows into this codebase through the Novalink MCP server. Use when the user wants to automate a task, build an AI agent workflow, or call a Novalink workflow from their code.
+---
+
+# Building Novalink workflows
+
+Novalink runs AI agent workflows: a trigger, then nodes (agents, app actions, HTTP calls, logic) joined by edges. You build them through the Novalink 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 `NOVALINK_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 Novalink and allow it.