@blocks-network/mcp-server 0.1.62 → 0.1.64

package/dist/tools.js

@@ -161,13 +161,13 @@ export async function listAgents(params, deps) {
     const result = await deps.listAgents({
         baseUrl,
         apiKey,
-        skill: params.skill,
+        tag: params.tag,
         listing: params.listing,
         limit: params.limit,
     });
     const lines = result.agents.map((a) => {
-        const skills = a.skills?.map((s) => s.name).join(', ') ?? '';
-        return `${a.agentName} | ${a.name ?? a.agentName} | ${a.listing ?? 'public'} | ${skills}`;
+        const tags = a.tags?.map((t) => t.name).join(', ') ?? '';
+        return `${a.agentName} | ${a.name ?? a.agentName} | ${a.listing ?? 'public'} | ${tags}`;
     });
     const header = `Agents (${result.totalCount ?? result.agents.length}):`;
     return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
@@ -268,6 +268,172 @@ export async function connectTask(params, deps) {
     }
 }
 // ============================================================================
+// download_artifact
+// ============================================================================
+function bytesToBase64(bytes) {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++)
+        binary += String.fromCharCode(bytes[i]);
+    return Buffer.from(binary, 'binary').toString('base64');
+}
+export async function downloadArtifact(params, deps) {
+    const freeClient = await deps.getTaskClient('free');
+    const task = await freeClient.getTask(params.taskId);
+    const billingMode = resolveBillingMode(task);
+    const client = await deps.getTaskClient(billingMode);
+    let session;
+    try {
+        session = await client.connect({ taskId: params.taskId });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Failed to connect to task ${params.taskId}: ${msg}` }],
+            isError: true,
+        };
+    }
+    try {
+        const refs = session.listArtifacts();
+        const ref = refs.find((r) => r.fileName === params.fileName);
+        if (!ref) {
+            const available = refs.map((r) => r.fileName ?? 'unnamed').join(', ') || '(none)';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Artifact "${params.fileName}" not found on task ${params.taskId}. Available: ${available}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const downloaded = await session.downloadArtifact(ref);
+        if (params.savePath) {
+            const safePath = deps.resolveSavePath(params.savePath);
+            deps.writeFile(safePath, downloaded.data);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Saved ${downloaded.data.length} bytes to ${safePath} (${downloaded.mimeType})`,
+                    },
+                ],
+            };
+        }
+        if (isTextMimeType(downloaded.mimeType)) {
+            const text = new TextDecoder().decode(downloaded.data);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `[artifact: ${downloaded.fileName ?? params.fileName}] (${downloaded.mimeType}, ${downloaded.data.length} bytes)\n${text}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `[artifact: ${downloaded.fileName ?? params.fileName}] (${downloaded.mimeType}, ${downloaded.data.length} bytes, base64)\n${bytesToBase64(downloaded.data)}`,
+                },
+            ],
+        };
+    }
+    finally {
+        session.close();
+    }
+}
+// ============================================================================
+// pause_task / resume_task / retry_task
+// ============================================================================
+export async function pauseTask(params, deps) {
+    const client = await deps.getTaskClient();
+    await client.pauseTask(params.taskId);
+    return { content: [{ type: 'text', text: `Task ${params.taskId} paused.` }] };
+}
+export async function resumeTask(params, deps) {
+    const client = await deps.getTaskClient();
+    await client.resumeTask(params.taskId);
+    return { content: [{ type: 'text', text: `Task ${params.taskId} resumed.` }] };
+}
+export async function retryTask(params, deps) {
+    const client = await deps.getTaskClient();
+    await client.retryTask(params.taskId);
+    return { content: [{ type: 'text', text: `Task ${params.taskId} retry requested.` }] };
+}
+// ============================================================================
+// get_agent_status
+// ============================================================================
+export async function getAgentStatus(params, deps) {
+    const baseUrl = await deps.getBaseUrl();
+    const apiKey = deps.getApiKey();
+    const result = await deps.fetchAgentStatus({
+        baseUrl,
+        apiKey,
+        agentNames: params.agentNames,
+    });
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+}
+// ============================================================================
+// check_balance / request_topup
+// ============================================================================
+function requireBillingContext(deps) {
+    const apiKey = deps.getApiKey();
+    if (!apiKey) {
+        return {
+            content: [{ type: 'text', text: 'BLOCKS_API_KEY is required for billing operations.' }],
+            isError: true,
+        };
+    }
+    const orgId = deps.getOrgId();
+    if (!orgId) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'BLOCKS_ORG_ID is required for billing operations. Set it from your dashboard URL or `blocks whoami --json`.',
+                },
+            ],
+            isError: true,
+        };
+    }
+    return { apiKey, orgId };
+}
+export async function checkBalance(_params, deps) {
+    const ctx = requireBillingContext(deps);
+    if ('content' in ctx)
+        return ctx;
+    const baseUrl = await deps.getBaseUrl();
+    const balance = await deps.getConsumerBalance({
+        baseUrl,
+        apiKey: ctx.apiKey,
+        orgId: ctx.orgId,
+    });
+    return {
+        content: [{ type: 'text', text: JSON.stringify(balance, null, 2) }],
+    };
+}
+export async function requestTopup(params, deps) {
+    const ctx = requireBillingContext(deps);
+    if ('content' in ctx)
+        return ctx;
+    const baseUrl = await deps.getBaseUrl();
+    const session = await deps.createConsumerTopUp({
+        baseUrl,
+        apiKey: ctx.apiKey,
+        orgId: ctx.orgId,
+        amountUsd: params.amountUsd,
+    });
+    const url = session.checkoutUrl;
+    const body = url
+        ? `Open this URL in a browser to complete the $${params.amountUsd.toFixed(2)} top-up:\n${url}`
+        : JSON.stringify(session, null, 2);
+    return { content: [{ type: 'text', text: body }] };
+}
+// ============================================================================
 // Default file helpers (re-exported so index.ts can build a default ToolDeps)
 // ============================================================================
 export function defaultFileSize(path) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocks-network/mcp-server",
-  "version": "0.1.62",
+  "version": "0.1.64",
   "description": "MCP server for Blocks Network consumer operations",
   "type": "module",
   "main": "dist/index.js",

package/src/agent-status.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 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 async function fetchAgentStatus(
+  opts: FetchAgentStatusOptions,
+): Promise<AgentStatusResponse> {
+  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: Record<string, string> = {
+    [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()) as AgentStatusResponse;
+}

package/src/billing.ts

@@ -0,0 +1,122 @@
+/**
+ * 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;
+
+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;
+}
+
+function buildHeaders(apiKey: string): Record<string, string> {
+  return {
+    [PROTOCOL_VERSION_HEADER]: CURRENT_PROTOCOL_VERSION,
+    Authorization: `Bearer ${apiKey}`,
+    'Content-Type': 'application/json',
+  };
+}
+
+function billingUrl(baseUrl: string, orgId: string, suffix: string): string {
+  return `${baseUrl.replace(/\/+$/, '')}/api/v1/billing/${encodeURIComponent(orgId)}${suffix}`;
+}
+
+export async function getConsumerBalance(
+  opts: BillingClientBase,
+): Promise<ConsumerBalance> {
+  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()) as 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 async function createConsumerTopUp(
+  opts: CreateTopUpOptions,
+): Promise<TopUpSession> {
+  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()) as TopUpSession;
+}

package/src/index.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-import { resolve, relative } from 'node:path';
-import { realpathSync } from 'node:fs';
+import { resolve, relative, dirname } from 'node:path';
+import { realpathSync, mkdirSync, writeFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
@@ -15,14 +15,23 @@ import {
 } from '@blocks-network/sdk';
 
 import { listAgentsAuthenticated } from './registry-list.js';
+import { fetchAgentStatus, MAX_AGENT_NAMES } from './agent-status.js';
+import { getConsumerBalance, createConsumerTopUp } from './billing.js';
 import {
   sendTask,
   getTask,
   listTasks,
   cancelTask,
+  pauseTask,
+  resumeTask,
+  retryTask,
   listAgents,
   getAgentCard,
+  getAgentStatus,
   connectTask,
+  downloadArtifact,
+  checkBalance,
+  requestTopup,
   defaultFileSize,
   type ToolDeps,
   type TaskClientLike,
@@ -51,6 +60,21 @@ function validateFilePath(filePath: string): string {
   return real;
 }
 
+function resolveSavePath(filePath: string): string {
+  const root = realpathSync(resolve(ALLOWED_ROOT));
+  const resolved = resolve(root, filePath);
+  const rel = relative(root, resolved);
+  if (rel.startsWith('..') || resolve(root, rel) !== resolved) {
+    throw new Error(`Save path must be within ${ALLOWED_ROOT}`);
+  }
+  mkdirSync(dirname(resolved), { recursive: true });
+  return resolved;
+}
+
+function writeFile(filePath: string, data: Uint8Array): void {
+  writeFileSync(filePath, data);
+}
+
 const taskClients = new Map<string, TaskClient>();
 let resolvedBaseUrl: string | undefined;
 
@@ -78,11 +102,17 @@ async function getTaskClient(billingMode: 'free' | 'paid' = 'free'): Promise<Tas
 const deps: ToolDeps = {
   getBaseUrl,
   getApiKey: () => process.env.BLOCKS_API_KEY,
+  getOrgId: () => process.env.BLOCKS_ORG_ID,
   getTaskClient,
   getAgentByName: (agentName, options) =>
     getAgent(agentName, options) as Promise<AgentEntryLike | null>,
   listAgents: listAgentsAuthenticated,
+  fetchAgentStatus,
+  getConsumerBalance,
+  createConsumerTopUp,
   validateFilePath,
+  resolveSavePath,
+  writeFile,
   fileSize: defaultFileSize,
   maxUploadBytes: BLOCKS_MAX_UPLOAD_BYTES,
   filePartFromPath,
@@ -140,11 +170,32 @@ server.tool(
   (params) => cancelTask(params, deps),
 );
 
+server.tool(
+  'pause_task',
+  'Pause a running pipe task. Resume later with resume_task.',
+  { taskId: z.string().describe('The task ID to pause') },
+  (params) => pauseTask(params, deps),
+);
+
+server.tool(
+  'resume_task',
+  'Resume a paused pipe task',
+  { taskId: z.string().describe('The task ID to resume') },
+  (params) => resumeTask(params, deps),
+);
+
+server.tool(
+  'retry_task',
+  'Retry a failed task',
+  { taskId: z.string().describe('The task ID to retry') },
+  (params) => retryTask(params, deps),
+);
+
 server.tool(
   'list_agents',
   'List available agents in the Blocks Network registry. Use listing="private" with an API key to discover your private agents.',
   {
-    skill: z.string().optional().describe('Filter by skill name'),
+    tag: z.string().optional().describe('Filter by tag slug'),
     listing: z
       .enum(['public', 'private'])
       .optional()
@@ -161,6 +212,40 @@ server.tool(
   (params) => getAgentCard(params, deps),
 );
 
+server.tool(
+  'get_agent_status',
+  'Check live availability for one or more agents: how many instances are online, total task count for the agent, and SDK/CLI versions per instance. (Per-instance live activity counters such as `activeTasks`, `concurrentTasksPerInstance`, `startedAt`, and `totalActiveTasks` are reserved in the response shape but not yet populated by the backend — they currently return 0.)',
+  {
+    agentNames: z
+      .array(z.string())
+      .min(1)
+      .max(MAX_AGENT_NAMES)
+      .describe(`Agent names to check (1-${MAX_AGENT_NAMES})`),
+  },
+  (params) => getAgentStatus(params, deps),
+);
+
+server.tool(
+  'check_balance',
+  'Get the consumer billing balance for the configured org (BLOCKS_ORG_ID): ledger balance, active reservations, and available balance.',
+  {},
+  (_params) => checkBalance({}, deps),
+);
+
+server.tool(
+  'request_topup',
+  'Create a Stripe Checkout session to add USD to the consumer balance. Returns a URL the user opens in a browser to complete payment; the MCP server does not handle payment itself. Minimum top-up is $5 (platform `MIN_BILLING_AMOUNT`).',
+  {
+    amountUsd: z
+      .number()
+      .positive()
+      .describe(
+        'Amount to add in USD (e.g. 25 or 19.99). Whole-cent precision. Must be at least $5 (platform minimum).',
+      ),
+  },
+  (params) => requestTopup(params, deps),
+);
+
 server.tool(
   'connect_task',
   'Connect to an existing task, stream events and data until completion',
@@ -171,6 +256,20 @@ server.tool(
   (params) => connectTask(params, deps),
 );
 
+server.tool(
+  'download_artifact',
+  'Download a single artifact from a task by file name. If savePath is provided, writes the artifact to disk under BLOCKS_MCP_FILE_ROOT; otherwise returns the content inline (text decoded, binary base64-encoded).',
+  {
+    taskId: z.string().describe('The task ID that produced the artifact'),
+    fileName: z.string().describe('Artifact file name as listed by get_task'),
+    savePath: z
+      .string()
+      .optional()
+      .describe('Optional path (relative to BLOCKS_MCP_FILE_ROOT) to write the artifact to'),
+  },
+  (params) => downloadArtifact(params, deps),
+);
+
 function shutdown() {
   for (const client of taskClients.values()) {
     client.destroy();

package/src/protocol-headers.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared protocol-version header constants for direct-HTTP backend
+ * callers (`registry-list`, `agent-status`, `billing`).
+ *
+ * MUST stay in sync with
+ * blocks-sdk/sdks/node/src/runtime/protocol-version.ts (the canonical
+ * source). Until the SDK exports these from its public surface, both
+ * files must update atomically when the protocol version bumps.
+ */
+
+export const PROTOCOL_VERSION_HEADER = 'Blocks-Protocol-Version';
+export const CURRENT_PROTOCOL_VERSION = '2026-05-01';

package/src/registry-list.ts

@@ -6,8 +6,10 @@
  * optional Bearer API key for private/owned listings.
  */
 
-export const PROTOCOL_VERSION_HEADER = 'Blocks-Protocol-Version';
-export const CURRENT_PROTOCOL_VERSION = '2026-05-01';
+import {
+  PROTOCOL_VERSION_HEADER,
+  CURRENT_PROTOCOL_VERSION,
+} from './protocol-headers.js';
 
 export interface AgentListEntry {
   agentName: string;
@@ -15,13 +17,13 @@ export interface AgentListEntry {
   description?: string;
   listing?: string;
   billingMode?: string;
-  skills?: Array<{ id: string; name: string }>;
+  tags?: Array<{ id: string; name: string }>;
 }
 
 export interface ListAgentsOptions {
   baseUrl: string;
   apiKey?: string;
-  skill?: string;
+  tag?: string;
   listing?: 'public' | 'private';
   limit?: number;
   fetchImpl?: typeof fetch;
@@ -36,7 +38,7 @@ export async function listAgentsAuthenticated(
   opts: ListAgentsOptions,
 ): Promise<ListAgentsResult> {
   const params = new URLSearchParams({ include: 'full' });
-  if (opts.skill) params.set('skill', opts.skill);
+  if (opts.tag) params.set('tag', opts.tag);
   if (opts.listing) {
     params.set('listing', opts.listing);
     if (opts.listing === 'private') params.set('scope', 'owned');