@blocks-network/mcp-server 0.1.55 → 0.1.62

package/src/tools.ts

@@ -0,0 +1,496 @@
+/**
+ * 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';
+import {
+  textPart,
+  filePartFromPath,
+  type TaskInfo,
+  type SendMessageRequestPart,
+} from '@blocks-network/sdk';
+
+import type { ListAgentsResult } from './registry-list.js';
+
+// ============================================================================
+// Types — minimal local shapes mirroring @blocks-network/sdk surfaces.
+// Using narrow interfaces (instead of importing the SDK classes) keeps
+// the tests free of PubNub/runtime dependencies.
+// ============================================================================
+
+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>;
+  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;
+    skill?: string;
+    listing?: 'public' | 'private';
+    limit?: number;
+  }): Promise<ListAgentsResult>;
+  validateFilePath(filePath: string): string;
+  fileSize(path: string): number;
+  maxUploadBytes: number;
+  filePartFromPath: typeof filePartFromPath;
+  textPart: typeof textPart;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+const TERMINAL_STATES = new Set(['completed', 'failed', 'canceled']);
+
+function resolveBillingMode(task: TaskInfo): 'free' | 'paid' {
+  const mode = task.billingMode as string | undefined;
+  return mode === 'paid' ? 'paid' : 'free';
+}
+
+function isTextLikeContentType(ct: string): boolean {
+  return ct.startsWith('text/') || ct === 'application/json' || ct.endsWith('+json');
+}
+
+function isTextMimeType(mimeType: string): boolean {
+  return mimeType.startsWith('text/') || mimeType === 'application/json';
+}
+
+async function appendArtifacts(
+  session: TaskSessionLike,
+  refs: ArtifactRef[],
+  out: string[],
+): Promise<void> {
+  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)`);
+    }
+  }
+}
+
+// ============================================================================
+// Tool params
+// ============================================================================
+
+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 {
+  skill?: string;
+  listing?: 'public' | 'private';
+  limit?: number;
+}
+
+export interface GetAgentCardParams {
+  agentName: string;
+}
+
+export interface ConnectTaskParams {
+  taskId: string;
+  timeoutMs?: number;
+}
+
+// ============================================================================
+// send_task
+// ============================================================================
+
+export async function sendTask(
+  params: SendTaskParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  const baseUrl = await deps.getBaseUrl();
+  const apiKey = deps.getApiKey();
+  const entry = await deps.getAgentByName(params.agentName, { baseUrl, apiKey });
+  const billingMode: 'free' | 'paid' = 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: SendMessageRequestPart[] = [];
+  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: string[] = [];
+  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: GetTaskParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  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: ListTasksParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  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: TaskInfo) =>
+      `${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: CancelTaskParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  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: ListAgentsParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  const baseUrl = await deps.getBaseUrl();
+  const apiKey = deps.getApiKey();
+  const result = await deps.listAgents({
+    baseUrl,
+    apiKey,
+    skill: params.skill,
+    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 header = `Agents (${result.totalCount ?? result.agents.length}):`;
+  return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
+}
+
+// ============================================================================
+// get_agent_card
+// ============================================================================
+
+export async function getAgentCard(
+  params: GetAgentCardParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  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: ConnectTaskParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  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: string[] = [];
+  const streamOutputs: Array<{ label: string; chunks: string[] }> = [];
+  const streamDrains: Promise<void>[] = [];
+
+  session.onProgress((event) => {
+    if (event.message) progressLines.push(`[progress] ${event.message}`);
+  });
+
+  const drainStream = (streamRef: 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: [] as string[] };
+    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: string[] = [`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: string[] = [`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 };
+  }
+}
+
+// ============================================================================
+// Default file helpers (re-exported so index.ts can build a default ToolDeps)
+// ============================================================================
+
+export function defaultFileSize(path: string): number {
+  return statSync(path).size;
+}

package/tests/cancel-task.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { cancelTask } from '../src/tools.js';
+import { makeFakeDeps, makeFakeClient } from './helpers.js';
+
+describe('cancel_task', () => {
+  it('calls client.cancelTask with the supplied id and confirms', async () => {
+    const client = makeFakeClient();
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await cancelTask({ taskId: 'task_xyz' }, deps);
+
+    expect(client.cancelTaskMock).toHaveBeenCalledWith('task_xyz');
+    expect(res.content[0].text).toBe('Task task_xyz cancelled.');
+    expect(res.isError).toBeUndefined();
+  });
+
+  it('propagates errors from cancelTask', async () => {
+    const client = makeFakeClient();
+    client.cancelTaskMock.mockRejectedValueOnce(new Error('not allowed'));
+    const { deps } = makeFakeDeps({ client });
+
+    await expect(cancelTask({ taskId: 'task_zzz' }, deps)).rejects.toThrow('not allowed');
+  });
+});

package/tests/connect-task.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect } from 'vitest';
+import { connectTask } from '../src/tools.js';
+import {
+  asyncIterFrom,
+  makeFakeClient,
+  makeFakeDeps,
+  makeFakeSession,
+} from './helpers.js';
+import type { StreamRef } from '../src/tools.js';
+
+function makeStreamRef(opts: {
+  streamId: string;
+  declaredStream?: string;
+  format: 'events' | 'bytes';
+  localDirection: 'inbound' | 'outbound' | 'bidirectional';
+  events?: unknown[];
+  bytes?: Uint8Array[];
+}): StreamRef {
+  return {
+    descriptor: {
+      streamId: opts.streamId,
+      declaredStream: opts.declaredStream,
+      format: opts.format,
+      localDirection: opts.localDirection,
+    },
+    open: () => ({
+      events: () => asyncIterFrom(opts.events ?? []),
+      bytes: () => asyncIterFrom(opts.bytes ?? []),
+    }),
+  };
+}
+
+describe('connect_task', () => {
+  it('drains inbound event streams and includes them in the output', async () => {
+    const stream = makeStreamRef({
+      streamId: 's1',
+      declaredStream: 'thoughts',
+      format: 'events',
+      localDirection: 'inbound',
+      events: [{ kind: 'tick', n: 1 }, { kind: 'tick', n: 2 }],
+    });
+    const session = makeFakeSession({
+      taskId: 't1',
+      streams: [stream],
+      terminal: { state: 'completed' },
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't1', state: 'running' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await connectTask({ taskId: 't1' }, deps);
+
+    expect(res.content[0].text).toContain('Task t1 completed');
+    expect(res.content[0].text).toContain('[stream: thoughts]');
+    expect(res.content[0].text).toContain('{"kind":"tick","n":1}');
+    expect(res.content[0].text).toContain('{"kind":"tick","n":2}');
+    expect(session.asyncCloseMock).toHaveBeenCalledOnce();
+  });
+
+  it('drains inbound byte streams and decodes UTF-8', async () => {
+    const stream = makeStreamRef({
+      streamId: 's2',
+      format: 'bytes',
+      localDirection: 'inbound',
+      bytes: [
+        new TextEncoder().encode('hello '),
+        new TextEncoder().encode('world'),
+      ],
+    });
+    const session = makeFakeSession({
+      streams: [stream],
+      terminal: { state: 'completed' },
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't2', state: 'running' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await connectTask({ taskId: 't2' }, deps);
+    expect(res.content[0].text).toContain('[stream: s2]\nhello world');
+  });
+
+  it('skips outbound-only streams', async () => {
+    const stream = makeStreamRef({
+      streamId: 's3',
+      format: 'events',
+      localDirection: 'outbound',
+      events: [{ ignored: true }],
+    });
+    const session = makeFakeSession({
+      streams: [stream],
+      terminal: { state: 'completed' },
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't3', state: 'running' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await connectTask({ taskId: 't3' }, deps);
+    expect(res.content[0].text).not.toContain('[stream:');
+  });
+
+  it('drains streams that arrive after connect via onStream callback', async () => {
+    const session = makeFakeSession({
+      streams: [],
+      lateStreams: [
+        makeStreamRef({
+          streamId: 'late',
+          format: 'events',
+          localDirection: 'bidirectional',
+          events: [{ msg: 'late-arrival' }],
+        }),
+      ],
+      terminal: { state: 'completed' },
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't4', state: 'running' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await connectTask({ taskId: 't4' }, deps);
+    expect(res.content[0].text).toContain('[stream: late]');
+    expect(res.content[0].text).toContain('"late-arrival"');
+  });
+
+  it('returns isError=true and partial stream output when waitForTerminal rejects', async () => {
+    const stream = makeStreamRef({
+      streamId: 's5',
+      format: 'events',
+      localDirection: 'inbound',
+      events: [{ tick: 1 }],
+    });
+    const session = makeFakeSession({
+      streams: [stream],
+      terminalRejects: new Error('timeout'),
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't5', state: 'running' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await connectTask({ taskId: 't5' }, deps);
+
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain('Task t5 timed out (timeout)');
+    expect(session.asyncCloseMock).toHaveBeenCalledOnce();
+  });
+
+  it('routes paid tasks through the paid TaskClient', async () => {
+    const client = makeFakeClient({
+      task: { taskId: 't6', state: 'running', billingMode: 'paid' },
+    });
+    const { deps, mocks } = makeFakeDeps({ client });
+
+    await connectTask({ taskId: 't6' }, deps);
+
+    expect(mocks.getTaskClient).toHaveBeenCalledWith('free');
+    expect(mocks.getTaskClient).toHaveBeenCalledWith('paid');
+  });
+
+  it('appends "Error:" line for failed terminals', async () => {
+    const session = makeFakeSession({
+      terminal: { state: 'failed', reason: 'boom' },
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't7', state: 'running' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await connectTask({ taskId: 't7' }, deps);
+    expect(res.content[0].text).toContain('Error: boom');
+  });
+});