@blocks-network/mcp-server 0.1.55 → 0.1.64

package/dist/tools.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Tool handlers for the Blocks Network MCP server.
+ *
+ * Each handler is a pure function that takes its dependencies (clients,
+ * registry helpers, fs/path utilities) so it can be unit-tested without
+ * touching the network or the filesystem.
+ */
+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;
+}
+export interface DownloadedArtifact {
+    fileName?: string;
+    mimeType: string;
+    data: Uint8Array;
+}
+export interface StreamDescriptor {
+    localDirection: string;
+    format: string;
+    declaredStream?: string;
+    streamId: string;
+}
+export interface StreamClient {
+    events(): AsyncIterable<unknown>;
+    bytes(): AsyncIterable<Uint8Array>;
+}
+export interface StreamRef {
+    descriptor: StreamDescriptor;
+    open(): StreamClient;
+}
+export interface ProgressEvent {
+    message?: string;
+}
+export interface TerminalEvent {
+    state: string;
+    error?: string;
+    reason?: string;
+}
+export interface TaskSessionLike {
+    taskId: string;
+    onProgress(cb: (event: ProgressEvent) => void): unknown;
+    onStream(cb: (ref: StreamRef) => void): unknown;
+    listArtifacts(): ArtifactRef[];
+    listStreams(): StreamRef[];
+    downloadArtifact(ref: ArtifactRef): Promise<DownloadedArtifact>;
+    waitForTerminal(timeoutMs?: number): Promise<TerminalEvent>;
+    close(): void;
+    asyncClose(): Promise<void>;
+}
+export interface TaskClientLike {
+    sendMessage(params: {
+        agentName: string;
+        requestParts: SendMessageRequestPart[];
+        taskKind?: 'request' | 'pipe';
+        duration?: number;
+    }): Promise<TaskSessionLike>;
+    getTask(taskId: string): Promise<TaskInfo>;
+    listTasks(params: {
+        agentName?: string;
+        state?: string;
+        limit?: number;
+    }): Promise<{
+        tasks: TaskInfo[];
+        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>;
+}
+export interface AgentEntryLike {
+    agentName: string;
+    card?: {
+        io?: {
+            inputs?: Array<{
+                id: string;
+                contentType: string;
+            }>;
+        };
+    };
+    billingMode?: 'free' | 'paid';
+}
+export interface ToolResult {
+    [k: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export interface ToolDeps {
+    getBaseUrl(): Promise<string>;
+    getApiKey(): string | undefined;
+    getTaskClient(billingMode?: 'free' | 'paid'): Promise<TaskClientLike>;
+    getAgentByName(agentName: string, options: {
+        baseUrl: string;
+        apiKey?: string;
+    }): Promise<AgentEntryLike | null>;
+    listAgents(options: {
+        baseUrl: string;
+        apiKey?: string;
+        tag?: string;
+        listing?: 'public' | 'private';
+        limit?: 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;
+    message: string;
+    filePath?: string;
+    inputs?: Record<string, string>;
+    taskKind?: 'request' | 'pipe';
+    duration?: number;
+    timeoutMs?: number;
+}
+export interface GetTaskParams {
+    taskId: string;
+}
+export interface ListTasksParams {
+    agentName?: string;
+    state?: string;
+    limit?: number;
+}
+export interface CancelTaskParams {
+    taskId: string;
+}
+export interface ListAgentsParams {
+    tag?: string;
+    listing?: 'public' | 'private';
+    limit?: number;
+}
+export interface GetAgentCardParams {
+    agentName: string;
+}
+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 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

@@ -0,0 +1,441 @@
+/**
+ * Tool handlers for the Blocks Network MCP server.
+ *
+ * Each handler is a pure function that takes its dependencies (clients,
+ * registry helpers, fs/path utilities) so it can be unit-tested without
+ * touching the network or the filesystem.
+ */
+import { statSync } from 'node:fs';
+// ============================================================================
+// Helpers
+// ============================================================================
+const TERMINAL_STATES = new Set(['completed', 'failed', 'canceled']);
+function resolveBillingMode(task) {
+    const mode = task.billingMode;
+    return mode === 'paid' ? 'paid' : 'free';
+}
+function isTextLikeContentType(ct) {
+    return ct.startsWith('text/') || ct === 'application/json' || ct.endsWith('+json');
+}
+function isTextMimeType(mimeType) {
+    return mimeType.startsWith('text/') || mimeType === 'application/json';
+}
+async function appendArtifacts(session, refs, out) {
+    for (const ref of refs) {
+        try {
+            const downloaded = await session.downloadArtifact(ref);
+            if (isTextMimeType(downloaded.mimeType)) {
+                const text = new TextDecoder().decode(downloaded.data);
+                out.push(`[artifact: ${downloaded.fileName ?? 'unnamed'}]\n${text}`);
+            }
+            else {
+                out.push(`[artifact: ${downloaded.fileName ?? 'unnamed'}] (${downloaded.mimeType}, ${downloaded.data.length} bytes)`);
+            }
+        }
+        catch {
+            out.push(`[artifact: ${ref.fileName ?? 'unnamed'}] (download failed)`);
+        }
+    }
+}
+// ============================================================================
+// send_task
+// ============================================================================
+export async function sendTask(params, deps) {
+    const baseUrl = await deps.getBaseUrl();
+    const apiKey = deps.getApiKey();
+    const entry = await deps.getAgentByName(params.agentName, { baseUrl, apiKey });
+    const billingMode = entry?.billingMode ?? 'free';
+    const client = await deps.getTaskClient(billingMode);
+    const declaredInputs = entry?.card?.io?.inputs ?? [];
+    const textInput = declaredInputs.find((i) => isTextLikeContentType(i.contentType));
+    const fileInput = declaredInputs.find((i) => !isTextLikeContentType(i.contentType));
+    const requestParts = [];
+    const textPartId = textInput?.id ?? 'text';
+    if ((textInput || declaredInputs.length === 0) && !params.inputs?.[textPartId]) {
+        requestParts.push(deps.textPart(params.message, textPartId));
+    }
+    if (params.filePath) {
+        const safePath = deps.validateFilePath(params.filePath);
+        const size = deps.fileSize(safePath);
+        if (size > deps.maxUploadBytes) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `File too large (${size} bytes). Maximum upload size is ${deps.maxUploadBytes} bytes (25 MB).`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        requestParts.push(await deps.filePartFromPath(safePath, {
+            partId: fileInput?.id ?? 'file',
+            contentType: fileInput?.contentType,
+        }));
+    }
+    if (params.inputs) {
+        for (const [partId, value] of Object.entries(params.inputs)) {
+            requestParts.push(deps.textPart(value, partId));
+        }
+    }
+    const session = await client.sendMessage({
+        agentName: params.agentName,
+        requestParts,
+        taskKind: params.taskKind,
+        duration: params.duration,
+    });
+    const timeout = params.timeoutMs ?? 60000;
+    const progressLines = [];
+    session.onProgress((event) => {
+        if (event.message)
+            progressLines.push(`[progress] ${event.message}`);
+    });
+    try {
+        const terminal = await session.waitForTerminal(timeout);
+        const output = [`Task ${session.taskId} ${terminal.state}`, ...progressLines];
+        await appendArtifacts(session, session.listArtifacts(), output);
+        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,
+        };
+    }
+}
+// ============================================================================
+// get_task
+// ============================================================================
+export async function getTask(params, deps) {
+    const freeClient = await deps.getTaskClient('free');
+    const task = await freeClient.getTask(params.taskId);
+    const output = [JSON.stringify(task, null, 2)];
+    if (task.state && TERMINAL_STATES.has(task.state)) {
+        try {
+            const billingMode = resolveBillingMode(task);
+            const client = await deps.getTaskClient(billingMode);
+            const session = await client.connect({ taskId: params.taskId });
+            await appendArtifacts(session, session.listArtifacts(), output);
+            session.close();
+        }
+        catch {
+            // connect failed — return task info without artifacts
+        }
+    }
+    return { content: [{ type: 'text', text: output.join('\n') }] };
+}
+// ============================================================================
+// list_tasks
+// ============================================================================
+export async function listTasks(params, deps) {
+    const client = await deps.getTaskClient();
+    const result = await client.listTasks({
+        agentName: params.agentName,
+        state: params.state,
+        limit: params.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') }] };
+}
+// ============================================================================
+// cancel_task
+// ============================================================================
+export async function cancelTask(params, deps) {
+    const client = await deps.getTaskClient();
+    await client.cancelTask(params.taskId);
+    return { content: [{ type: 'text', text: `Task ${params.taskId} cancelled.` }] };
+}
+// ============================================================================
+// list_agents
+// ============================================================================
+export async function listAgents(params, deps) {
+    const baseUrl = await deps.getBaseUrl();
+    const apiKey = deps.getApiKey();
+    const result = await deps.listAgents({
+        baseUrl,
+        apiKey,
+        tag: params.tag,
+        listing: params.listing,
+        limit: params.limit,
+    });
+    const lines = result.agents.map((a) => {
+        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') }] };
+}
+// ============================================================================
+// get_agent_card
+// ============================================================================
+export async function getAgentCard(params, deps) {
+    const baseUrl = await deps.getBaseUrl();
+    const apiKey = deps.getApiKey();
+    const entry = await deps.getAgentByName(params.agentName, { baseUrl, apiKey });
+    if (!entry) {
+        return {
+            content: [{ type: 'text', text: `Agent "${params.agentName}" not found.` }],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(entry.card ?? entry, null, 2) }],
+    };
+}
+// ============================================================================
+// connect_task
+// ============================================================================
+export async function connectTask(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);
+    const session = await client.connect({ taskId: params.taskId });
+    const timeout = params.timeoutMs ?? 60000;
+    const progressLines = [];
+    const streamOutputs = [];
+    const streamDrains = [];
+    session.onProgress((event) => {
+        if (event.message)
+            progressLines.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 out = [`Task ${params.taskId} ${terminal.state}`, ...progressLines];
+        for (const s of streamOutputs) {
+            if (s.chunks.length > 0) {
+                out.push(`[stream: ${s.label}]\n${s.chunks.join('')}`);
+            }
+        }
+        await appendArtifacts(session, session.listArtifacts(), out);
+        if (terminal.state === 'failed') {
+            out.push(`Error: ${terminal.error ?? terminal.reason ?? 'unknown'}`);
+        }
+        await session.asyncClose();
+        return { content: [{ type: 'text', text: out.join('\n') }] };
+    }
+    catch (err) {
+        await session.asyncClose();
+        const msg = err instanceof Error ? err.message : String(err);
+        const partial = [`Task ${params.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(...progressLines);
+        return { content: [{ type: 'text', text: partial.join('\n') }], isError: true };
+    }
+}
+// ============================================================================
+// 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) {
+    return statSync(path).size;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocks-network/mcp-server",
-  "version": "0.1.55",
+  "version": "0.1.64",
   "description": "MCP server for Blocks Network consumer operations",
   "type": "module",
   "main": "dist/index.js",
@@ -12,19 +12,31 @@
     "prebuild": "npm run build:sdk",
     "build": "tsc",
     "start": "node dist/index.js",
-    "dev": "tsx src/index.ts"
+    "dev": "tsx src/index.ts",
+    "test": "vitest run"
   },
   "dependencies": {
-    "@blocks-network/sdk": "file:../sdks/node",
-    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@blocks-network/sdk": "^0.1.60",
+    "@modelcontextprotocol/sdk": "^1.29",
     "zod": "^3.25.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4"
   },
   "engines": {
     "node": ">=20.0.0"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blocksnetwork/blocks-sdk.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://github.com/blocksnetwork/blocks-sdk/tree/main/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/blocksnetwork/blocks-sdk/issues"
+  },
+  "license": "SEE LICENSE IN LICENSE"
 }