@spendctl/mcp-server 0.0.0-stage → 0.1.0

package/bin/spendctl-mcp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const { serveStdio } = await import("../dist/index.js");
+await serveStdio();

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type AgentClientOptions } from "@spendctl/client";
+/**
+ * MCP tools that let an agent spend through spendctl. The server is a thin client
+ * of the sidecar: it holds no keys and cannot approve anything. Identity comes
+ * from SPENDCTL_AGENT (+ SPENDCTL_AGENT_TOKEN) or the options.
+ */
+export declare function createMcpServer(options?: AgentClientOptions): McpServer;
+export declare function serveStdio(options?: AgentClientOptions): Promise<McpServer>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAe,KAAK,kBAAkB,EAAe,MAAM,kBAAkB,CAAC;AASrF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,kBAAuB,GAAG,SAAS,CA6G3E;AAED,wBAAsB,UAAU,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,SAAS,CAAC,CAIrF"}

package/dist/index.js

@@ -0,0 +1,110 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { AgentClient, readRefusal } from "@spendctl/client";
+import { z } from "zod";
+const MAX_BODY_CHARS = 20_000;
+function text(content, isError = false) {
+    return { content: [{ type: "text", text: content }], isError };
+}
+/**
+ * MCP tools that let an agent spend through spendctl. The server is a thin client
+ * of the sidecar: it holds no keys and cannot approve anything. Identity comes
+ * from SPENDCTL_AGENT (+ SPENDCTL_AGENT_TOKEN) or the options.
+ */
+export function createMcpServer(options = {}) {
+    const client = new AgentClient(options);
+    const server = new McpServer({ name: "spendctl", version: "0.1.0" });
+    server.registerTool("pay", {
+        title: "Fetch a paid URL",
+        description: "Fetch an HTTP(S) URL that may require payment (HTTP 402: x402 or MPP). spendctl applies your budget, allowlist and approval policy outside your control, pays if allowed, and returns the response. If it refuses or needs a human, the result explains why — do not try to pay another way.",
+        inputSchema: {
+            url: z.string().url().describe("Absolute http(s) URL"),
+            method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET"),
+            headers: z.record(z.string(), z.string()).optional().describe("Extra request headers"),
+            body: z.string().optional().describe("Request body (for POST/PUT/PATCH)"),
+            idempotencyKey: z
+                .string()
+                .optional()
+                .describe("Reuse the same key when retrying so you are never charged twice"),
+            dryRun: z.boolean().optional().describe("Only report what spendctl would do; never pay"),
+        },
+        annotations: { openWorldHint: true },
+    }, async ({ url, method, headers, body, idempotencyKey, dryRun }) => {
+        const requestHeaders = new Headers(headers ?? {});
+        if (idempotencyKey)
+            requestHeaders.set("idempotency-key", idempotencyKey);
+        if (dryRun)
+            requestHeaders.set("x-spendctl-dry-run", "1");
+        let response;
+        try {
+            response = await client.fetch(url, { method, headers: requestHeaders, body });
+        }
+        catch (error) {
+            return text(`spendctl sidecar unreachable: ${error.message}. Ask a human to run \`spendctl start\`.`, true);
+        }
+        const refusal = await readRefusal(response);
+        if (refusal) {
+            const lines = [refusal.message];
+            if (refusal.approval)
+                lines.push(`Approval id: ${refusal.approval}. A human must run \`spendctl approve ${refusal.approval}\`.`);
+            if (refusal.attempt)
+                lines.push(`Ledger entry: ${refusal.attempt}`);
+            return text(lines.join("\n"), refusal.error !== "spendctl_dry_run");
+        }
+        const payload = await response.text();
+        const decision = response.headers.get("x-spendctl-decision");
+        const amount = response.headers.get("x-spendctl-amount");
+        const summary = decision
+            ? `HTTP ${response.status} · paid ${amount ?? "?"} (${decision}) · receipt ${response.headers.get("x-spendctl-attempt")}`
+            : `HTTP ${response.status} · no payment needed`;
+        const clipped = payload.length > MAX_BODY_CHARS ? `${payload.slice(0, MAX_BODY_CHARS)}\n…[truncated]` : payload;
+        return text(`${summary}\n\n${clipped}`, !response.ok);
+    });
+    server.registerTool("check_budget", {
+        title: "Check remaining budget",
+        description: "Show this agent's spending limits, what has been spent in each window, and what is left.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        try {
+            const budget = await client.budget();
+            const lines = [
+                `Agent: ${budget.agent} (${budget.mode})`,
+                `Per request: ${budget.perRequest ?? "no limit"}`,
+                `Human approval at or above: ${budget.requireApprovalAbove ?? "never"}`,
+                `When a budget would be exceeded: ${budget.onBudgetExceeded === "approve" ? "ask a human" : "refuse"}`,
+                `Allowed hosts: ${budget.allow.join(", ")}`,
+                ...budget.windows.map((w) => `${w.window}: spent ${w.spent} of ${w.limit}, ${w.remaining} left`),
+            ];
+            return text(lines.join("\n"));
+        }
+        catch (error) {
+            return text(error.message, true);
+        }
+    });
+    server.registerTool("list_receipts", {
+        title: "List receipts",
+        description: "List this agent's recent payment attempts (paid, refused, waiting for approval) with amounts and transaction hashes.",
+        inputSchema: { limit: z.number().int().min(1).max(100).default(10) },
+        annotations: { readOnlyHint: true },
+    }, async ({ limit }) => {
+        try {
+            const receipts = await client.receipts(limit);
+            if (!receipts.length)
+                return text("No payments yet.");
+            return text(receipts
+                .map((r) => `${r.created_at_utc} ${r.id} ${r.method} ${r.host}${r.path} ${r.usd_value ? `$${r.usd_value}` : "-"} ${r.status}${r.tx_hash ? ` tx ${r.tx_hash}` : r.reasons ? ` (${r.reasons})` : ""}`)
+                .join("\n"));
+        }
+        catch (error) {
+            return text(error.message, true);
+        }
+    });
+    return server;
+}
+export async function serveStdio(options = {}) {
+    const server = createMcpServer(options);
+    await server.connect(new StdioServerTransport());
+    return server;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@spendctl/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "MCP server exposing spendctl to agents: pay, check_budget, list_receipts. Holds no keys.",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "spendctl-mcp": "./bin/spendctl-mcp.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "THIRD_PARTY_NOTICES"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "@spendctl/client": "^0.1.0",
+    "zod": "^4.6.7"
+  },
+  "homepage": "https://spendctl.dev",
+  "scripts": {}
 }