@curless/mcp-server 0.1.10

package/README.md

@@ -0,0 +1,244 @@
+# @curless/mcp-server
+
+MCP server that lets any local AI agent (Claude Desktop, Cursor, Cline,
+LangChain, custom Python script, …) drive a Curless wallet + virtual card to
+order coffee, book hotels, and buy office supplies through real merchant
+endpoints.
+
+> **v0.1 = single-user demo mode.** Every install shares the same demo
+> backend wallets. No real money — all charges are simulated. v0.2
+> introduces per-user API keys and real on-chain USDC.
+
+---
+
+## What you get
+
+18 MCP tools that wrap the Curless REST API:
+
+| Category | Tools |
+|---|---|
+| VCC | `create_vcc`, `top_up_vcc`, `update_vcc_limit`, `get_vcc_info` |
+| Wallet | `get_wallet_info`, `fund_wallet` |
+| Coffee (Nowwa) | `list_coffees`, `order_coffee` |
+| Hotel (Club Med) | `list_properties`, `list_rooms`, `book_room` |
+| Office supplies | `list_supplies`, `check_inventory`, `order_supplies`, `set_reorder_rule`, `list_supply_orders` |
+| Receipts | `list_transactions` |
+
+Each tool is a thin HTTPS wrapper — no LLM involvement inside the MCP
+server. Your local agent decides what to call.
+
+---
+
+## Install
+
+```bash
+npm install -g @curless/mcp-server
+```
+
+Or run on-demand via `npx`:
+
+```bash
+npx @curless/mcp-server
+```
+
+---
+
+## Configure your client
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "curless": {
+      "command": "npx",
+      "args": ["-y", "@curless/mcp-server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The 18 tools appear under the 🔌 menu.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "curless": {
+      "command": "npx",
+      "args": ["-y", "@curless/mcp-server"]
+    }
+  }
+}
+```
+
+### Cline (VS Code extension)
+
+Open the Cline panel → Settings → MCP Servers → paste the same JSON.
+
+### Custom (Python / LangChain / etc.)
+
+Spawn the binary with stdio transport. See the
+[MCP client examples](https://modelcontextprotocol.io/docs/clients) for
+your framework.
+
+---
+
+## Try it
+
+Once connected, ask your agent:
+
+- **"Create a VCC with a $50 limit"** → mints a card
+- **"Top up the card with $20"** → moves USDC wallet → card
+- **"Order a Coconut Latte"** → charges, returns order_id
+- **"Book Club Med Bali for June 1-4"** → real booking flow
+- **"A4 paper is running low, order 5 reams"** → procurement flow
+- **"What's my wallet balance?"** → quick check
+
+The agent will discover the right tool from the description. Names work
+in Chinese too: "订一杯椰漾拿铁", "帮我订巴厘岛 Club Med, 9月1日入住, 9月4日退房", etc.
+
+---
+
+## Configuration
+
+All optional, set as environment variables:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `CURLESS_BASE_URL` | `https://openclaw.curless.ai` | Backend host. Point to staging or a self-hosted Curless. |
+| `CURLESS_WALLET_ID` | `wal-002` | Which demo wallet to use. (`wal-001` TravelBot · `wal-002` ProcureAI · `wal-003` BookingBot · `wal-004` SupplyAgent) |
+| `CURLESS_AGENT_ID` | `agent-002` | Default agent identity stamped on minted VCCs. |
+| `CURLESS_STAMP_PREFIX` | `mcp` | Prefix on `agent_id` so MCP-originated records (e.g. `mcp-agent-002`) are distinguishable from web-UI traffic in the merchant dashboard. |
+| `CURLESS_AUTO_OPEN_URLS` | unset | If `true` or `1`, terminal actions (order_coffee / book_room / order_supplies) auto-launch the storefront confirmation page in the user's default browser. Off by default — the URL is still surfaced as a clickable link in the tool response. |
+
+### Storefront page after order
+
+The web UI animates an embedded iframe through `catalog → cart → order
+detail` after a successful purchase. Desktop MCP clients (Claude
+Desktop, Cursor, Cline) don't have an iframe context, so each terminal
+tool now returns a `view_url` plus a markdown `🔗 Open in browser:`
+content block that clients render as a clickable link. Click → real
+browser opens to the order page on nowwa / clubmed / procurement.
+
+For agents that should open the page without user interaction (kiosk
+demos, hands-free walkthroughs), set `CURLESS_AUTO_OPEN_URLS=true`.
+The MCP server then spawns the OS browser via `open` / `xdg-open` /
+`start` the moment a successful order returns.
+
+Example in `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "curless": {
+      "command": "npx",
+      "args": ["-y", "@curless/mcp-server"],
+      "env": {
+        "CURLESS_WALLET_ID": "wal-004",
+        "CURLESS_STAMP_PREFIX": "my-bot",
+        "CURLESS_AUTO_OPEN_URLS": "true"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Tool semantics
+
+### State maintained by the server
+
+The server keeps one piece of state in memory across tool calls: the
+**most recently created VCC id**. So a typical session looks like:
+
+```
+> Create a VCC for $100
+  → vcc-abc123 (server remembers this)
+> Top up the card with $30
+  → no vcc_id needed; uses vcc-abc123
+> Order a Cold Brew
+  → no vcc_id needed; uses vcc-abc123
+```
+
+If you have multiple VCCs in flight, pass `vcc_id` explicitly.
+
+### Per-tool agent stamping
+
+To keep merchant analytics sane, orders are tagged with the appropriate
+agent based on tool category:
+
+| Tool category | agent_id stamped on records |
+|---|---|
+| Coffee (`order_coffee`) | `${CURLESS_STAMP_PREFIX}-agent-002` |
+| Hotel (`book_room`) | `${CURLESS_STAMP_PREFIX}-agent-001` |
+| Supplies (`order_supplies`, `set_reorder_rule`, …) | `${CURLESS_STAMP_PREFIX}-agent-004` |
+| VCC mint | `${CURLESS_STAMP_PREFIX}-${CURLESS_AGENT_ID}` |
+
+With the default `STAMP_PREFIX=mcp`, your MCP-driven traffic is searchable
+as `mcp-agent-*` in the Curless merchant dashboard.
+
+### Scheduled orders
+
+`order_supplies` accepts `scheduled_for: "2026-07-21"`. Scheduled orders
+are queued, not charged immediately, and don't require a VCC.
+
+### Error envelope
+
+Every tool returns either a success object or an error envelope:
+
+```json
+{ "error": "insufficient_funds", "code": "VCC_INSUFFICIENT", "hint": "Top up via top_up_vcc and retry." }
+```
+
+`isError: true` is set on the MCP response so your client can short-circuit
+on failure.
+
+---
+
+## Limitations of v0.1
+
+- **Shared wallets.** All installs share `wal-001..wal-004`. Your agent can
+  see other users' orders. **Do not use real money.**
+- **No real money flow.** USDC transfers are simulated server-side. Card
+  charges go through `merchantChargeService` but no card rail is involved.
+- **No retries / circuit breaker.** The client makes one attempt per call
+  and surfaces the error.
+- **No webhook callbacks.** Long-running scheduled orders complete
+  silently — no push notifications.
+
+v0.2 will address these via API keys, real on-chain settlement, and
+webhook delivery.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/onelabs-spark/curless-agent-payment.git
+cd curless-agent-payment/mcp-server
+npm install
+npm run dev   # uses tsx — restart on save
+```
+
+To test against a local backend:
+
+```bash
+CURLESS_BASE_URL=http://localhost:3000 npm run dev
+```
+
+To smoke-test individual tools without a chat client, use any MCP
+inspector (e.g. `npx @modelcontextprotocol/inspector npx @curless/mcp-server`).
+
+---
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Thin HTTP client for the Curless REST API.
+ *
+ * v0.1 is single-user demo mode — there's no per-user authentication.
+ * Every install of this MCP server talks to the same shared Curless
+ * backend and uses the same demo wallets. Production multi-user mode
+ * will swap the constructor to take an API key and add Bearer auth.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+export interface CurlessClientOptions {
+    /** Base URL — defaults to env CURLESS_BASE_URL or production. */
+    baseUrl?: string;
+    /** Per-request timeout in ms. Defaults to 30s. */
+    timeoutMs?: number;
+}
+export declare class CurlessClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(opts?: CurlessClientOptions);
+    /** GET with optional query params. */
+    get<T = unknown>(path: string, params?: Record<string, unknown>): Promise<T>;
+    /** POST JSON body. */
+    post<T = unknown>(path: string, body: unknown): Promise<T>;
+    /** PUT JSON body. */
+    put<T = unknown>(path: string, body: unknown): Promise<T>;
+    private fetch;
+}
+/**
+ * Most Curless endpoints wrap their payload in `{ success, data }`.
+ * This helper peels that off, falling through if the response is
+ * already the bare object.
+ */
+export declare function unwrap<T>(res: unknown): T;

package/dist/client.js

@@ -0,0 +1,89 @@
+/**
+ * Thin HTTP client for the Curless REST API.
+ *
+ * v0.1 is single-user demo mode — there's no per-user authentication.
+ * Every install of this MCP server talks to the same shared Curless
+ * backend and uses the same demo wallets. Production multi-user mode
+ * will swap the constructor to take an API key and add Bearer auth.
+ */
+export class HttpError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        const preview = typeof body === 'string' ? body.slice(0, 200) : JSON.stringify(body).slice(0, 200);
+        super(`HTTP ${status}: ${preview}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'HttpError';
+    }
+}
+export class CurlessClient {
+    baseUrl;
+    timeoutMs;
+    constructor(opts = {}) {
+        const fromEnv = process.env.CURLESS_BASE_URL;
+        this.baseUrl = (opts.baseUrl ?? fromEnv ?? 'https://openclaw.curless.ai').replace(/\/$/, '');
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+    }
+    /** GET with optional query params. */
+    async get(path, params) {
+        const url = new URL(this.baseUrl + path);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                if (v !== undefined && v !== null && v !== '')
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        return this.fetch(url.toString(), { method: 'GET' });
+    }
+    /** POST JSON body. */
+    async post(path, body) {
+        return this.fetch(this.baseUrl + path, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    /** PUT JSON body. */
+    async put(path, body) {
+        return this.fetch(this.baseUrl + path, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    async fetch(url, init) {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(url, { ...init, signal: ac.signal });
+            const text = await res.text();
+            let parsed = text;
+            try {
+                parsed = text ? JSON.parse(text) : null;
+            }
+            catch {
+                // Non-JSON response — keep text as the body.
+            }
+            if (!res.ok) {
+                throw new HttpError(res.status, parsed);
+            }
+            return parsed;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * Most Curless endpoints wrap their payload in `{ success, data }`.
+ * This helper peels that off, falling through if the response is
+ * already the bare object.
+ */
+export function unwrap(res) {
+    if (res && typeof res === 'object' && 'data' in res) {
+        return res.data;
+    }
+    return res;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Curless MCP Server — lets any MCP-aware client (Claude Desktop, Cursor,
+ * Cline, custom LangChain agent, …) drive a Curless wallet + VCC to order
+ * coffee, book hotels, and buy office supplies through the Curless backend.
+ *
+ * v0.1 = single-user demo mode. All installs share the same demo wallets
+ * (wal-001..wal-004). v0.2 will introduce per-user API keys.
+ */
+export {};