@blocks-network/mcp-server 0.1.55 → 0.1.64

package/README.md

@@ -9,6 +9,7 @@ Get API Key: https://app.blocks.ai/manage/api-keys
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `BLOCKS_API_KEY` | Yes | Your Blocks Network API key |
+| `BLOCKS_ORG_ID` | For billing tools | Your consumer org ID (required by `check_balance` and `request_topup`). Find it in the dashboard URL or `blocks whoami --json`. |
 | `BLOCKS_MCP_FILE_ROOT` | No | Allowed root directory for file uploads (default: cwd) |
 
 All other configuration (keys, endpoints) is resolved automatically from CDM.
@@ -19,6 +20,8 @@ All other configuration (keys, endpoints) is resolved automatically from CDM.
 npm i @blocks-network/mcp-server
 ```
 
+`BLOCKS_ORG_ID` in the snippets below is only required by the billing tools (`check_balance`, `request_topup`); omit it if you don't plan to use them.
+
 ### Claude Code (CLI)
 
 ```bash
@@ -34,7 +37,8 @@ Or add to your `.claude/settings.json`:
       "command": "npx",
       "args": ["@blocks-network/mcp-server"],
       "env": {
-        "BLOCKS_API_KEY": "your-api-key"
+        "BLOCKS_API_KEY": "your-api-key",
+        "BLOCKS_ORG_ID": "your-consumer-org-id"
       }
     }
   }
@@ -52,7 +56,8 @@ Add to your `claude_desktop_config.json`:
       "command": "npx",
       "args": ["@blocks-network/mcp-server"],
       "env": {
-        "BLOCKS_API_KEY": "your-api-key"
+        "BLOCKS_API_KEY": "your-api-key",
+        "BLOCKS_ORG_ID": "your-consumer-org-id"
       }
     }
   }
@@ -74,7 +79,8 @@ Create an `mcp.json` file:
       "command": "npx",
       "args": ["@blocks-network/mcp-server"],
       "env": {
-        "BLOCKS_API_KEY": "your-api-key"
+        "BLOCKS_API_KEY": "your-api-key",
+        "BLOCKS_ORG_ID": "your-consumer-org-id"
       }
     }
   }
@@ -92,7 +98,8 @@ Add to your `~/.gemini/settings.json`:
       "command": "npx",
       "args": ["@blocks-network/mcp-server"],
       "env": {
-        "BLOCKS_API_KEY": "your-api-key"
+        "BLOCKS_API_KEY": "your-api-key",
+        "BLOCKS_ORG_ID": "your-consumer-org-id"
       }
     }
   }
@@ -107,9 +114,16 @@ Add to your `~/.gemini/settings.json`:
 | `get_task` | Get the current status of a task |
 | `list_tasks` | List tasks, optionally filtered by agent or state |
 | `cancel_task` | Cancel a running task |
+| `pause_task` | Pause a running pipe task |
+| `resume_task` | Resume a paused pipe task |
+| `retry_task` | Retry a failed task |
 | `list_agents` | List available agents in the registry |
 | `get_agent_card` | Get the full agent card for a specific agent |
+| `get_agent_status` | Check live availability for agents (online instance count and total task count). Per-instance live activity counters (`activeTasks`, `concurrentTasksPerInstance`, `startedAt`, `totalActiveTasks`) are reserved in the response shape but currently return `0` — the backend does not yet populate them. |
 | `connect_task` | Connect to an existing task and stream events |
+| `download_artifact` | Download a single task artifact by file name (inline content or save to disk) |
+| `check_balance` | Get the consumer billing balance for the configured org |
+| `request_topup` | Create a Stripe Checkout URL to add USD to the consumer balance (user completes payment in a browser). Minimum top-up is `$5` (platform `MIN_BILLING_AMOUNT`). |
 
 ## Development
 

