@getbags/cash 0.2.0 → 0.3.0

package/dist/mcp-server.js

@@ -0,0 +1,276 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { CliApiError, apiRequest, checkEndpoint, closeSessions, discover, getBalance, getPolicies, getTransactions, listSessions, redeem, search, setPolicies, walletFetch, } from './api.js';
+import { loadCredentials, saveCredentials as defaultSaveCredentials } from './config.js';
+import { WALLET_MCP_INSTRUCTIONS } from './mcp-instructions.js';
+export const WALLET_MCP_TOOL_NAMES = [
+    'wallet_balance',
+    'wallet_discover',
+    'wallet_search',
+    'wallet_check_endpoint',
+    'wallet_fetch',
+    'wallet_sessions_list',
+    'wallet_sessions_close',
+    'wallet_sessions_tick',
+    'wallet_redeem',
+    'wallet_transactions',
+    'wallet_get_settings',
+    'wallet_update_settings',
+];
+const MISSING_TOKEN_MESSAGE = 'No wallet token found. Run: npx @getbags/cash redeem --test (sandbox) or npx @getbags/cash redeem <code> (live invite).';
+async function defaultTickSession(token, input) {
+    return apiRequest('/api/wallet/sessions', {
+        method: 'POST',
+        token,
+        body: {
+            action: 'tick',
+            cumulative_cents: input.cumulative_cents,
+            session_id: input.session_id,
+            channel_id: input.channel_id,
+        },
+    });
+}
+function textContent(data, isError = false) {
+    return {
+        content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }],
+        isError,
+    };
+}
+function missingTokenResult() {
+    return textContent({
+        status: 'error',
+        code: 'AUTH_MISSING_CREDENTIALS',
+        message: MISSING_TOKEN_MESSAGE,
+    }, true);
+}
+function resolveApi(partial) {
+    return {
+        getBalance,
+        discover,
+        search,
+        checkEndpoint,
+        walletFetch,
+        listSessions,
+        closeSessions,
+        tickSession: defaultTickSession,
+        redeem,
+        getTransactions,
+        getPolicies,
+        setPolicies,
+        ...partial,
+    };
+}
+function resolveToken(deps) {
+    if (deps.getToken)
+        return deps.getToken();
+    return loadCredentials()?.token ?? null;
+}
+/**
+ * Build the BAGS Cash wallet MCP server (stdio-ready). Token is read from
+ * ~/.bags/credentials.json (or deps.getToken) per tool call — never from config.
+ */
+export function createWalletMcpServer(deps = {}) {
+    const api = resolveApi(deps.api);
+    const persistCredentials = deps.saveCredentials ?? defaultSaveCredentials;
+    const server = new McpServer({ name: 'bags-cash', version: '0.3.0' }, { instructions: WALLET_MCP_INSTRUCTIONS });
+    async function withToken(run) {
+        const token = resolveToken(deps);
+        if (!token)
+            return missingTokenResult();
+        try {
+            return await run(token);
+        }
+        catch (err) {
+            if (err instanceof CliApiError) {
+                return textContent(err.message, true);
+            }
+            return textContent({
+                status: 'error',
+                message: err instanceof Error ? err.message : String(err),
+            }, true);
+        }
+    }
+    server.registerTool('wallet_balance', {
+        title: 'Wallet balance',
+        description: 'Show BAGS agent wallet balance, daily spent/cap, per-call cap, and status.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => withToken(async (token) => textContent(await api.getBalance(token))));
+    server.registerTool('wallet_discover', {
+        title: 'Discover wallet endpoints',
+        description: 'List BAGS merchant x402 endpoints. Optional query also searches the open ecosystem index (BAGS results first).',
+        inputSchema: {
+            query: z.string().optional().describe('Optional search keywords'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => withToken(async (token) => {
+        const q = typeof args.query === 'string' ? args.query.trim() : '';
+        return textContent(await api.discover(token, q || undefined));
+    }));
+    server.registerTool('wallet_search', {
+        title: 'Search payable endpoints',
+        description: 'Natural-language search for x402 endpoints. BAGS catalog first, best-effort ecosystem (Bazaar) second. Returns price, description, schemas when available.',
+        inputSchema: {
+            query: z.string().min(1).describe('Natural-language or keyword query'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => withToken(async (token) => textContent(await api.search(token, String(args.query ?? '').trim()))));
+    server.registerTool('wallet_check_endpoint', {
+        title: 'Check endpoint quote',
+        description: 'Probe an x402 URL for schema + exact price quote without paying (AgentCash check parity). Use before wallet_fetch.',
+        inputSchema: {
+            url: z.string().url().describe('Endpoint URL to probe'),
+            method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD']).optional(),
+            body: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => withToken(async (token) => textContent(await api.checkEndpoint(token, {
+        url: String(args.url),
+        method: typeof args.method === 'string' ? args.method : undefined,
+        body: args.body,
+    }))));
+    server.registerTool('wallet_fetch', {
+        title: 'Wallet fetch (pay + proxy)',
+        description: 'Pay for and proxy an x402- or MPP-protected HTTP request using the BAGS hosted wallet. MPP tempo:session channels stay open until wallet_sessions_close.',
+        inputSchema: {
+            url: z.string().url(),
+            method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD']).optional(),
+            body: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
+            max_price_cents: z.number().int().positive().optional(),
+            payment_protocol: z
+                .enum(['x402', 'mpp', 'auto'])
+                .optional()
+                .describe('Force rail (default auto: x402 then MPP-only fallback)'),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (args) => withToken(async (token) => textContent(await api.walletFetch(token, {
+        url: String(args.url),
+        method: typeof args.method === 'string' ? args.method : undefined,
+        body: args.body,
+        max_price_cents: typeof args.max_price_cents === 'number' ? args.max_price_cents : undefined,
+        payment_protocol: args.payment_protocol === 'x402' ||
+            args.payment_protocol === 'mpp' ||
+            args.payment_protocol === 'auto'
+            ? args.payment_protocol
+            : undefined,
+    }))));
+    server.registerTool('wallet_sessions_list', {
+        title: 'List MPP sessions',
+        description: 'List open MPP tempo:session channels for the wallet (mppx / AgentCash sessions list parity).',
+        inputSchema: {
+            status: z.enum(['active', 'open', 'closing', 'closed', 'failed']).optional(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => withToken(async (token) => textContent(await api.listSessions(token))));
+    server.registerTool('wallet_sessions_close', {
+        title: 'Close MPP session',
+        description: 'Close one or all open MPP tempo:session channels (settles reservation to cumulative spend). Pass all=true to close every open session.',
+        inputSchema: {
+            session_id: z.string().uuid().optional(),
+            channel_id: z.string().min(1).optional(),
+            all: z.boolean().optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: true },
+    }, async (args) => withToken(async (token) => textContent(await api.closeSessions(token, {
+        session_id: typeof args.session_id === 'string' ? args.session_id : undefined,
+        channel_id: typeof args.channel_id === 'string' ? args.channel_id : undefined,
+        all: typeof args.all === 'boolean' ? args.all : undefined,
+    }))));
+    server.registerTool('wallet_sessions_tick', {
+        title: 'Tick MPP session spend',
+        description: 'Record cumulative spend against an open MPP session (server rejects above max_deposit). Used for metered/streaming vouchers.',
+        inputSchema: {
+            cumulative_cents: z.number().int().nonnegative(),
+            session_id: z.string().uuid().optional(),
+            channel_id: z.string().min(1).optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false },
+    }, async (args) => withToken(async (token) => textContent(await api.tickSession(token, {
+        cumulative_cents: Number(args.cumulative_cents),
+        session_id: typeof args.session_id === 'string' ? args.session_id : undefined,
+        channel_id: typeof args.channel_id === 'string' ? args.channel_id : undefined,
+    }))));
+    server.registerTool('wallet_redeem', {
+        title: 'Redeem invite code',
+        description: 'Redeem a BAGS wallet invite code and persist the token to ~/.bags/credentials.json (never echoed back).',
+        inputSchema: {
+            code: z.string().min(1).describe('Invite code'),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false },
+    }, async (args) => {
+        try {
+            const result = await api.redeem({ code: String(args.code) });
+            persistCredentials(result.token);
+            return textContent({
+                status: 'ok',
+                message: 'Wallet token saved to ~/.bags/credentials.json (mode 0o600). Token is not returned — call wallet_balance next.',
+                balance_cents: result.balance_cents,
+            });
+        }
+        catch (err) {
+            if (err instanceof CliApiError) {
+                return textContent(err.message, true);
+            }
+            return textContent({
+                status: 'error',
+                message: err instanceof Error ? err.message : String(err),
+            }, true);
+        }
+    });
+    server.registerTool('wallet_transactions', {
+        title: 'Wallet transactions',
+        description: 'List paginated wallet ledger / spend history.',
+        inputSchema: {
+            limit: z.number().int().positive().max(100).optional(),
+            cursor: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (args) => withToken(async (token) => textContent(await api.getTransactions(token, {
+        limit: typeof args.limit === 'number' ? args.limit : undefined,
+        cursor: typeof args.cursor === 'string' ? args.cursor : undefined,
+    }))));
+    server.registerTool('wallet_get_settings', {
+        title: 'Get wallet settings / policies',
+        description: 'Read spend policies and wallet settings (caps, status).',
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => withToken(async (token) => {
+        try {
+            return textContent(await api.getPolicies(token));
+        }
+        catch (err) {
+            if (err instanceof CliApiError && err.code === 'NOT_FOUND') {
+                const bal = await api.getBalance(token);
+                return textContent({
+                    status: 'success',
+                    data: { ...bal, note: 'policies API not live; returning balance caps' },
+                });
+            }
+            throw err;
+        }
+    }));
+    server.registerTool('wallet_update_settings', {
+        title: 'Update wallet settings / policies',
+        description: 'Patch spend policies (e.g. per_call_cap_cents, daily_cap_cents).',
+        inputSchema: {
+            per_call_cap_cents: z.number().int().positive().optional(),
+            daily_cap_cents: z.number().int().positive().optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+    }, async (args) => withToken(async (token) => {
+        const patch = {};
+        if (typeof args.per_call_cap_cents === 'number')
+            patch.per_call_cap_cents = args.per_call_cap_cents;
+        if (typeof args.daily_cap_cents === 'number')
+            patch.daily_cap_cents = args.daily_cap_cents;
+        return textContent(await api.setPolicies(token, patch));
+    }));
+    return server;
+}
+/** Connect the wallet MCP server over stdio (for `bags mcp`). */
+export async function runStdioServer() {
+    const server = createWalletMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/parse.d.ts

@@ -1,9 +1,11 @@
+import type { ClientId, InstallScope } from './detect.js';
 export type PaymentProtocol = 'x402' | 'mpp' | 'auto';
 export type ParsedArgs = {
     command: 'help';
 } | {
     command: 'redeem';
-    code: string;
+    code?: string;
+    test: boolean;
 } | {
     command: 'balance';
 } | {
@@ -27,6 +29,16 @@ export type ParsedArgs = {
     format: 'json' | 'pretty';
 } | {
     command: 'init';
+    dryRun: boolean;
+    clients: ClientId[];
+    scope: InstallScope;
+} | {
+    command: 'mcp';
+} | {
+    command: 'doctor';
+    clients: ClientId[];
+    /** Omitted means check both project and user scopes. */
+    scope?: InstallScope;
 } | {
     command: 'fund';
     open: boolean;

package/dist/parse.js

@@ -1,4 +1,25 @@
 import { walletDepositsVisible } from './deposits-visible.js';
+const VALID_CLIENTS = ['cursor', 'claude', 'codex'];
+function parseClientList(raw) {
+    const parts = raw
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    if (parts.length === 0) {
+        return { error: 'usage: bags init [--client cursor|claude|codex] (repeatable or comma-separated)' };
+    }
+    const out = [];
+    for (const part of parts) {
+        if (part !== 'cursor' && part !== 'claude' && part !== 'codex') {
+            return {
+                error: 'usage: bags init [--client cursor|claude|codex] (repeatable or comma-separated)',
+            };
+        }
+        if (!out.includes(part))
+            out.push(part);
+    }
+    return out;
+}
 function takeFormat(rest, usage) {
     let format = 'pretty';
     const out = [];
@@ -29,11 +50,35 @@ export function parseArgs(argv) {
     const [cmd, ...rest] = argv;
     switch (cmd) {
         case 'redeem': {
-            const code = rest[0];
-            if (!code || code.startsWith('-')) {
-                return { command: 'error', message: 'usage: bags redeem <code>' };
+            let code;
+            let test = false;
+            for (const arg of rest) {
+                if (arg === '--test') {
+                    test = true;
+                }
+                else if (arg.startsWith('-')) {
+                    return {
+                        command: 'error',
+                        message: 'usage: bags redeem <code> | bags redeem --test',
+                    };
+                }
+                else if (!code) {
+                    code = arg;
+                }
+                else {
+                    return {
+                        command: 'error',
+                        message: 'usage: bags redeem <code> | bags redeem --test',
+                    };
+                }
+            }
+            if (!test && !code) {
+                return {
+                    command: 'error',
+                    message: 'usage: bags redeem <code> | bags redeem --test',
+                };
             }
-            return { command: 'redeem', code };
+            return { command: 'redeem', code, test };
         }
         case 'balance':
             return { command: 'balance' };
@@ -199,8 +244,145 @@ export function parseArgs(argv) {
             }
             return { command: 'sessions', action, sessionId, channelId, all, yes, format: parsed.format };
         }
-        case 'init':
-            return { command: 'init' };
+        case 'init': {
+            let dryRun = false;
+            let scope = 'user';
+            const clients = [];
+            for (let i = 0; i < rest.length; i++) {
+                const arg = rest[i];
+                if (arg === '--dry-run') {
+                    dryRun = true;
+                }
+                else if (arg === '--scope') {
+                    const value = rest[++i];
+                    if (value !== 'project' && value !== 'user') {
+                        return {
+                            command: 'error',
+                            message: 'usage: bags init [--scope project|user]',
+                        };
+                    }
+                    scope = value;
+                }
+                else if (arg.startsWith('--scope=')) {
+                    const value = arg.slice('--scope='.length);
+                    if (value !== 'project' && value !== 'user') {
+                        return {
+                            command: 'error',
+                            message: 'usage: bags init [--scope project|user]',
+                        };
+                    }
+                    scope = value;
+                }
+                else if (arg === '--client') {
+                    const value = rest[++i];
+                    if (!value) {
+                        return {
+                            command: 'error',
+                            message: 'usage: bags init [--client cursor|claude|codex] (repeatable or comma-separated)',
+                        };
+                    }
+                    const parsed = parseClientList(value);
+                    if ('error' in parsed)
+                        return { command: 'error', message: parsed.error };
+                    for (const c of parsed) {
+                        if (!clients.includes(c))
+                            clients.push(c);
+                    }
+                }
+                else if (arg.startsWith('--client=')) {
+                    const parsed = parseClientList(arg.slice('--client='.length));
+                    if ('error' in parsed)
+                        return { command: 'error', message: parsed.error };
+                    for (const c of parsed) {
+                        if (!clients.includes(c))
+                            clients.push(c);
+                    }
+                }
+                else if (arg.startsWith('-')) {
+                    return {
+                        command: 'error',
+                        message: 'usage: bags init [--dry-run] [--client cursor|claude|codex] [--scope project|user]',
+                    };
+                }
+                else {
+                    return {
+                        command: 'error',
+                        message: 'usage: bags init [--dry-run] [--client cursor|claude|codex] [--scope project|user]',
+                    };
+                }
+            }
+            // Keep only known clients (defensive; parseClientList already validates).
+            const filtered = clients.filter((c) => VALID_CLIENTS.includes(c));
+            return { command: 'init', dryRun, clients: filtered, scope };
+        }
+        case 'mcp':
+            return { command: 'mcp' };
+        case 'doctor': {
+            let scope;
+            const clients = [];
+            for (let i = 0; i < rest.length; i++) {
+                const arg = rest[i];
+                if (arg === '--scope') {
+                    const value = rest[++i];
+                    if (value !== 'project' && value !== 'user') {
+                        return {
+                            command: 'error',
+                            message: 'usage: bags doctor [--scope project|user] [--client cursor|claude|codex]',
+                        };
+                    }
+                    scope = value;
+                }
+                else if (arg.startsWith('--scope=')) {
+                    const value = arg.slice('--scope='.length);
+                    if (value !== 'project' && value !== 'user') {
+                        return {
+                            command: 'error',
+                            message: 'usage: bags doctor [--scope project|user] [--client cursor|claude|codex]',
+                        };
+                    }
+                    scope = value;
+                }
+                else if (arg === '--client') {
+                    const value = rest[++i];
+                    if (!value) {
+                        return {
+                            command: 'error',
+                            message: 'usage: bags doctor [--client cursor|claude|codex] (repeatable or comma-separated)',
+                        };
+                    }
+                    const parsed = parseClientList(value);
+                    if ('error' in parsed)
+                        return { command: 'error', message: parsed.error };
+                    for (const c of parsed) {
+                        if (!clients.includes(c))
+                            clients.push(c);
+                    }
+                }
+                else if (arg.startsWith('--client=')) {
+                    const parsed = parseClientList(arg.slice('--client='.length));
+                    if ('error' in parsed)
+                        return { command: 'error', message: parsed.error };
+                    for (const c of parsed) {
+                        if (!clients.includes(c))
+                            clients.push(c);
+                    }
+                }
+                else if (arg.startsWith('-')) {
+                    return {
+                        command: 'error',
+                        message: 'usage: bags doctor [--scope project|user] [--client cursor|claude|codex]',
+                    };
+                }
+                else {
+                    return {
+                        command: 'error',
+                        message: 'usage: bags doctor [--scope project|user] [--client cursor|claude|codex]',
+                    };
+                }
+            }
+            const filtered = clients.filter((c) => VALID_CLIENTS.includes(c));
+            return { command: 'doctor', clients: filtered, scope };
+        }
         case 'fund': {
             let open = false;
             let create = false;
@@ -443,8 +625,9 @@ MPP streams: fetch (opens session) → sessions close
 
 Commands:
   redeem <code>                 Redeem an invite code and save the wallet token
+  redeem --test                 Mint a sandbox wallet (no invite; Base Sepolia + Solana devnet)
   balance                       Show wallet balance and caps
-${fundLine}  discover [query]              List BAGS merchant endpoints (BAGS first)
+${fundLine}  discover [query]              List BAGS merchant endpoints (BAGS first; includes \$0.01 /api/v1)
   search <query>                NL search: BAGS catalog + ecosystem index
   check <url>                   Probe an endpoint for schema + exact quote (no pay)
   fetch <url> [flags]           Pay and proxy an x402 / MPP endpoint
@@ -453,10 +636,22 @@ ${fundLine}  discover [query]              List BAGS merchant endpoints (BAGS fi
   policies get|set              Read or update spend policies
   keys create|list|revoke       Manage per-agent wallet keys
   register <origin>             Register an origin into the discover index
-  init                          Install the bags-cash agent skill into this repo
+  init [flags]                  Register MCP + skill + routing rule for detected clients
+  mcp                           Serve wallet tools over stdio (JSON-RPC on stdout)
+  doctor [flags]                Verify token, MCP registration, skill, and routing rule
+
+Init flags:
+  --dry-run                     Print the plan without writing files
+  --client <name>               Force cursor|claude|codex even without a marker dir (repeatable)
+  --scope project|user          Config scope (default: user — ambient on this machine)
+
+Doctor flags:
+  --client <name>               Target cursor|claude|codex (repeatable or comma-separated)
+  --scope project|user          Check one scope (default: both project and user)
 
 Hosted skill (prompt paste):
   Set up https://www.getbags.app/wallet/skill.md
+  Human install: https://www.getbags.app/wallet/install
   Onboard: https://www.getbags.app/wallet/onboard
 
 Fetch / check flags:
@@ -467,9 +662,11 @@ Fetch / check flags:
   --format json|pretty          Machine or human output
 
 Sessions:
-  bags sessions list
-  bags sessions close <id>      Close one channel (session uuid or channel id)
-  bags sessions close --all --yes
+  npx @getbags/cash sessions list
+  npx @getbags/cash sessions close <id>
+  npx @getbags/cash sessions close --all --yes
+
+Alias: after \`npm i -g @getbags/cash\`, \`bags\` is equivalent to \`npx @getbags/cash\`.
 
 Env:
   BAGS_API_URL                  API base URL (default: https://www.getbags.app)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getbags/cash",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "BAGS Cash CLI — hosted agent wallet for x402 (balance → discover → check → fetch)",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "test": "vitest run",
+    "test": "bun run build && vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "bun run build"
   },
@@ -38,6 +38,10 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.26.0",
+    "zod": "^4.3.6"
+  },
   "devDependencies": {
     "@types/node": "^25.0.3",
     "typescript": "6.0.2",