@tuppence/mcp 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @tuppence/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.
+Tuppence's MCP tools for clients that only speak **stdio**. Tuppence's MCP server is remote
+(`https://api.tuppence.ai/mcp`); this is a small local server that forwards to it with your key,
+so the tools are exactly the remote ones, scoped to what that key may do.
+
+Clients that support remote (HTTP) MCP servers don't need this: point them at
+`https://api.tuppence.ai/mcp` with an `Authorization: Bearer <key>` header.
+
+## Claude Code
+
+```sh
+claude mcp add tuppence --env TUPPENCE_API_KEY=sk_test_… -- npx -y @tuppence/mcp
+```
+
+## Claude Desktop / Cursor (`mcpServers` config)
+
+```json
+{
+  "mcpServers": {
+    "tuppence": {
+      "command": "npx",
+      "args": ["-y", "@tuppence/mcp"],
+      "env": { "TUPPENCE_API_KEY": "sk_test_…" }
+    }
+  }
+}
+```
+
+Use a **restricted key** (`rk_…`) with only the scopes the agent needs: it will only see the
+tools those scopes allow. Prefer `TUPPENCE_API_KEY` to `--api-key`: command lines are visible to
+other processes. `TUPPENCE_API_URL` (or `--api-url`) points it somewhere other than production.

package/dist/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * `npx @tuppence/mcp` — Tuppence's MCP server for clients that only speak stdio (plan 11-07).
+ *
+ * Tuppence's MCP server is remote (`POST https://api.tuppence.ai/mcp`, streamable HTTP). This
+ * is a local stdio server that forwards `tools/list` and `tools/call` to it, authenticated with
+ * your API key — so the tools, their scopes and their behaviour are exactly the remote ones.
+ *
+ *   TUPPENCE_API_KEY=sk_test_… npx @tuppence/mcp
+ *
+ * Prefer the environment variable to `--api-key`: command lines are visible to every process
+ * on the machine.
+ *
+ * Tuppence Connect: `TUPPENCE_ACCOUNT=acct_…` (or `--account`) makes every tool act as that one
+ * of the key's connected accounts — the `Tuppence-Account` header on the connection.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.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 { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+const VERSION = "0.1.1";
+function option(name) {
+    const at = process.argv.indexOf(`--${name}`);
+    if (at >= 0)
+        return process.argv[at + 1];
+    const inline = process.argv.find((a) => a.startsWith(`--${name}=`));
+    return inline?.slice(name.length + 3);
+}
+/** Everything goes to stderr: stdout is the protocol. */
+const fail = (message) => {
+    process.stderr.write(`tuppence-mcp: ${message}\n`);
+    process.exit(1);
+};
+const apiKey = process.env.TUPPENCE_API_KEY ?? option("api-key");
+const apiUrl = (process.env.TUPPENCE_API_URL ??
+    option("api-url") ??
+    "https://api.tuppence.ai").replace(/\/+$/, "");
+if (!apiKey)
+    fail("set TUPPENCE_API_KEY (or pass --api-key) to a Tuppence secret or restricted key.");
+if (!/^(sk|rk)_(test|live)_/.test(apiKey)) {
+    fail("that is not a Tuppence secret or restricted key (sk_… / rk_…).");
+}
+const account = process.env.TUPPENCE_ACCOUNT ?? option("account");
+if (account !== undefined && !/^acct_\w+$/.test(account)) {
+    fail('TUPPENCE_ACCOUNT (or --account) is a connected account id: "acct_…".');
+}
+const remote = new Client({ name: "tuppence-mcp-stdio", version: VERSION });
+await remote
+    .connect(new StreamableHTTPClientTransport(new URL(`${apiUrl}/mcp`), {
+    requestInit: {
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            ...(account ? { "Tuppence-Account": account } : {}),
+        },
+    },
+}))
+    .catch((error) => fail(`could not reach ${apiUrl}/mcp: ${error.message}`));
+const local = new Server({ name: "tuppence", version: VERSION }, {
+    capabilities: { tools: {} },
+    instructions: "Tuppence: take payments, create payment links, refund, read balances and meter usage. Tools act as the API key this server was started with.",
+});
+local.setRequestHandler(ListToolsRequestSchema, (request) => remote.listTools(request.params));
+local.setRequestHandler(CallToolRequestSchema, (request) => remote.callTool(request.params));
+await local.connect(new StdioServerTransport());
+process.stdin.on("close", () => {
+    void remote.close().finally(() => process.exit(0));
+});

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@tuppence/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Tuppence's MCP server for clients that only speak stdio: a local proxy to the remote server.",
+  "license": "MIT",
+  "homepage": "https://docs.tuppence.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZenningAI/tuppence.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": "https://github.com/ZenningAI/tuppence/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "tuppence-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }