@blocks-network/mcp-server 0.1.62 → 0.1.65

package/dist/tools.d.ts

@@ -7,6 +7,8 @@
  */
 import { textPart, filePartFromPath, type TaskInfo, type SendMessageRequestPart } from '@blocks-network/sdk';
 import type { ListAgentsResult } from './registry-list.js';
+import { type AgentStatusResponse } from './agent-status.js';
+import type { ConsumerBalance, TopUpSession } from './billing.js';
 export interface ArtifactRef {
     fileName?: string;
 }
@@ -65,6 +67,9 @@ export interface TaskClientLike {
         totalCount?: number;
     }>;
     cancelTask(taskId: string): Promise<unknown>;
+    pauseTask(taskId: string): Promise<unknown>;
+    resumeTask(taskId: string): Promise<unknown>;
+    retryTask(taskId: string): Promise<unknown>;
     connect(params: {
         taskId: string;
     }): Promise<TaskSessionLike>;
@@ -100,15 +105,37 @@ export interface ToolDeps {
     listAgents(options: {
         baseUrl: string;
         apiKey?: string;
-        skill?: string;
+        /** Free-text search query (`q`); matches agent name, description, tags, etc. */
+        q?: string;
+        tag?: string;
         listing?: 'public' | 'private';
-        limit?: number;
+        /** Optional cap on the total number of agents to fetch across all pages. */
+        maxAgents?: number;
     }): Promise<ListAgentsResult>;
     validateFilePath(filePath: string): string;
+    resolveSavePath(filePath: string): string;
+    writeFile(filePath: string, data: Uint8Array): void;
     fileSize(path: string): number;
     maxUploadBytes: number;
     filePartFromPath: typeof filePartFromPath;
     textPart: typeof textPart;
+    getOrgId(): string | undefined;
+    fetchAgentStatus(options: {
+        baseUrl: string;
+        apiKey?: string;
+        agentNames: string[];
+    }): Promise<AgentStatusResponse>;
+    getConsumerBalance(options: {
+        baseUrl: string;
+        apiKey: string;
+        orgId: string;
+    }): Promise<ConsumerBalance>;
+    createConsumerTopUp(options: {
+        baseUrl: string;
+        apiKey: string;
+        orgId: string;
+        amountUsd: number;
+    }): Promise<TopUpSession>;
 }
 export interface SendTaskParams {
     agentName: string;
@@ -131,9 +158,28 @@ export interface CancelTaskParams {
     taskId: string;
 }
 export interface ListAgentsParams {
-    skill?: string;
+    tag?: string;
+    listing?: 'public' | 'private';
+    limit?: number;
+    /**
+     * Include agents that have no online instances. Defaults to false: the
+     * registry returns every registered agent regardless of whether any
+     * instance is currently running, so by default we filter to agents with
+     * at least one online instance to avoid surfacing unreachable agents.
+     */
+    includeOffline?: boolean;
+}
+export interface SearchAgentsParams {
+    /** Free-text search query; matches agent name, description, tags, etc. */
+    query: string;
+    tag?: string;
     listing?: 'public' | 'private';
     limit?: number;
+    /**
+     * Include agents that have no online instances. Defaults to false so we
+     * only surface agents that can actually take a task. See ListAgentsParams.
+     */
+    includeOffline?: boolean;
 }
 export interface GetAgentCardParams {
     agentName: string;
@@ -142,11 +188,33 @@ export interface ConnectTaskParams {
     taskId: string;
     timeoutMs?: number;
 }
+export interface DownloadArtifactParams {
+    taskId: string;
+    fileName: string;
+    savePath?: string;
+}
+export interface TaskIdParams {
+    taskId: string;
+}
+export interface GetAgentStatusParams {
+    agentNames: string[];
+}
+export interface RequestTopUpParams {
+    amountUsd: number;
+}
 export declare function sendTask(params: SendTaskParams, deps: ToolDeps): Promise<ToolResult>;
 export declare function getTask(params: GetTaskParams, deps: ToolDeps): Promise<ToolResult>;
 export declare function listTasks(params: ListTasksParams, deps: ToolDeps): Promise<ToolResult>;
 export declare function cancelTask(params: CancelTaskParams, deps: ToolDeps): Promise<ToolResult>;
 export declare function listAgents(params: ListAgentsParams, deps: ToolDeps): Promise<ToolResult>;
+export declare function searchAgents(params: SearchAgentsParams, deps: ToolDeps): Promise<ToolResult>;
 export declare function getAgentCard(params: GetAgentCardParams, deps: ToolDeps): Promise<ToolResult>;
 export declare function connectTask(params: ConnectTaskParams, deps: ToolDeps): Promise<ToolResult>;
+export declare function downloadArtifact(params: DownloadArtifactParams, deps: ToolDeps): Promise<ToolResult>;
+export declare function pauseTask(params: TaskIdParams, deps: ToolDeps): Promise<ToolResult>;
+export declare function resumeTask(params: TaskIdParams, deps: ToolDeps): Promise<ToolResult>;
+export declare function retryTask(params: TaskIdParams, deps: ToolDeps): Promise<ToolResult>;
+export declare function getAgentStatus(params: GetAgentStatusParams, deps: ToolDeps): Promise<ToolResult>;
+export declare function checkBalance(_params: Record<string, never>, deps: ToolDeps): Promise<ToolResult>;
+export declare function requestTopup(params: RequestTopUpParams, deps: ToolDeps): Promise<ToolResult>;
 export declare function defaultFileSize(path: string): number;

package/dist/tools.js

@@ -6,6 +6,7 @@
  * touching the network or the filesystem.
  */
 import { statSync } from 'node:fs';
+import { MAX_AGENT_NAMES, AGENT_NAME_PATTERN, } from './agent-status.js';
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -161,17 +162,89 @@ 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,
+        maxAgents: 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 total = result.totalCount ?? result.agents.length;
+    // The registry returns every registered agent regardless of whether any
+    // instance is currently running. Default to online-only so we never
+    // surface agents that can't actually take a task; `includeOffline` opts
+    // back into the full registry view.
+    if (params.includeOffline) {
+        const lines = result.agents.map(formatAgentRow);
+        const header = `Agents (${result.agents.length} of ${total} total):`;
+        return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
+    }
+    const online = await filterOnlineAgents(result.agents, { baseUrl, apiKey }, deps);
+    const lines = online.map(formatAgentRow);
+    const header = `Agents (${online.length} online of ${total} total):`;
+    return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
+}
+// ============================================================================
+// search_agent
+// ============================================================================
+export async function searchAgents(params, deps) {
+    const query = params.query.trim();
+    if (!query) {
+        return {
+            content: [{ type: 'text', text: 'Search query must not be empty.' }],
+            isError: true,
+        };
+    }
+    const baseUrl = await deps.getBaseUrl();
+    const apiKey = deps.getApiKey();
+    const result = await deps.listAgents({
+        baseUrl,
+        apiKey,
+        q: query,
+        tag: params.tag,
+        listing: params.listing,
+        maxAgents: params.limit,
     });
-    const header = `Agents (${result.totalCount ?? result.agents.length}):`;
+    const total = result.totalCount ?? result.agents.length;
+    // Mirror list_agents: default to online-only so we never surface agents
+    // that can't actually take a task; `includeOffline` opts back into the
+    // full set of matches.
+    if (params.includeOffline) {
+        const lines = result.agents.map(formatAgentRow);
+        const header = `Agents matching "${query}" (${result.agents.length} of ${total} total):`;
+        return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
+    }
+    const online = await filterOnlineAgents(result.agents, { baseUrl, apiKey }, deps);
+    const lines = online.map(formatAgentRow);
+    const header = `Agents matching "${query}" (${online.length} online of ${total} total):`;
     return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
 }
+function formatAgentRow(a) {
+    const tags = a.tags?.map((t) => t.name).join(', ') ?? '';
+    return `${a.agentName} | ${a.name ?? a.agentName} | ${a.listing ?? 'public'} | ${tags}`;
+}
+/**
+ * Keep only agents that have at least one online instance, as reported by
+ * the agent-status service. Agent names that the status endpoint can't
+ * accept (too many, or invalid characters) are queried in valid batches;
+ * any name that's unqueryable is treated as offline and dropped.
+ */
+async function filterOnlineAgents(agents, ctx, deps) {
+    const queryable = agents.filter((a) => AGENT_NAME_PATTERN.test(a.agentName));
+    if (queryable.length === 0)
+        return [];
+    const online = new Set();
+    for (let i = 0; i < queryable.length; i += MAX_AGENT_NAMES) {
+        const batch = queryable.slice(i, i + MAX_AGENT_NAMES);
+        const status = await deps.fetchAgentStatus({
+            baseUrl: ctx.baseUrl,
+            apiKey: ctx.apiKey,
+            agentNames: batch.map((a) => a.agentName),
+        });
+        for (const [name, info] of Object.entries(status.agents)) {
+            if ((info.onlineCount ?? 0) > 0)
+                online.add(name);
+        }
+    }
+    return agents.filter((a) => online.has(a.agentName));
+}
 // ============================================================================
 // get_agent_card
 // ============================================================================
@@ -268,6 +341,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.65",
   "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;
+}