@novalinkai/mcp 0.1.1 → 0.1.2

package/README.md

@@ -1,12 +1,64 @@
-# @novalinkai/mcp
+# Novalink 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.
+[![npm version](https://img.shields.io/npm/v/@novalinkai/mcp.svg)](https://www.npmjs.com/package/@novalinkai/mcp)
+[![CI](https://github.com/Novalink-AI/mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Novalink-AI/mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Connect coding agents to [Novalink](https://novalink.live) so they can design, build, test and ship AI workflows, then integrate them into your codebase.
+
+This repository contains:
+
+- **`@novalinkai/mcp`**: a command-line tool that configures Claude Code, Cursor, Antigravity, VS Code and Windsurf to use the hosted Novalink MCP server. It also includes a local stdio bridge for clients that cannot authenticate to remote servers.
+- **The `novalink-workflows` skill**: guidance that teaches agents the Novalink 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 Novalink 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 Novalink workflow. You can open it on the canvas, inspect its runs, and edit it like any other.
+
+## Requirements
+
+- A [Novalink](https://novalink.live) 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 @novalinkai/mcp install
 ```
 
-Any package runner works:
+The installer detects your editors, adds the Novalink server to each one, and installs the `/novalink-workflows` guide. It writes configuration only, never credentials, so the generated files are safe to commit.
+
+The first time your agent calls Novalink, 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 `/novalink-workflows` directly.
+
+The installer runs with any package runner:
 
 ```sh
 pnpm dlx @novalinkai/mcp install
@@ -14,78 +66,201 @@ 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.
+## Installation options
 
-### Claude Code plugin
-
-In Claude Code you can install Novalink as a plugin instead. It bundles the server and the skill, and updates with the plugin:
+### Choose editors and scope
 
-```
-/plugin marketplace add Novalink-AI/mcp
-/plugin install novalink@novalink
+```sh
+npx @novalinkai/mcp install --client claude-code,cursor   # specific editors
+npx @novalinkai/mcp install --scope user                  # all projects, not only this repository
+npx @novalinkai/mcp install --dry-run                     # preview changes without writing
+npx @novalinkai/mcp uninstall                             # remove the configuration
 ```
 
-## What gets written
+The installer writes to these locations:
 
-| Editor | Server config | Guide |
+| Client | Server configuration | Guide |
 |---|---|---|
-| Claude Code | `.mcp.json`, or `claude mcp add` for `--scope user` | `.claude/skills/novalink-workflows/SKILL.md` |
+| Claude Code | `.mcp.json`, or `claude mcp add` with `--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.
+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
 
-## Options
+In Claude Code, you can install Novalink as a plugin. The plugin bundles the server configuration and the skill, and updates through the plugin system:
 
 ```
-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
+/plugin marketplace add Novalink-AI/mcp
+/plugin install novalink@novalink
 ```
 
-## The stdio bridge
+### Manual configuration
 
-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.
+The server endpoint is `https://api.novalink.live/mcp`, using the Streamable HTTP transport with OAuth 2.1.
+
+Claude Code:
 
 ```sh
-npx @novalinkai/mcp login    # sign in ahead of time
-npx @novalinkai/mcp status
-npx @novalinkai/mcp logout   # revoke and forget the tokens
+claude mcp add --transport http --scope user novalink https://api.novalink.live/mcp
 ```
 
-Set `NOVALINK_MCP_URL` (or `NOVALINK_API_URL`) to point at another deployment, such as `http://localhost:8000/mcp` in development.
+Cursor (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "novalink": { "url": "https://api.novalink.live/mcp" }
+  }
+}
+```
+
+VS Code (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "novalink": { "type": "http", "url": "https://api.novalink.live/mcp" }
+  }
+}
+```
+
+Clients without remote OAuth support can use the stdio bridge:
+
+```json
+{
+  "mcpServers": {
+    "novalink": { "command": "npx", "args": ["-y", "@novalinkai/mcp@latest", "serve"] }
+  }
+}
+```
+
+## How it works
+
+```
+Coding agent --- MCP over HTTPS ---------------------> api.novalink.live/mcp ---> your Novalink account
+      |                                                        ^
+      +--- stdio ---> novalink-mcp serve (local bridge) -------+
+```
+
+- **Hosted server.** Novalink 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.** `novalink-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 `novalink-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
 
-At sign-in you choose what the agent may do:
+You choose the permissions on the consent screen when the agent first connects.
 
-- **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.
+| 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 disconnect an agent at any time, go to **API keys > Connected agents** in Novalink.
+To review or revoke connected agents, open **API keys > Connected agents** in Novalink. Revocation takes effect immediately.
 
-Docs: https://novalink.live/developers/mcp
+## CLI reference
+
+```
+novalink-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 |
+|---|---|
+| `NOVALINK_MCP_URL` | MCP server URL, for example `http://localhost:8000/mcp` |
+| `NOVALINK_API_URL` | API base URL; `/mcp` is appended |
+| `NOVALINK_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/novalink/credentials.json`, or `%APPDATA%\novalink` 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 Novalink from your editor and grant the scope named in the message. With the bridge, run `npx @novalinkai/mcp logout`, then `login`.
+
+**Connecting to a local or self-hosted deployment.** Set `NOVALINK_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/Novalink-AI/mcp.git
+cd mcp
 npm ci
 npm test
 npm run build
 NOVALINK_MCP_URL=http://localhost:8000/mcp node dist/cli.js install --dry-run
 ```
 
-The skill in `skills/novalink-workflows/SKILL.md` is the source for every editor's guide, the Claude Code plugin, and the `design_workflow` prompt the Novalink server serves.
+`skills/novalink-workflows/SKILL.md` is the single source for the guide. The installer, the Claude Code plugin and the Novalink 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`.
 
-To release, bump the version in `package.json`, `src/constants.ts` and `.claude-plugin/*.json`, then push a tag such as `v0.1.2`.
+The release workflow publishes to npm through trusted publishing, with provenance.
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { spawn, spawnSync } from "child_process";
+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";
@@ -17,16 +17,35 @@ import { dirname, join } from "path";
 
 // src/constants.ts
 var PACKAGE = "@novalinkai/mcp";
-var VERSION = "0.1.1";
+var VERSION = "0.1.2";
 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";
+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) {
-  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;
+  let url = DEFAULT_URL;
+  if (flag) url = flag.replace(/\/$/, "");
+  else if (env.NOVALINK_MCP_URL) url = env.NOVALINK_MCP_URL.replace(/\/$/, "");
+  else if (env.NOVALINK_API_URL) url = `${env.NOVALINK_API_URL.replace(/\/$/, "")}/mcp`;
+  return checkUrl(url, "The Novalink server URL");
 }
 function log(message) {
   process.stderr.write(`${message}
@@ -44,7 +63,6 @@ var TokenStore = class {
   constructor(path) {
     this.path = path;
   }
-  path;
   readAll() {
     if (!existsSync(this.path)) return {};
     try {
@@ -93,7 +111,9 @@ async function discover(url, fetchFn) {
     `${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 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}`,
@@ -103,6 +123,10 @@ async function discover(url, fetchFn) {
   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) {
@@ -254,9 +278,6 @@ var Bridge = class {
     this.deps = deps;
     this.write = write;
   }
-  url;
-  deps;
-  write;
   signingIn;
   protocolVersion;
   async token() {
@@ -331,6 +352,22 @@ async function serve(url, deps) {
   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";
 
@@ -549,13 +586,6 @@ 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 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novalinkai/mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Connect Claude Code, Cursor, Antigravity and other coding agents to Novalink, so they can plan, build and integrate workflows.",
   "keywords": [
     "novalink",
@@ -42,7 +42,7 @@
     "@types/node": "^22.0.0",
     "tsup": "^8.5.0",
     "typescript": "^5.9.0",
-    "vitest": "^3.2.0"
+    "vitest": "^5.0.2"
   },
   "publishConfig": {
     "access": "public",