letagentpay-mcp 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# letagentpay-mcp
+
+MCP server for [LetAgentPay](https://letagentpay.com) — AI agent spending policy middleware. Works with Claude Desktop, Claude Code, Cursor, OpenClaw, and any MCP-compatible client.
+
+## Setup
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "letagentpay": {
+      "command": "npx",
+      "args": ["-y", "letagentpay-mcp"],
+      "env": {
+        "LETAGENTPAY_TOKEN": "agt_xxx"
+      }
+    }
+  }
+}
+```
+
+Get your agent token at [letagentpay.com](https://letagentpay.com) or from your self-hosted instance.
+
+### Self-hosted
+
+```json
+{
+  "mcpServers": {
+    "letagentpay": {
+      "command": "npx",
+      "args": ["-y", "letagentpay-mcp"],
+      "env": {
+        "LETAGENTPAY_TOKEN": "agt_xxx",
+        "LETAGENTPAY_API_URL": "http://localhost:8000/api/v1"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `request_purchase` | Submit a purchase request for policy evaluation |
+| `check_budget` | View current budget, spent, held, and remaining |
+| `list_categories` | List valid purchase categories |
+| `my_requests` | Check status of a specific purchase request |
+| `list_requests` | List purchase requests with optional status filter |
+| `confirm_purchase` | Confirm purchase completion (or failure) |
+
+Every purchase request goes through 8 deterministic policy checks: agent status, category, per-request limit, schedule, daily/weekly/monthly limits, and total budget.
+
+## Environment Variables
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `LETAGENTPAY_TOKEN` | Yes | — |
+| `LETAGENTPAY_API_URL` | No | `https://api.letagentpay.com/api/v1` |
+
+## SDKs
+
+For programmatic integration without MCP:
+
+- **Python**: `pip install letagentpay`
+- **TypeScript**: `npm install letagentpay`
+
+## Links
+
+- [LetAgentPay](https://letagentpay.com)
+- [GitHub](https://github.com/LetAgentPay/letagentpay)
+- [OpenClaw Skill](https://github.com/LetAgentPay/letagentpay-openclaw)
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createApiClient, createServer } from "./server.js";
+
+const TOKEN = process.env.LETAGENTPAY_TOKEN;
+const API_URL = process.env.LETAGENTPAY_API_URL || "https://api.letagentpay.com/api/v1";
+
+if (!TOKEN) {
+  console.error("LETAGENTPAY_TOKEN environment variable is required");
+  process.exit(1);
+}
+
+const apiCall = createApiClient(TOKEN, API_URL);
+const server = createServer(apiCall);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "letagentpay-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for LetAgentPay — AI agent spending policy middleware",
+  "main": "index.js",
+  "bin": {
+    "letagentpay-mcp": "./index.js"
+  },
+  "type": "module",
+  "files": [
+    "index.js",
+    "server.js"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": ["mcp", "letagentpay", "ai-agent", "purchases", "budget", "policy", "openclaw", "claude"],
+  "author": "LetAgentPay <hello@letagentpay.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LetAgentPay/letagentpay-mcp"
+  },
+  "homepage": "https://letagentpay.com",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "vitest": "^3.1.1"
+  }
+}

package/server.js

@@ -0,0 +1,140 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+export function createApiClient(token, apiUrl) {
+  return async function apiCall(path, options = {}) {
+    const res = await fetch(`${apiUrl}/agent-api${path}`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+        ...options.headers,
+      },
+      ...options,
+    });
+
+    const data = await res.json();
+    if (!res.ok) {
+      throw new Error(data.detail || `API error: ${res.status}`);
+    }
+    return data;
+  };
+}
+
+export function createServer(apiCall) {
+  const server = new McpServer({
+    name: "letagentpay",
+    version: "0.1.0",
+  });
+
+  server.tool(
+    "request_purchase",
+    "Request approval for a purchase. Returns request ID and status (auto_approved, pending, or rejected).",
+    {
+      amount: z.number().positive().describe("Purchase amount in account currency"),
+      category: z.string().describe("Purchase category (use list_categories to see valid options)"),
+      merchant_name: z.string().optional().describe("Merchant or store name"),
+      description: z.string().optional().describe("What is being purchased"),
+      agent_comment: z.string().optional().describe("Why this purchase is needed — shown to the human reviewer"),
+    },
+    async ({ amount, category, merchant_name, description, agent_comment }) => {
+      const result = await apiCall("/requests", {
+        method: "POST",
+        body: JSON.stringify({ amount, category, merchant_name, description, agent_comment }),
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  );
+
+  server.tool(
+    "check_budget",
+    "Check the current budget, amount spent, and remaining balance.",
+    {},
+    async () => {
+      const result = await apiCall("/budget");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Budget: $${result.budget}\nSpent: $${result.spent}\nRemaining: $${result.remaining}`,
+          },
+        ],
+      };
+    },
+  );
+
+  server.tool(
+    "list_categories",
+    "List all valid purchase categories.",
+    {},
+    async () => {
+      const result = await apiCall("/categories");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Valid categories:\n${result.categories.map((c) => `- ${c}`).join("\n")}`,
+          },
+        ],
+      };
+    },
+  );
+
+  server.tool(
+    "my_requests",
+    "Get the status of a specific purchase request by ID.",
+    {
+      request_id: z.string().describe("The purchase request ID"),
+    },
+    async ({ request_id }) => {
+      const result = await apiCall(`/requests/${request_id}`);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  );
+
+  server.tool(
+    "list_requests",
+    "List agent's purchase requests with optional status filter.",
+    {
+      status: z.string().optional().describe("Filter by status: pending, auto_approved, approved, rejected, expired, completed, failed"),
+      limit: z.number().optional().describe("Max results to return (default 20, max 100)"),
+      offset: z.number().optional().describe("Offset for pagination (default 0)"),
+    },
+    async ({ status, limit, offset }) => {
+      const params = new URLSearchParams();
+      if (status) params.set("status", status);
+      if (limit != null) params.set("limit", String(limit));
+      if (offset != null) params.set("offset", String(offset));
+      const query = params.toString();
+      const result = await apiCall(`/requests${query ? `?${query}` : ""}`);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  );
+
+  server.tool(
+    "confirm_purchase",
+    "Confirm that a purchase was completed (or failed). Call after an approved request.",
+    {
+      request_id: z.string().describe("The purchase request ID"),
+      success: z.boolean().describe("Whether the purchase was successful"),
+      actual_amount: z.number().optional().describe("Actual amount if different from requested"),
+      receipt_url: z.string().optional().describe("URL to receipt or confirmation"),
+    },
+    async ({ request_id, success, actual_amount, receipt_url }) => {
+      const result = await apiCall(`/requests/${request_id}/confirm`, {
+        method: "POST",
+        body: JSON.stringify({ success, actual_amount, receipt_url }),
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  );
+
+  return server;
+}