@blocks-network/mcp-server 0.1.62 → 0.1.65

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';
@@ -14,15 +14,25 @@ import {
   BLOCKS_MAX_UPLOAD_BYTES,
 } from '@blocks-network/sdk';
 
-import { listAgentsAuthenticated } from './registry-list.js';
+import { listAllAgentsAuthenticated } 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,
+  searchAgents,
   getAgentCard,
+  getAgentStatus,
   connectTask,
+  downloadArtifact,
+  checkBalance,
+  requestTopup,
   defaultFileSize,
   type ToolDeps,
   type TaskClientLike,
@@ -51,6 +61,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 +103,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,
+  listAgents: listAllAgentsAuthenticated,
+  fetchAgentStatus,
+  getConsumerBalance,
+  createConsumerTopUp,
   validateFilePath,
+  resolveSavePath,
+  writeFile,
   fileSize: defaultFileSize,
   maxUploadBytes: BLOCKS_MAX_UPLOAD_BYTES,
   filePartFromPath,
@@ -140,20 +171,70 @@ 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.',
+  'List available agents in the Blocks Network registry. By default only agents with at least one online instance are returned; set includeOffline=true to also list registered agents that are currently offline. 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()
       .describe('Filter by listing visibility (default: public)'),
-    limit: z.number().optional().describe('Max results to return'),
+    limit: z
+      .number()
+      .optional()
+      .describe('Max agents to fetch across all pages; omit to fetch all'),
+    includeOffline: z
+      .boolean()
+      .optional()
+      .describe('Include agents with no online instances (default: false)'),
   },
   (params) => listAgents(params, deps),
 );
 
+server.tool(
+  'search_agent',
+  'Search the Blocks Network registry for agents matching a free-text query. The query matches against agent name, display name, description, tags, provider, and category, and supports field qualifiers (e.g. "agentname:translate", tag:"data"), quoted phrases, and negation ("-deprecated"). By default only agents with at least one online instance are returned; set includeOffline=true to also include matching agents that are currently offline. Use listing="private" with an API key to search your private agents.',
+  {
+    query: z.string().describe('Free-text search query'),
+    tag: z.string().optional().describe('Additionally filter by tag slug'),
+    listing: z
+      .enum(['public', 'private'])
+      .optional()
+      .describe('Filter by listing visibility (default: public)'),
+    limit: z
+      .number()
+      .optional()
+      .describe('Max matching agents to fetch across all pages; omit to fetch all'),
+    includeOffline: z
+      .boolean()
+      .optional()
+      .describe('Include agents with no online instances (default: false)'),
+  },
+  (params) => searchAgents(params, deps),
+);
+
 server.tool(
   'get_agent_card',
   'Get the full agent card for a specific agent',
@@ -161,6 +242,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 +286,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,33 +17,50 @@ 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;
+  /** Free-text search query (`q`); matches agent name, description, tags, etc. */
+  q?: string;
+  tag?: string;
   listing?: 'public' | 'private';
+  /** Page size for a single request. The backend caps this at 100. */
   limit?: number;
+  /** Opaque pagination cursor returned as `next` by a previous request. */
+  cursor?: string;
   fetchImpl?: typeof fetch;
 }
 
 export interface ListAgentsResult {
   agents: AgentListEntry[];
   totalCount?: number;
+  /** Opaque cursor for the next page, or null/absent when there are no more. */
+  next?: string | null;
+  /** Total agents with at least one online instance (ignores cursor). */
+  totalOnlineCount?: number;
 }
 
+/** Backend maximum page size for GET /api/v1/registry/agents. */
+export const REGISTRY_PAGE_SIZE = 100;
+
+/** Safety backstop so a misbehaving (never-null) cursor can't loop forever. */
+const MAX_PAGES = 1000;
+
 export async function listAgentsAuthenticated(
   opts: ListAgentsOptions,
 ): Promise<ListAgentsResult> {
   const params = new URLSearchParams({ include: 'full' });
-  if (opts.skill) params.set('skill', opts.skill);
+  if (opts.q) params.set('q', opts.q);
+  if (opts.tag) params.set('tag', opts.tag);
   if (opts.listing) {
     params.set('listing', opts.listing);
     if (opts.listing === 'private') params.set('scope', 'owned');
   }
   if (opts.limit) params.set('limit', String(opts.limit));
+  if (opts.cursor) params.set('cursor', opts.cursor);
 
   const url = `${opts.baseUrl.replace(/\/+$/, '')}/api/v1/registry/agents?${params}`;
   const headers: Record<string, string> = {
@@ -56,3 +75,47 @@ export async function listAgentsAuthenticated(
   }
   return (await response.json()) as ListAgentsResult;
 }
+
+/**
+ * Fetch every agent by following the `next` cursor until it's null/absent.
+ *
+ * Uses the backend's maximum page size (100) to minimise round-trips. The
+ * optional `maxAgents` cap bounds the total number of agents collected and
+ * shrinks the final page request so we never over-fetch. The latest
+ * `totalCount`/`totalOnlineCount` seen are carried forward to the result.
+ */
+export async function listAllAgentsAuthenticated(
+  opts: ListAgentsOptions & { maxAgents?: number },
+): Promise<ListAgentsResult> {
+  const agents: AgentListEntry[] = [];
+  let cursor = opts.cursor;
+  let totalCount: number | undefined;
+  let totalOnlineCount: number | undefined;
+  const cap = opts.maxAgents;
+
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const remaining = cap !== undefined ? cap - agents.length : undefined;
+    if (remaining !== undefined && remaining <= 0) break;
+    const pageSize =
+      remaining !== undefined
+        ? Math.min(REGISTRY_PAGE_SIZE, remaining)
+        : REGISTRY_PAGE_SIZE;
+
+    const result = await listAgentsAuthenticated({
+      ...opts,
+      limit: pageSize,
+      cursor,
+    });
+    agents.push(...result.agents);
+    if (result.totalCount !== undefined) totalCount = result.totalCount;
+    if (result.totalOnlineCount !== undefined) {
+      totalOnlineCount = result.totalOnlineCount;
+    }
+
+    cursor = result.next ?? undefined;
+    if (!cursor) break;
+  }
+
+  const trimmed = cap !== undefined ? agents.slice(0, cap) : agents;
+  return { agents: trimmed, totalCount, totalOnlineCount, next: null };
+}