package/dist/agent-status.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Agent presence/availability helper.
+ *
+ * Calls GET /api/v1/agent-status with the Blocks-Protocol-Version
+ * header. Backend route is optionalAuth so the API key is forwarded
+ * when available but not required.
+ *
+ * Response shape mirrors the service's agent-status types.
+ */
+/** MUST stay in sync with the service's agent-status types. */
+export declare const MAX_AGENT_NAMES = 50;
+export declare const AGENT_NAME_PATTERN: RegExp;
+export interface AgentInstanceStatus {
+    instanceId: string;
+    uuid: string;
+    online: true;
+    /**
+     * Reserved — backend currently returns 0 (live activity counters are not
+     * yet populated by the agent-status service). Do not use for routing or
+     * availability decisions.
+     */
+    activeTasks: number;
+    /** Reserved — backend currently returns 0. See `activeTasks`. */
+    concurrentTasksPerInstance: number;
+    /** Reserved — backend currently returns 0. See `activeTasks`. */
+    startedAt: number;
+    sdkVersion: string | null;
+    cliVersion: string | null;
+    preferredProtocolVersion: string | null;
+    protocolVersions: string[];
+}
+export interface AgentStatus {
+    agentName: string;
+    instances: AgentInstanceStatus[];
+    onlineCount: number;
+    /** Reserved — backend currently returns 0. See `AgentInstanceStatus.activeTasks`. */
+    totalActiveTasks: number;
+    taskCount: number;
+}
+export interface AgentStatusResponse {
+    agents: Record<string, AgentStatus>;
+}
+export interface FetchAgentStatusOptions {
+    baseUrl: string;
+    agentNames: string[];
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function fetchAgentStatus(opts: FetchAgentStatusOptions): Promise<AgentStatusResponse>;

package/dist/agent-status.js

@@ -0,0 +1,40 @@
+/**
+ * Agent presence/availability helper.
+ *
+ * Calls GET /api/v1/agent-status with the Blocks-Protocol-Version
+ * header. Backend route is optionalAuth so the API key is forwarded
+ * when available but not required.
+ *
+ * Response shape mirrors the service's agent-status types.
+ */
+import { PROTOCOL_VERSION_HEADER, CURRENT_PROTOCOL_VERSION, } from './protocol-headers.js';
+/** MUST stay in sync with the service's agent-status types. */
+export const MAX_AGENT_NAMES = 50;
+export const AGENT_NAME_PATTERN = /^[a-zA-Z0-9_]+$/;
+export async function fetchAgentStatus(opts) {
+    const names = opts.agentNames.map((n) => n.trim()).filter(Boolean);
+    if (names.length === 0) {
+        throw new Error('agentNames must contain at least one value');
+    }
+    if (names.length > MAX_AGENT_NAMES) {
+        throw new Error(`agentNames must be at most ${MAX_AGENT_NAMES} values`);
+    }
+    for (const n of names) {
+        if (!AGENT_NAME_PATTERN.test(n)) {
+            throw new Error(`Invalid agent name: ${n}`);
+        }
+    }
+    const params = new URLSearchParams({ agentNames: names.join(',') });
+    const url = `${opts.baseUrl.replace(/\/+$/, '')}/api/v1/agent-status?${params}`;
+    const headers = {
+        [PROTOCOL_VERSION_HEADER]: CURRENT_PROTOCOL_VERSION,
+    };
+    if (opts.apiKey)
+        headers['Authorization'] = `Bearer ${opts.apiKey}`;
+    const fetchFn = opts.fetchImpl ?? fetch;
+    const response = await fetchFn(url, { headers });
+    if (!response.ok) {
+        throw new Error(`Agent status failed: HTTP ${response.status}`);
+    }
+    return (await response.json());
+}

package/dist/billing.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Billing helpers — direct HTTP to the routes that accept Bearer
+ * API-key auth (`requireAuth` middleware path on the backend).
+ *
+ *   GET  /api/v1/billing/:orgId/consumer/balance
+ *   POST /api/v1/billing/:orgId/consumer/topup
+ *
+ * Other billing routes (ledger, usage-summary, dashboard-summary,
+ * topup-from-earnings) are session-only on the backend and are not
+ * callable from an MCP server holding only an API key.
+ */
+/**
+ * Platform minimum top-up amount in USD. MUST stay in sync with
+ * the service's MIN_BILLING_AMOUNT
+ * (decimal-dollar string `'5'`). The backend rejects values below this floor
+ * via `stripeMoneyAtLeast(MIN_BILLING_AMOUNT, ...)`; we mirror it here so MCP
+ * callers get the real contract up front instead of a runtime HTTP 400.
+ */
+export declare const MIN_TOPUP_AMOUNT_USD = 5;
+export interface ConsumerBalance {
+    /** Ledger balance as a decimal-dollar string (e.g. "12.34"). */
+    balance: string;
+    /** Currently reserved (held for in-flight tasks). */
+    reservedBalance: string;
+    /** balance - reservedBalance. */
+    availableBalance: string;
+    /** ISO timestamp of when the balance snapshot was taken. */
+    updatedAt: string;
+}
+export interface TopUpSession {
+    /** Stripe Checkout URL the user opens in a browser to complete payment. */
+    checkoutUrl: string;
+    /** Stripe Checkout session id. */
+    sessionId: string;
+}
+export interface BillingClientBase {
+    baseUrl: string;
+    orgId: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function getConsumerBalance(opts: BillingClientBase): Promise<ConsumerBalance>;
+export interface CreateTopUpOptions extends BillingClientBase {
+    /**
+     * Whole-dollar (or whole-cent decimal) USD amount, e.g. 25 or 19.99.
+     * Must be at least `MIN_TOPUP_AMOUNT_USD` ($5) — backend rejects below this.
+     */
+    amountUsd: number;
+}
+export declare function createConsumerTopUp(opts: CreateTopUpOptions): Promise<TopUpSession>;

package/dist/billing.js

@@ -0,0 +1,72 @@
+/**
+ * Billing helpers — direct HTTP to the routes that accept Bearer
+ * API-key auth (`requireAuth` middleware path on the backend).
+ *
+ *   GET  /api/v1/billing/:orgId/consumer/balance
+ *   POST /api/v1/billing/:orgId/consumer/topup
+ *
+ * Other billing routes (ledger, usage-summary, dashboard-summary,
+ * topup-from-earnings) are session-only on the backend and are not
+ * callable from an MCP server holding only an API key.
+ */
+import { PROTOCOL_VERSION_HEADER, CURRENT_PROTOCOL_VERSION, } from './protocol-headers.js';
+/**
+ * Platform minimum top-up amount in USD. MUST stay in sync with
+ * the service's MIN_BILLING_AMOUNT
+ * (decimal-dollar string `'5'`). The backend rejects values below this floor
+ * via `stripeMoneyAtLeast(MIN_BILLING_AMOUNT, ...)`; we mirror it here so MCP
+ * callers get the real contract up front instead of a runtime HTTP 400.
+ */
+export const MIN_TOPUP_AMOUNT_USD = 5;
+function buildHeaders(apiKey) {
+    return {
+        [PROTOCOL_VERSION_HEADER]: CURRENT_PROTOCOL_VERSION,
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+    };
+}
+function billingUrl(baseUrl, orgId, suffix) {
+    return `${baseUrl.replace(/\/+$/, '')}/api/v1/billing/${encodeURIComponent(orgId)}${suffix}`;
+}
+export async function getConsumerBalance(opts) {
+    const url = billingUrl(opts.baseUrl, opts.orgId, '/consumer/balance');
+    const fetchFn = opts.fetchImpl ?? fetch;
+    const response = await fetchFn(url, {
+        method: 'GET',
+        headers: buildHeaders(opts.apiKey),
+    });
+    if (!response.ok) {
+        throw new Error(`Balance lookup failed: HTTP ${response.status}`);
+    }
+    return (await response.json());
+}
+export async function createConsumerTopUp(opts) {
+    if (!Number.isFinite(opts.amountUsd) || opts.amountUsd <= 0) {
+        throw new Error('amountUsd must be a positive finite number');
+    }
+    if (Math.round(opts.amountUsd * 100) / 100 !== opts.amountUsd) {
+        throw new Error('amountUsd must be a whole-cent value (no sub-cent fractions)');
+    }
+    if (opts.amountUsd < MIN_TOPUP_AMOUNT_USD) {
+        throw new Error(`amountUsd must be at least $${MIN_TOPUP_AMOUNT_USD}.00 (platform minimum)`);
+    }
+    const amount = opts.amountUsd.toFixed(2);
+    const url = billingUrl(opts.baseUrl, opts.orgId, '/consumer/topup');
+    const fetchFn = opts.fetchImpl ?? fetch;
+    const response = await fetchFn(url, {
+        method: 'POST',
+        headers: buildHeaders(opts.apiKey),
+        body: JSON.stringify({ amount }),
+    });
+    if (!response.ok) {
+        let detail = '';
+        try {
+            detail = await response.text();
+        }
+        catch {
+            // ignore body decode failures
+        }
+        throw new Error(`Top-up failed: HTTP ${response.status}${detail ? ` — ${detail}` : ''}`);
+    }
+    return (await response.json());
+}