@getbags/cash 0.2.1 → 0.3.1

package/dist/mcp-server.d.ts

@@ -0,0 +1,72 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type CheckResponse, type DiscoverResponse, type FetchResponse, type BalanceResponse, type PoliciesResponse, type TransactionsResponse, type RedeemResponse, type MppSessionSummary } from './api.js';
+export declare const WALLET_MCP_TOOL_NAMES: readonly ["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"];
+export type WalletMcpApi = {
+    getResult: (token: string, input: {
+        id: string;
+        field?: string;
+        offset?: number;
+        limit?: number;
+    }) => Promise<Record<string, unknown>>;
+    getBalance: (token: string) => Promise<BalanceResponse>;
+    discover: (token: string, query?: string) => Promise<DiscoverResponse>;
+    search: (token: string, query: string) => Promise<DiscoverResponse>;
+    checkEndpoint: (token: string, input: {
+        url: string;
+        method?: string;
+        body?: unknown;
+    }) => Promise<CheckResponse>;
+    walletFetch: (token: string, input: {
+        url: string;
+        method?: string;
+        headers?: Record<string, string>;
+        body?: unknown;
+        max_price_cents?: number;
+        payment_protocol?: 'x402' | 'mpp' | 'auto';
+        result_mode?: 'inline' | 'summary';
+    }) => Promise<FetchResponse>;
+    listSessions: (token: string) => Promise<{
+        sessions: MppSessionSummary[];
+    }>;
+    closeSessions: (token: string, input: {
+        session_id?: string;
+        channel_id?: string;
+        all?: boolean;
+    }) => Promise<{
+        closed: Array<{
+            id: string;
+            channel_id: string;
+            status: string;
+        }>;
+        errors: unknown[];
+    }>;
+    tickSession: (token: string, input: {
+        cumulative_cents: number;
+        session_id?: string;
+        channel_id?: string;
+    }) => Promise<Record<string, unknown>>;
+    redeem: (opts: {
+        code?: string;
+        mode?: 'live' | 'test';
+    }) => Promise<RedeemResponse>;
+    getTransactions: (token: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }) => Promise<TransactionsResponse>;
+    getPolicies: (token: string) => Promise<PoliciesResponse>;
+    setPolicies: (token: string, patch: Record<string, unknown>) => Promise<PoliciesResponse>;
+};
+export type WalletMcpServerDeps = {
+    /** Override credential lookup (default: ~/.bags/credentials.json). */
+    getToken?: () => string | null;
+    /** Persist a redeemed token (default: saveCredentials → ~/.bags/credentials.json). */
+    saveCredentials?: (token: string) => void;
+    api?: Partial<WalletMcpApi>;
+};
+/**
+ * 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 declare function createWalletMcpServer(deps?: WalletMcpServerDeps): McpServer;
+/** Connect the wallet MCP server over stdio (for `bags mcp`). */
+export declare function runStdioServer(): Promise<void>;

package/dist/mcp-server.js

@@ -0,0 +1,293 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { CliApiError, apiRequest, checkEndpoint, closeSessions, discover, getBalance, getResult, 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,
+        getResult,
+        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 { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    const server = new McpServer({ name: 'bags-cash', version }, { 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) => (async () => {
+        const token = resolveToken(deps) ?? '';
+        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) => textContent(await api.search(resolveToken(deps) ?? '', 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_result', {
+        title: 'Read retained wallet result',
+        description: 'Retrieve full output, fields or array pages from a previous wallet_fetch result for 24 hours. Does not execute or charge again. Provider asset URLs may expire earlier.',
+        inputSchema: {
+            id: z.string().uuid(),
+            field: z.string().max(200).optional(),
+            offset: z.number().int().nonnegative().optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (args) => withToken(async (token) => textContent(await api.getResult(token, args))));
+    server.registerTool('wallet_fetch', {
+        title: 'Wallet fetch (pay + proxy)',
+        description: 'Pay for an x402 or one-shot MPP tempo:charge HTTP request with the hosted wallet. Check the quote and wallet mode first. Hosted MPP sessions are currently unavailable.',
+        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(),
+            result_mode: z.enum(['inline', 'summary']).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,
+        result_mode: args.result_mode,
+        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: 'Request cleanup of existing MPP sessions. On-chain close is currently unsupported: the call reports failure and preserves the reservation and ownership. New sessions cannot be opened.',
+        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,11 +1,22 @@
+import type { ClientId, InstallScope } from './detect.js';
 export type PaymentProtocol = 'x402' | 'mpp' | 'auto';
 export type ParsedArgs = {
     command: 'help';
+} | {
+    command: 'usage';
+    message: string;
 } | {
     command: 'redeem';
-    code: string;
+    code?: string;
+    test: boolean;
 } | {
     command: 'balance';
+} | {
+    command: 'result';
+    id: string;
+    field?: string;
+    offset?: number;
+    limit?: number;
 } | {
     command: 'discover';
     format: 'json' | 'pretty';
@@ -27,6 +38,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;