@blocks-network/mcp-server 0.1.55 → 0.1.64

package/dist/index.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
-import { resolve, relative } from 'node:path';
-import { realpathSync, statSync } 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';
 import { TaskClient, textPart, filePartFromPath, fetchCdmConfig, getAgent, BLOCKS_MAX_UPLOAD_BYTES, } 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, } from './tools.js';
 const ALLOWED_ROOT = process.env.BLOCKS_MCP_FILE_ROOT ?? process.cwd();
 if (!process.env.BLOCKS_API_KEY) {
     console.error('Warning: BLOCKS_API_KEY is not set. Private agents and paid tasks will not work.');
@@ -25,11 +29,18 @@ function validateFilePath(filePath) {
     }
     return real;
 }
-function resolveBillingMode(task) {
-    const mode = task.billingMode;
-    if (mode === 'paid')
-        return 'paid';
-    return 'free';
+function resolveSavePath(filePath) {
+    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, data) {
+    writeFileSync(filePath, data);
 }
 const taskClients = new Map();
 let resolvedBaseUrl;
@@ -44,28 +55,6 @@ async function getBaseUrl() {
     resolvedBaseUrl = cdm.api.baseUrl;
     return resolvedBaseUrl;
 }
-async function listAgentsAuthenticated(opts) {
-    const params = new URLSearchParams({ include: 'full' });
-    if (opts.skill)
-        params.set('skill', opts.skill);
-    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));
-    const url = `${opts.baseUrl.replace(/\/+$/, '')}/api/v1/registry/agents?${params}`;
-    const headers = {};
-    if (opts.apiKey)
-        headers['Authorization'] = `Bearer ${opts.apiKey}`;
-    const response = await fetch(url, { headers });
-    if (!response.ok) {
-        throw new Error(`Registry list failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    return data;
-}
 async function getTaskClient(billingMode = 'free') {
     let client = taskClients.get(billingMode);
     if (!client) {
@@ -75,301 +64,88 @@ async function getTaskClient(billingMode = 'free') {
     }
     return client;
 }
+const deps = {
+    getBaseUrl,
+    getApiKey: () => process.env.BLOCKS_API_KEY,
+    getOrgId: () => process.env.BLOCKS_ORG_ID,
+    getTaskClient,
+    getAgentByName: (agentName, options) => getAgent(agentName, options),
+    listAgents: listAgentsAuthenticated,
+    fetchAgentStatus,
+    getConsumerBalance,
+    createConsumerTopUp,
+    validateFilePath,
+    resolveSavePath,
+    writeFile,
+    fileSize: defaultFileSize,
+    maxUploadBytes: BLOCKS_MAX_UPLOAD_BYTES,
+    filePartFromPath,
+    textPart,
+};
 const server = new McpServer({
     name: 'blocks-network',
-    version: '0.1.0',
+    version: '0.1.60',
 });
-// ============================================================================
-// Tool: send_task
-// ============================================================================
 server.tool('send_task', 'Send a task to a Blocks Network agent and wait for the result', {
     agentName: z.string().describe('Name of the target agent'),
     message: z.string().describe('Text message to send to the agent'),
     filePath: z.string().optional().describe('Optional file path to attach'),
-    inputs: z.record(z.string(), z.string()).optional().describe('Additional named inputs as {partId: value} pairs'),
+    inputs: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Additional named inputs as {partId: value} pairs'),
     taskKind: z.enum(['request', 'pipe']).optional().describe('Task kind (default: request)'),
     duration: z.number().optional().describe('Duration in minutes (required for pipe tasks)'),
-    timeoutMs: z.number().optional().describe('Timeout in milliseconds to wait for result (default: 60000)'),
-}, async ({ agentName, message, filePath, inputs, taskKind, duration, timeoutMs }) => {
-    const baseUrl = await getBaseUrl();
-    const apiKey = process.env.BLOCKS_API_KEY;
-    const entry = await getAgent(agentName, { baseUrl, apiKey });
-    const billingMode = entry?.billingMode ?? 'free';
-    const client = await getTaskClient(billingMode);
-    const declaredInputs = entry?.card?.io?.inputs ?? [];
-    const isTextLike = (ct) => ct.startsWith('text/') || ct === 'application/json' || ct.endsWith('+json');
-    const textInput = declaredInputs.find((i) => isTextLike(i.contentType));
-    const fileInput = declaredInputs.find((i) => !isTextLike(i.contentType));
-    const requestParts = [];
-    const textPartId = textInput?.id ?? 'text';
-    if ((textInput || declaredInputs.length === 0) && !inputs?.[textPartId]) {
-        requestParts.push(textPart(message, textPartId));
-    }
-    if (filePath) {
-        const safePath = validateFilePath(filePath);
-        const fileSize = statSync(safePath).size;
-        if (fileSize > BLOCKS_MAX_UPLOAD_BYTES) {
-            return {
-                content: [{ type: 'text', text: `File too large (${fileSize} bytes). Maximum upload size is ${BLOCKS_MAX_UPLOAD_BYTES} bytes (25 MB).` }],
-                isError: true,
-            };
-        }
-        requestParts.push(await filePartFromPath(safePath, {
-            partId: fileInput?.id ?? 'file',
-            contentType: fileInput?.contentType,
-        }));
-    }
-    if (inputs) {
-        for (const [partId, value] of Object.entries(inputs)) {
-            requestParts.push(textPart(value, partId));
-        }
-    }
-    const session = await client.sendMessage({
-        agentName,
-        requestParts,
-        taskKind,
-        duration,
-    });
-    const timeout = timeoutMs ?? 60000;
-    const results = [];
-    session.onProgress((event) => {
-        if (event.message) {
-            results.push(`[progress] ${event.message}`);
-        }
-    });
-    try {
-        const terminal = await session.waitForTerminal(timeout);
-        const allArtifacts = session.listArtifacts();
-        const output = [`Task ${session.taskId} ${terminal.state}`, ...results];
-        for (const ref of allArtifacts) {
-            try {
-                const downloaded = await session.downloadArtifact(ref);
-                const isText = downloaded.mimeType.startsWith('text/') ||
-                    downloaded.mimeType === 'application/json';
-                if (isText) {
-                    const text = new TextDecoder().decode(downloaded.data);
-                    output.push(`[artifact: ${downloaded.fileName ?? 'unnamed'}]\n${text}`);
-                }
-                else {
-                    output.push(`[artifact: ${downloaded.fileName ?? 'unnamed'}] (${downloaded.mimeType}, ${downloaded.data.length} bytes)`);
-                }
-            }
-            catch {
-                output.push(`[artifact: ${ref.fileName ?? 'unnamed'}] (download failed)`);
-            }
-        }
-        if (terminal.state === 'failed') {
-            output.push(`Error: ${terminal.error ?? terminal.reason ?? 'unknown'}`);
-        }
-        session.close();
-        return { content: [{ type: 'text', text: output.join('\n') }] };
-    }
-    catch (err) {
-        session.close();
-        const msg = err instanceof Error ? err.message : String(err);
-        return { content: [{ type: 'text', text: `Task ${session.taskId} error: ${msg}` }], isError: true };
-    }
-});
-// ============================================================================
-// Tool: get_task
-// ============================================================================
-server.tool('get_task', 'Get the current status of a task by ID, including artifact content if completed', {
-    taskId: z.string().describe('The task ID to look up'),
-}, async ({ taskId }) => {
-    const freeClient = await getTaskClient('free');
-    const task = await freeClient.getTask(taskId);
-    const output = [JSON.stringify(task, null, 2)];
-    const terminalStates = new Set(['completed', 'failed', 'canceled']);
-    if (task.state && terminalStates.has(task.state)) {
-        try {
-            const billingMode = resolveBillingMode(task);
-            const client = await getTaskClient(billingMode);
-            const session = await client.connect({ taskId });
-            const allArtifacts = session.listArtifacts();
-            for (const ref of allArtifacts) {
-                try {
-                    const downloaded = await session.downloadArtifact(ref);
-                    const isText = downloaded.mimeType.startsWith('text/') ||
-                        downloaded.mimeType === 'application/json';
-                    if (isText) {
-                        const text = new TextDecoder().decode(downloaded.data);
-                        output.push(`[artifact: ${downloaded.fileName ?? 'unnamed'}]\n${text}`);
-                    }
-                    else {
-                        output.push(`[artifact: ${downloaded.fileName ?? 'unnamed'}] (${downloaded.mimeType}, ${downloaded.data.length} bytes)`);
-                    }
-                }
-                catch {
-                    output.push(`[artifact: ${ref.fileName ?? 'unnamed'}] (download failed)`);
-                }
-            }
-            session.close();
-        }
-        catch {
-            // connect failed — return task info without artifacts
-        }
-    }
-    return { content: [{ type: 'text', text: output.join('\n') }] };
-});
-// ============================================================================
-// Tool: list_tasks
-// ============================================================================
+    timeoutMs: z
+        .number()
+        .optional()
+        .describe('Timeout in milliseconds to wait for result (default: 60000)'),
+}, (params) => sendTask(params, deps));
+server.tool('get_task', 'Get the current status of a task by ID, including artifact content if completed', { taskId: z.string().describe('The task ID to look up') }, (params) => getTask(params, deps));
 server.tool('list_tasks', 'List tasks, optionally filtered by agent or state', {
     agentName: z.string().optional().describe('Filter by agent name'),
     state: z.string().optional().describe('Filter by state (e.g. completed, failed, running)'),
     limit: z.number().optional().describe('Max results to return'),
-}, async ({ agentName, state, limit }) => {
-    const client = await getTaskClient();
-    const result = await client.listTasks({ agentName, state, limit });
-    const lines = result.tasks.map((t) => `${t.taskId} | ${t.agentName ?? '?'} | ${t.state ?? '?'} | ${t.createdTime ?? ''}`);
-    const header = `Tasks (${result.totalCount ?? result.tasks.length} total):`;
-    return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
-});
-// ============================================================================
-// Tool: cancel_task
-// ============================================================================
-server.tool('cancel_task', 'Cancel a running task', {
-    taskId: z.string().describe('The task ID to cancel'),
-}, async ({ taskId }) => {
-    const client = await getTaskClient();
-    await client.cancelTask(taskId);
-    return { content: [{ type: 'text', text: `Task ${taskId} cancelled.` }] };
-});
-// ============================================================================
-// Tool: list_agents
-// ============================================================================
+}, (params) => listTasks(params, deps));
+server.tool('cancel_task', 'Cancel a running task', { taskId: z.string().describe('The task ID to cancel') }, (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'),
-    listing: z.enum(['public', 'private']).optional().describe('Filter by listing visibility (default: public)'),
+    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'),
-}, async ({ skill, listing, limit }) => {
-    const baseUrl = await getBaseUrl();
-    const apiKey = process.env.BLOCKS_API_KEY;
-    const result = await listAgentsAuthenticated({ baseUrl, apiKey, skill, listing, 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 header = `Agents (${result.totalCount ?? result.agents.length}):`;
-    return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
-});
-// ============================================================================
-// Tool: get_agent_card
-// ============================================================================
-server.tool('get_agent_card', 'Get the full agent card for a specific agent', {
-    agentName: z.string().describe('Agent name to look up'),
-}, async ({ agentName }) => {
-    const baseUrl = await getBaseUrl();
-    const apiKey = process.env.BLOCKS_API_KEY;
-    const entry = await getAgent(agentName, { baseUrl, apiKey });
-    if (!entry) {
-        return { content: [{ type: 'text', text: `Agent "${agentName}" not found.` }], isError: true };
-    }
-    return { content: [{ type: 'text', text: JSON.stringify(entry.card ?? entry, null, 2) }] };
-});
-// ============================================================================
-// Tool: connect_task
-// ============================================================================
+}, (params) => listAgents(params, deps));
+server.tool('get_agent_card', 'Get the full agent card for a specific agent', { agentName: z.string().describe('Agent name to look up') }, (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', {
     taskId: z.string().describe('The task ID to connect to'),
     timeoutMs: z.number().optional().describe('Timeout in milliseconds (default: 60000)'),
-}, async ({ taskId, timeoutMs }) => {
-    const freeClient = await getTaskClient('free');
-    const task = await freeClient.getTask(taskId);
-    const billingMode = resolveBillingMode(task);
-    const client = await getTaskClient(billingMode);
-    const session = await client.connect({ taskId });
-    const timeout = timeoutMs ?? 60000;
-    const results = [];
-    const streamOutputs = [];
-    const streamDrains = [];
-    session.onProgress((event) => {
-        if (event.message) {
-            results.push(`[progress] ${event.message}`);
-        }
-    });
-    const drainStream = (streamRef) => {
-        const dir = streamRef.descriptor.localDirection;
-        if (dir !== 'inbound' && dir !== 'bidirectional')
-            return;
-        const format = streamRef.descriptor.format;
-        const label = streamRef.descriptor.declaredStream ?? streamRef.descriptor.streamId;
-        const entry = { label, chunks: [] };
-        streamOutputs.push(entry);
-        try {
-            const streamClient = streamRef.open();
-            const drain = (async () => {
-                if (format === 'events') {
-                    for await (const event of streamClient.events()) {
-                        entry.chunks.push(JSON.stringify(event) + '\n');
-                    }
-                }
-                else {
-                    const decoder = new TextDecoder();
-                    for await (const chunk of streamClient.bytes()) {
-                        entry.chunks.push(decoder.decode(chunk, { stream: true }));
-                    }
-                }
-            })();
-            streamDrains.push(drain.catch(() => { }));
-        }
-        catch {
-            // stream already ended or terminal
-        }
-    };
-    for (const ref of session.listStreams()) {
-        drainStream(ref);
-    }
-    session.onStream(drainStream);
-    try {
-        const terminal = await session.waitForTerminal(timeout);
-        await Promise.allSettled(streamDrains);
-        const allArtifacts = session.listArtifacts();
-        results.unshift(`Task ${taskId} ${terminal.state}`);
-        for (const s of streamOutputs) {
-            if (s.chunks.length > 0) {
-                results.push(`[stream: ${s.label}]\n${s.chunks.join('')}`);
-            }
-        }
-        for (const ref of allArtifacts) {
-            try {
-                const downloaded = await session.downloadArtifact(ref);
-                const isText = downloaded.mimeType.startsWith('text/') ||
-                    downloaded.mimeType === 'application/json';
-                if (isText) {
-                    const text = new TextDecoder().decode(downloaded.data);
-                    results.push(`[artifact: ${downloaded.fileName ?? 'unnamed'}]\n${text}`);
-                }
-                else {
-                    results.push(`[artifact: ${downloaded.fileName ?? 'unnamed'}] (${downloaded.mimeType}, ${downloaded.data.length} bytes)`);
-                }
-            }
-            catch {
-                results.push(`[artifact: ${ref.fileName ?? 'unnamed'}] (download failed)`);
-            }
-        }
-        if (terminal.state === 'failed') {
-            results.push(`Error: ${terminal.error ?? terminal.reason ?? 'unknown'}`);
-        }
-        await session.asyncClose();
-        return { content: [{ type: 'text', text: results.join('\n') }] };
-    }
-    catch (err) {
-        await session.asyncClose();
-        const msg = err instanceof Error ? err.message : String(err);
-        const partial = [`Task ${taskId} timed out (${msg})`];
-        for (const s of streamOutputs) {
-            if (s.chunks.length > 0) {
-                partial.push(`[stream: ${s.label}]\n${s.chunks.join('')}`);
-            }
-        }
-        partial.push(...results);
-        return { content: [{ type: 'text', text: partial.join('\n') }], isError: true };
-    }
-});
-// ============================================================================
-// Start server
-// ============================================================================
+}, (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/dist/protocol-headers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare const PROTOCOL_VERSION_HEADER = "Blocks-Protocol-Version";
+export declare const CURRENT_PROTOCOL_VERSION = "2026-05-01";

package/dist/protocol-headers.js

@@ -0,0 +1,11 @@
+/**
+ * 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/dist/registry-list.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Authenticated registry list helper.
+ *
+ * Calls GET /api/v1/registry/agents with the Blocks-Protocol-Version
+ * header (required by the backend protocol-version middleware) and an
+ * optional Bearer API key for private/owned listings.
+ */
+export interface AgentListEntry {
+    agentName: string;
+    name?: string;
+    description?: string;
+    listing?: string;
+    billingMode?: string;
+    tags?: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+export interface ListAgentsOptions {
+    baseUrl: string;
+    apiKey?: string;
+    tag?: string;
+    listing?: 'public' | 'private';
+    limit?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface ListAgentsResult {
+    agents: AgentListEntry[];
+    totalCount?: number;
+}
+export declare function listAgentsAuthenticated(opts: ListAgentsOptions): Promise<ListAgentsResult>;

package/dist/registry-list.js

@@ -0,0 +1,32 @@
+/**
+ * Authenticated registry list helper.
+ *
+ * Calls GET /api/v1/registry/agents with the Blocks-Protocol-Version
+ * header (required by the backend protocol-version middleware) and an
+ * optional Bearer API key for private/owned listings.
+ */
+import { PROTOCOL_VERSION_HEADER, CURRENT_PROTOCOL_VERSION, } from './protocol-headers.js';
+export async function listAgentsAuthenticated(opts) {
+    const params = new URLSearchParams({ include: 'full' });
+    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));
+    const url = `${opts.baseUrl.replace(/\/+$/, '')}/api/v1/registry/agents?${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(`Registry list failed: HTTP ${response.status}`);
+    }
+    return (await response.json());
+}