linkbreakers-mcp 0.0.0-stage → 1.162.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linkbreakers
+
+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

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# linkbreakers-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local stdio bridge to the hosted [Linkbreakers](https://linkbreakers.com) MCP server at `https://mcp.linkbreakers.com`, for MCP clients that can only start local (stdio) servers.
+
+If your client supports remote MCP servers, connect it to `https://mcp.linkbreakers.com` directly instead. See the [setup guide](https://linkbreakers.com/help/article/mcp-server-setup).
+
+Tools, resources and their schemas come from the hosted server: this package forwards every request unchanged, so it always matches what `https://mcp.linkbreakers.com` serves.
+
+## Setup
+
+```json
+{
+  "mcpServers": {
+    "linkbreakers": {
+      "command": "npx",
+      "args": ["-y", "linkbreakers-mcp"]
+    }
+  }
+}
+```
+
+### Authentication
+
+- **OAuth (default):** on the first request, your browser opens the Linkbreakers sign-in. Once you approve, the tools appear. Tokens are stored in `~/.config/linkbreakers/mcp-oauth.json` and refreshed automatically.
+- **API token:** set `LINKBREAKERS_API_TOKEN` to a workspace API token from the [dashboard](https://app.linkbreakers.com) to skip the browser.
+
+```json
+{
+  "mcpServers": {
+    "linkbreakers": {
+      "command": "npx",
+      "args": ["-y", "linkbreakers-mcp"],
+      "env": { "LINKBREAKERS_API_TOKEN": "your-workspace-token" }
+    }
+  }
+}
+```
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `LINKBREAKERS_API_TOKEN` | unset | Workspace API token, sent as a bearer token |
+| `LINKBREAKERS_MCP_URL` | `https://mcp.linkbreakers.com` | Server to forward to |
+| `LINKBREAKERS_MCP_CALLBACK_PORT` | `47823` | Local port for the OAuth redirect |
+
+Requires Node.js 18 or later.
+
+## Releases
+
+Each API release dispatches `update-sdk` to this repo. The [release workflow](.github/workflows/release.yml) sets the package to the API version, checks that the server answers an MCP `initialize` over stdio, publishes to npm through trusted publishing and tags `v<version>`.
+
+## License
+
+MIT

package/bin/linkbreakers-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../lib/proxy.js';
+
+main().catch((err) => {
+  process.stderr.write(`linkbreakers-mcp: ${err.message}\n`);
+  process.exit(1);
+});

package/lib/oauth.js

@@ -0,0 +1,159 @@
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const CALLBACK_PORT = Number(process.env.LINKBREAKERS_MCP_CALLBACK_PORT || 47823);
+const CALLBACK_PATH = '/callback';
+const LOGIN_TIMEOUT_MS = 10 * 60 * 1000;
+
+function storePath() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(base, 'linkbreakers', 'mcp-oauth.json');
+}
+
+function readStore(serverUrl) {
+  try {
+    return JSON.parse(readFileSync(storePath(), 'utf8'))[serverUrl] ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function writeStore(serverUrl, patch) {
+  const path = storePath();
+  let all = {};
+  try {
+    all = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {}
+  all[serverUrl] = { ...all[serverUrl], ...patch };
+  for (const [key, value] of Object.entries(all[serverUrl])) {
+    if (value === undefined) delete all[serverUrl][key];
+  }
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, JSON.stringify(all, null, 2), { mode: 0o600 });
+}
+
+export function hasStoredTokens(serverUrl) {
+  return Boolean(readStore(serverUrl).tokens);
+}
+
+export function openBrowser(url) {
+  const [cmd, args] =
+    process.platform === 'darwin'
+      ? ['open', [url]]
+      : process.platform === 'win32'
+        ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+        : ['xdg-open', [url]];
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch {}
+}
+
+export class FileOAuthProvider {
+  constructor(serverUrl, version) {
+    this.serverUrl = serverUrl;
+    this.version = version;
+    this.authorizationUrl = undefined;
+    this._state = undefined;
+    this._verifier = undefined;
+  }
+
+  get redirectUrl() {
+    return `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`;
+  }
+
+  get clientMetadata() {
+    return {
+      client_name: 'Linkbreakers MCP (stdio)',
+      client_uri: 'https://linkbreakers.com',
+      software_id: 'linkbreakers-mcp',
+      software_version: this.version,
+      redirect_uris: [this.redirectUrl],
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+      token_endpoint_auth_method: 'none',
+    };
+  }
+
+  state() {
+    this._state = randomBytes(16).toString('hex');
+    return this._state;
+  }
+
+  clientInformation() {
+    const info = readStore(this.serverUrl).clientInformation;
+    if (info && info.redirect_uris && !info.redirect_uris.includes(this.redirectUrl)) return undefined;
+    return info;
+  }
+
+  saveClientInformation(clientInformation) {
+    writeStore(this.serverUrl, { clientInformation });
+  }
+
+  tokens() {
+    return readStore(this.serverUrl).tokens;
+  }
+
+  saveTokens(tokens) {
+    writeStore(this.serverUrl, { tokens });
+  }
+
+  redirectToAuthorization(authorizationUrl) {
+    this.authorizationUrl = authorizationUrl.toString();
+  }
+
+  saveCodeVerifier(codeVerifier) {
+    this._verifier = codeVerifier;
+  }
+
+  codeVerifier() {
+    if (!this._verifier) throw new Error('no PKCE code verifier for this sign-in');
+    return this._verifier;
+  }
+
+  invalidateCredentials(scope) {
+    if (scope === 'all') writeStore(this.serverUrl, { clientInformation: undefined, tokens: undefined });
+    if (scope === 'client') writeStore(this.serverUrl, { clientInformation: undefined });
+    if (scope === 'tokens') writeStore(this.serverUrl, { tokens: undefined });
+  }
+
+  waitForCallback() {
+    const expectedState = this._state;
+    return new Promise((resolve, reject) => {
+      const server = createServer((req, res) => {
+        const url = new URL(req.url || '/', this.redirectUrl);
+        if (url.pathname !== CALLBACK_PATH) {
+          res.writeHead(404).end();
+          return;
+        }
+        const code = url.searchParams.get('code');
+        const error = url.searchParams.get('error');
+        const ok = code && (!expectedState || url.searchParams.get('state') === expectedState);
+        res.writeHead(ok ? 200 : 400, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(
+          ok
+            ? '<p>Linkbreakers is connected. You can close this tab and return to your MCP client.</p>'
+            : `<p>Linkbreakers sign-in failed: ${error ? String(error).replace(/[<>&"]/g, '') : 'invalid callback'}.</p>`,
+        );
+        clearTimeout(timer);
+        server.close();
+        if (ok) resolve(code);
+        else reject(new Error(`OAuth sign-in failed: ${error || 'invalid callback'}`));
+      });
+      const timer = setTimeout(() => {
+        server.close();
+        reject(new Error('OAuth sign-in timed out'));
+      }, LOGIN_TIMEOUT_MS);
+      server.on('error', (err) => {
+        clearTimeout(timer);
+        reject(new Error(`could not listen for the OAuth callback on ${this.redirectUrl}: ${err.message}`));
+      });
+      server.listen(CALLBACK_PORT, '127.0.0.1');
+    });
+  }
+}

package/lib/proxy.js

@@ -0,0 +1,134 @@
+import { readFileSync } from 'node:fs';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { McpError, ResultSchema } from '@modelcontextprotocol/sdk/types.js';
+import { FileOAuthProvider, hasStoredTokens, openBrowser } from './oauth.js';
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const SERVER_URL = new URL(process.env.LINKBREAKERS_MCP_URL || 'https://mcp.linkbreakers.com');
+const TOKEN = process.env.LINKBREAKERS_API_TOKEN?.trim();
+const REQUEST_TIMEOUT_MS = 5 * 60 * 1000;
+const AUTH_REQUIRED = -32001;
+const DEFAULT_CAPABILITIES = { tools: { listChanged: true }, resources: { listChanged: true } };
+
+const log = (message) => process.stderr.write(`linkbreakers-mcp: ${message}\n`);
+
+export async function main() {
+  const oauth = TOKEN ? undefined : new FileOAuthProvider(SERVER_URL.href, version);
+  let server;
+  let remote;
+  let connecting;
+  let signIn;
+
+  const transportOptions = TOKEN
+    ? { requestInit: { headers: { Authorization: `Bearer ${TOKEN}` } } }
+    : { authProvider: oauth };
+
+  async function connectRemote(transport = new StreamableHTTPClientTransport(SERVER_URL, transportOptions)) {
+    const client = new Client({ name: 'linkbreakers-mcp', version }, { capabilities: {} });
+    client.fallbackNotificationHandler = async (notification) => {
+      await server?.notification(notification).catch(() => {});
+    };
+    client.onclose = () => {
+      if (remote === client) remote = undefined;
+    };
+    try {
+      await client.connect(transport);
+    } catch (err) {
+      if (oauth && err instanceof UnauthorizedError && oauth.authorizationUrl) startSignIn(transport);
+      throw err;
+    }
+    return client;
+  }
+
+  function startSignIn(transport) {
+    if (signIn) return;
+    const url = oauth.authorizationUrl;
+    const callback = oauth.waitForCallback();
+    log(`sign in to Linkbreakers to continue: ${url}`);
+    openBrowser(url);
+    signIn = callback
+      .then((code) => transport.finishAuth(code))
+      .then(() => connectRemote())
+      .then(async (client) => {
+        remote = client;
+        log('signed in to Linkbreakers');
+        await server.sendToolListChanged().catch(() => {});
+        await server.sendResourceListChanged().catch(() => {});
+      })
+      .catch((err) => log(err.message))
+      .finally(() => {
+        signIn = undefined;
+      });
+  }
+
+  function authError() {
+    const url = oauth?.authorizationUrl;
+    return new McpError(
+      AUTH_REQUIRED,
+      TOKEN
+        ? 'Linkbreakers rejected LINKBREAKERS_API_TOKEN. Create a workspace API token at https://app.linkbreakers.com, or unset it to sign in with OAuth.'
+        : `Linkbreakers sign-in required. Finish the OAuth sign-in opened in your browser${url ? ` (${url})` : ''}, or set LINKBREAKERS_API_TOKEN to a workspace API token. Tools appear once you are signed in.`,
+    );
+  }
+
+  async function ensureRemote() {
+    if (remote) return remote;
+    if (signIn) throw authError();
+    connecting ??= connectRemote().finally(() => {
+      connecting = undefined;
+    });
+    try {
+      remote = await connecting;
+      return remote;
+    } catch (err) {
+      if (err instanceof UnauthorizedError || err?.code === 401) throw authError();
+      throw new McpError(-32603, `Could not reach ${SERVER_URL.href}: ${err.message}`);
+    }
+  }
+
+  if (TOKEN || hasStoredTokens(SERVER_URL.href)) {
+    try {
+      remote = await connectRemote();
+    } catch (err) {
+      log(`could not connect yet (${err.message}); retrying on the first request`);
+    }
+  }
+
+  server = new Server(
+    { name: 'linkbreakers-mcp', title: 'Linkbreakers MCP', version, websiteUrl: 'https://linkbreakers.com' },
+    {
+      capabilities: remote?.getServerCapabilities() ?? DEFAULT_CAPABILITIES,
+      instructions: remote?.getInstructions(),
+    },
+  );
+
+  server.fallbackRequestHandler = async (request, extra) => {
+    const client = await ensureRemote();
+    const progressToken = request.params?._meta?.progressToken;
+    return client.request({ method: request.method, params: request.params }, ResultSchema, {
+      signal: extra.signal,
+      timeout: REQUEST_TIMEOUT_MS,
+      resetTimeoutOnProgress: true,
+      onprogress:
+        progressToken === undefined
+          ? undefined
+          : (progress) =>
+              server.notification({ method: 'notifications/progress', params: { ...progress, progressToken } }).catch(() => {}),
+    });
+  };
+
+  server.fallbackNotificationHandler = async (notification) => {
+    await remote?.notification(notification).catch(() => {});
+  };
+
+  server.onclose = async () => {
+    await remote?.close().catch(() => {});
+    process.exit(0);
+  };
+
+  await server.connect(new StdioServerTransport());
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "linkbreakers-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.162.0",
+  "mcpName": "com.linkbreakers/mcp",
+  "description": "Local stdio bridge to the Linkbreakers MCP server (https://mcp.linkbreakers.com) for MCP clients that only run local servers.",
+  "keywords": [
+    "linkbreakers",
+    "mcp",
+    "model-context-protocol",
+    "qr-code",
+    "lead-capture"
+  ],
+  "homepage": "https://linkbreakers.com/mcp",
+  "bugs": "https://github.com/linkbreakers-com/linkbreakers-mcp/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linkbreakers-com/linkbreakers-mcp.git"
+  },
+  "license": "MIT",
+  "author": "Linkbreakers <support@linkbreakers.com>",
+  "type": "module",
+  "bin": {
+    "linkbreakers-mcp": "bin/linkbreakers-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1"
+  }
+}