urlpivot-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 URLPivot contributors
+
+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,68 @@
+# URLPivot MCP
+
+Keep the same public link and QR while your campaign destination changes. Connect your desktop agent to your URLPivot workspace to manage links, generate QR codes, prepare private Pages and review campaign traffic.
+
+The hosted endpoint is available at `https://urlpivot.app/api/agent/mcp`. Native HTTP clients can connect directly; this package provides a stdio bridge for desktop clients.
+
+## Choose your connection
+
+- Native HTTP clients: use `https://urlpivot.app/api/agent/mcp` and `Authorization: Bearer <workspace token>`. No installation required.
+- Local stdio clients, including Claude Desktop configurations: this package bridges to the same hosted service using the official MCP SDK. It does not replace the service or host your data locally.
+- Browser connectors that require OAuth: not supported by this Bearer-token bridge. This is not a Claude.ai or ChatGPT OAuth connector.
+
+## Start in five minutes
+
+1. Sign in at [URLPivot](https://urlpivot.app/login) and open the desired workspace.
+2. Open **AI agents → Agent access**. Create a workspace token with only the permissions you need. For your first connection, choose **Read only**.
+3. Store the token in the client's private environment as `URLPIVOT_TOKEN`. Never paste it into a conversation, URL, QR code or command argument.
+4. Configure an MCP stdio client (Node.js 22 or later):
+
+```json
+{
+  "mcpServers": {
+    "urlpivot": {
+      "command": "npx",
+      "args": ["-y", "urlpivot-mcp@0.1.0"],
+      "env": { "URLPIVOT_TOKEN": "upv_YOUR_TOKEN" }
+    }
+  }
+}
+```
+
+Replace the placeholder only in your private client configuration. Restart the client, then read `urlpivot://capabilities` and run `tools/list`. The exposed tools depend on your token, workspace plan and backend; the public catalog is not an authorization grant.
+
+To run from source, use `node /absolute/path/to/packages/mcp/bin/urlpivot-mcp.mjs` as your client's command after `npm ci --ignore-scripts` in this package directory. No token is needed for `--help` or `--version`.
+
+## Useful first tasks
+
+- **Workspace checkup:** “Review my links, active campaigns and configured expiry. Prioritize what I should fix. Make no changes.”
+- **Campaign setup:** “Prepare a Facebook campaign link. Suggest UTMs, show the final destination before saving, then return the short link and QR if my token permits it.”
+- **Traffic review:** “Compare the available completed days for this campaign. Separate human clicks and bots, explain retention and suggest one next action.”
+- **Private Page draft:** “Prepare a private Page from my existing links and approved brief. Return the editor URL for review. Do not publish.”
+
+Native `prompts/list` / `prompts/get` become available when the connected server advertises prompts. Until then, use the text requests above with existing tools. This package forwards only advertised features and works with servers that expose tools/resources without prompts.
+
+## Permissions and limitations
+
+The hosted catalog has 27 tools for workspace links, folders, QR, Pages, images, analytics, audit, domains and billing-access reads. Your token may expose fewer. New tools do not silently expand existing tokens. Page edits require the saved revision; publishing requires separate publication permissions. Domain tools return DNS/certificate instructions and request reconciliation; they do not edit DNS.
+
+No billing mutations, account administration, workspace switching, bulk deletion, arbitrary browser access or native AI Page generation are provided by this package. Analytics counts retained classified events, not unique visitors or sales. A Free workspace can begin using scoped tools; paid product limits still apply. Installing the bridge does not upgrade a plan.
+
+## Troubleshooting
+
+- Cannot connect / 401: check the endpoint, token validity and revocation.
+- Permission failure / 403: check the token scopes and workspace plan; never try another workspace to bypass a denial.
+- Stale Page revision: read the Page again before editing.
+- Uncertain or timed-out write: read back before a manual retry. This bridge does not automatically retry writes.
+- Native HTTP works but desktop does not: check Node.js 22+, private environment and the client's stdio config. Windows clients may require the absolute path to `npx.cmd`.
+- Prompts missing: use `prompts/list` only when initialization advertises prompts. Older server versions have tools/resources without prompts.
+
+`URLPIVOT_MCP_URL` optionally selects a trusted endpoint. HTTPS is required except loopback HTTP for development. URL credentials, query strings and fragments are rejected; redirects are rejected. Tokens are sent only as Authorization headers. No local token storage, telemetry or analytics collection is added by the bridge.
+
+## Contribute and get help
+
+[Connection guide and tool catalog](https://urlpivot.app/agents) · [Machine-readable guide](https://urlpivot.app/llms.txt) · [Support](https://urlpivot.app/support)
+
+For a bug report, include the package version, Node/client version, operation, sanitized error code and steps to reproduce. Omit tokens and private visitor data. Public repository/contribution links will be added after their actual publication; no community membership or certification is implied.
+
+License: MIT for this bridge. URLPivot hosted service terms and plan limits remain separate.

package/bin/urlpivot-mcp.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createBridge, readBridgeConfig, VERSION } from '../src/bridge.mjs';
+
+if (process.argv.includes('--help')) {
+  console.log('URLPivot MCP bridge\n\nSet URLPIVOT_TOKEN in your client private environment.\nURLPIVOT_MCP_URL is optional (default https://urlpivot.app/api/agent/mcp).\nRun without arguments for MCP stdio. Use --version for package version.');
+} else if (process.argv.includes('--version')) {
+  console.log(VERSION);
+} else if (process.argv.length > 2) {
+  console.error('No command arguments accepted. Store the token in URLPIVOT_TOKEN, never on the command line.');
+  process.exitCode = 1;
+} else {
+  let bridge;
+  try {
+    bridge = await createBridge(readBridgeConfig());
+    const stop = async () => { await bridge.close(); process.exitCode = 0; };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    process.stdin.once('end', stop);
+    await bridge.server.connect(new StdioServerTransport());
+  } catch (error) {
+    await bridge?.close();
+    // Only our controlled startup messages are allowed here. Never echo a token or upstream body.
+    console.error(error instanceof Error && /^(Set URLPIVOT_TOKEN|URLPIVOT_MCP_URL|Use HTTPS|Cannot connect to URLPivot)/.test(error.message)
+      ? error.message : 'URLPivot MCP could not start. Check the private client configuration.');
+    process.exitCode = 1;
+  }
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "urlpivot-mcp",
+  "version": "0.1.0",
+  "mcpName": "app.urlpivot/mcp",
+  "description": "Connect MCP desktop agents to URLPivot links, QR codes, Pages and campaign analytics using a scoped workspace token.",
+  "type": "module",
+  "bin": { "urlpivot-mcp": "bin/urlpivot-mcp.mjs" },
+  "exports": "./src/bridge.mjs",
+  "files": ["bin", "src", "README.md", "LICENSE"],
+  "engines": { "node": ">=22" },
+  "scripts": { "test": "node --test test/*.test.mjs", "start": "node bin/urlpivot-mcp.mjs" },
+  "keywords": ["mcp", "model-context-protocol", "urlpivot", "link-management", "qr-code", "campaign-analytics", "claude-desktop", "ai-agents"],
+  "homepage": "https://urlpivot.app/agents",
+  "bugs": { "url": "https://urlpivot.app/support" },
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "dependencies": { "@modelcontextprotocol/sdk": "1.32.0", "zod": "4.6.5" }
+}

package/src/bridge.mjs

@@ -0,0 +1,81 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport, StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema,
+  ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, McpError,
+} from '@modelcontextprotocol/sdk/types.js';
+
+export const VERSION = '0.1.0';
+export const DEFAULT_ENDPOINT = 'https://urlpivot.app/api/agent/mcp';
+
+export function readBridgeConfig(env = process.env) {
+  const token = env.URLPIVOT_TOKEN;
+  if (!token || !/^upv_[A-Za-z0-9_-]{16,512}$/.test(token)) throw new Error('Set URLPIVOT_TOKEN to a workspace agent token. Do not pass it in command arguments.');
+  let endpoint;
+  try { endpoint = new URL(env.URLPIVOT_MCP_URL || DEFAULT_ENDPOINT); }
+  catch { throw new Error('URLPIVOT_MCP_URL must be a valid HTTPS endpoint.'); }
+  const loopback = ['127.0.0.1', 'localhost', '[::1]'].includes(endpoint.hostname);
+  if ((endpoint.protocol !== 'https:' && !(endpoint.protocol === 'http:' && loopback)) || endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+    throw new Error('Use HTTPS (HTTP only on loopback), without credentials, query strings or fragments.');
+  }
+  return { endpoint, token };
+}
+
+/** No account switching, local persistence, telemetry or retry of tool mutations. */
+export async function createBridge(config, { fetch: fetchOverride } = {}) {
+  const remote = new Client({ name: 'urlpivot-mcp', version: VERSION }, { capabilities: {} });
+  const guardedFetch = async (url, init) => {
+    const response = await (fetchOverride || fetch)(url, { ...init, redirect: 'manual' });
+    if (response.status >= 300 && response.status < 400) {
+      await response.body?.cancel();
+      throw new Error('Endpoint redirects are not permitted.');
+    }
+    return response;
+  };
+  const transport = new StreamableHTTPClientTransport(config.endpoint, {
+    requestInit: { headers: { Authorization: `Bearer ${config.token}` }, redirect: 'error' },
+    fetch: guardedFetch,
+  });
+  // Never print raw transport failures, response bodies, headers or credentials.
+  remote.onerror = () => {};
+  try { await remote.connect(transport); }
+  catch { await remote.close().catch(() => {}); throw new Error('Cannot connect to URLPivot. Check the endpoint and token validity; no tool has been called.'); }
+  const capabilities = remote.getServerCapabilities() || {};
+  const server = new Server({ name: 'urlpivot-mcp', version: VERSION }, {
+    capabilities: {
+      ...(capabilities.tools ? { tools: {} } : {}),
+      ...(capabilities.resources ? { resources: {} } : {}),
+      ...(capabilities.prompts ? { prompts: {} } : {}),
+    },
+    instructions: remote.getInstructions(),
+  });
+  const forward = (run) => async (request, extra) => {
+    try { return await run(request.params, { signal: extra.signal, timeout: 60_000 }); }
+    catch (error) {
+      const code = error instanceof McpError ? error.code
+        : error instanceof UnauthorizedError ? -32001
+        : error instanceof StreamableHTTPError && error.code === 401 ? -32001
+        : error instanceof StreamableHTTPError && error.code === 403 ? -32003
+        : -32603;
+      throw new McpError(code, 'URLPivot request failed. Check token permissions, input and saved revision. A failed or timed-out write is not proof that it was not saved; read back before a manual retry.');
+    }
+  };
+  if (capabilities.tools) {
+    server.setRequestHandler(ListToolsRequestSchema, forward((params, options) => remote.listTools(params, options)));
+    server.setRequestHandler(CallToolRequestSchema, forward((params, options) => remote.callTool(params, undefined, options)));
+  }
+  if (capabilities.resources) {
+    server.setRequestHandler(ListResourcesRequestSchema, forward((params, options) => remote.listResources(params, options)));
+    server.setRequestHandler(ReadResourceRequestSchema, forward((params, options) => remote.readResource(params, options)));
+  }
+  if (capabilities.prompts) {
+    server.setRequestHandler(ListPromptsRequestSchema, forward((params, options) => remote.listPrompts(params, options)));
+    server.setRequestHandler(GetPromptRequestSchema, forward((params, options) => remote.getPrompt(params, options)));
+  }
+  return {
+    server,
+    async close() { await Promise.allSettled([server.close(), remote.close()]); },
+  };
+}