@blocks-network/mcp-server 0.1.55 → 0.1.62

package/tests/get-agent-card.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { getAgentCard } from '../src/tools.js';
+import { makeFakeDeps } from './helpers.js';
+
+describe('get_agent_card', () => {
+  it('returns the agent card JSON when found', async () => {
+    const card = {
+      io: { inputs: [{ id: 'prompt', contentType: 'text/plain' }] },
+    };
+    const { deps } = makeFakeDeps({
+      agentEntry: { agentName: 'alice', card },
+    });
+
+    const res = await getAgentCard({ agentName: 'alice' }, deps);
+
+    expect(res.isError).toBeUndefined();
+    expect(JSON.parse(res.content[0].text)).toEqual(card);
+  });
+
+  it('returns isError=true with a friendly message when not found', async () => {
+    const { deps } = makeFakeDeps({ agentEntry: null });
+
+    const res = await getAgentCard({ agentName: 'ghost' }, deps);
+
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toBe('Agent "ghost" not found.');
+  });
+
+  it('falls back to the bare entry JSON when the card field is missing', async () => {
+    const { deps } = makeFakeDeps({
+      agentEntry: { agentName: 'cardless', billingMode: 'free' },
+    });
+
+    const res = await getAgentCard({ agentName: 'cardless' }, deps);
+    const parsed = JSON.parse(res.content[0].text);
+    expect(parsed).toMatchObject({ agentName: 'cardless', billingMode: 'free' });
+  });
+
+  it('passes baseUrl + apiKey through to getAgentByName', async () => {
+    const { deps, mocks } = makeFakeDeps({
+      apiKey: 'sk-test',
+      baseUrl: 'http://api.test',
+      agentEntry: { agentName: 'alice' },
+    });
+
+    await getAgentCard({ agentName: 'alice' }, deps);
+
+    expect(mocks.getAgentByName).toHaveBeenCalledWith('alice', {
+      baseUrl: 'http://api.test',
+      apiKey: 'sk-test',
+    });
+  });
+});

package/tests/get-task.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { getTask } from '../src/tools.js';
+import { makeFakeDeps, makeFakeClient, makeFakeSession } from './helpers.js';
+
+describe('get_task', () => {
+  it('returns the task JSON for a still-running task without connecting', async () => {
+    const client = makeFakeClient({
+      task: { taskId: 't1', state: 'running', agentName: 'alice' },
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await getTask({ taskId: 't1' }, deps);
+
+    expect(client.connectMock).not.toHaveBeenCalled();
+    const parsed = JSON.parse(res.content[0].text);
+    expect(parsed).toMatchObject({ taskId: 't1', state: 'running' });
+  });
+
+  it('connects on terminal state and appends artifact content', async () => {
+    const session = makeFakeSession({
+      artifacts: [
+        {
+          fileName: 'output.json',
+          mimeType: 'application/json',
+          data: new TextEncoder().encode('{"ok":true}'),
+        },
+      ],
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't2', state: 'completed' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await getTask({ taskId: 't2' }, deps);
+
+    expect(client.connectMock).toHaveBeenCalledWith({ taskId: 't2' });
+    expect(res.content[0].text).toContain('[artifact: output.json]');
+    expect(res.content[0].text).toContain('{"ok":true}');
+    expect(session.closeMock).toHaveBeenCalledOnce();
+  });
+
+  it('uses paid TaskClient for paid tasks', async () => {
+    const client = makeFakeClient({
+      task: { taskId: 't3', state: 'completed', billingMode: 'paid' },
+    });
+    const { deps, mocks } = makeFakeDeps({ client });
+
+    await getTask({ taskId: 't3' }, deps);
+
+    expect(mocks.getTaskClient).toHaveBeenCalledWith('free');
+    expect(mocks.getTaskClient).toHaveBeenCalledWith('paid');
+  });
+
+  it('falls back to task JSON only when connect fails', async () => {
+    const client = makeFakeClient({
+      task: { taskId: 't4', state: 'failed' },
+    });
+    client.connectMock.mockRejectedValueOnce(new Error('connect refused'));
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await getTask({ taskId: 't4' }, deps);
+    expect(res.isError).toBeUndefined();
+    expect(res.content[0].text).toContain('"taskId": "t4"');
+  });
+
+  it('connects for canceled tasks (also a terminal state)', async () => {
+    const client = makeFakeClient({
+      task: { taskId: 't5', state: 'canceled' },
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    await getTask({ taskId: 't5' }, deps);
+    expect(client.connectMock).toHaveBeenCalled();
+  });
+});

package/tests/helpers.ts

@@ -0,0 +1,188 @@
+import { vi } from 'vitest';
+import type {
+  AgentEntryLike,
+  ArtifactRef,
+  DownloadedArtifact,
+  ProgressEvent,
+  StreamRef,
+  TaskClientLike,
+  TaskSessionLike,
+  TerminalEvent,
+  ToolDeps,
+} from '../src/tools.js';
+import type { ListAgentsResult } from '../src/registry-list.js';
+import type { TaskInfo } from '@blocks-network/sdk';
+
+export interface FakeSessionConfig {
+  taskId?: string;
+  artifacts?: Array<{
+    fileName?: string;
+    mimeType: string;
+    data: Uint8Array;
+    downloadFails?: boolean;
+  }>;
+  streams?: StreamRef[];
+  /** Streams delivered via onStream() callback after registration. */
+  lateStreams?: StreamRef[];
+  terminal?: TerminalEvent;
+  terminalRejects?: Error;
+  progressEvents?: ProgressEvent[];
+}
+
+export function makeFakeSession(cfg: FakeSessionConfig = {}): TaskSessionLike & {
+  closeMock: ReturnType<typeof vi.fn>;
+  asyncCloseMock: ReturnType<typeof vi.fn>;
+  emitStream: (ref: StreamRef) => void;
+} {
+  const taskId = cfg.taskId ?? 'task_123';
+  const refs: ArtifactRef[] = (cfg.artifacts ?? []).map((a) => ({ fileName: a.fileName }));
+  const streamCallbacks: Array<(ref: StreamRef) => void> = [];
+  const closeMock = vi.fn();
+  const asyncCloseMock = vi.fn().mockResolvedValue(undefined);
+
+  const session = {
+    taskId,
+    onProgress(cb: (e: ProgressEvent) => void) {
+      for (const e of cfg.progressEvents ?? []) cb(e);
+      return () => {};
+    },
+    onStream(cb: (ref: StreamRef) => void) {
+      streamCallbacks.push(cb);
+      for (const ref of cfg.lateStreams ?? []) cb(ref);
+      return () => {};
+    },
+    listArtifacts() {
+      return refs;
+    },
+    listStreams() {
+      return cfg.streams ?? [];
+    },
+    async downloadArtifact(ref: ArtifactRef): Promise<DownloadedArtifact> {
+      const idx = refs.indexOf(ref);
+      const a = (cfg.artifacts ?? [])[idx];
+      if (!a || a.downloadFails) throw new Error('download failed');
+      return { fileName: a.fileName, mimeType: a.mimeType, data: a.data };
+    },
+    async waitForTerminal(_timeoutMs?: number) {
+      if (cfg.terminalRejects) throw cfg.terminalRejects;
+      return cfg.terminal ?? { state: 'completed' };
+    },
+    close: closeMock,
+    asyncClose: asyncCloseMock,
+  };
+
+  return Object.assign(session, {
+    closeMock,
+    asyncCloseMock,
+    emitStream: (ref: StreamRef) => {
+      for (const cb of streamCallbacks) cb(ref);
+    },
+  });
+}
+
+export interface FakeClientConfig {
+  session?: TaskSessionLike;
+  task?: TaskInfo;
+  listResult?: { tasks: TaskInfo[]; totalCount?: number };
+}
+
+export function makeFakeClient(cfg: FakeClientConfig = {}): TaskClientLike & {
+  sendMessageMock: ReturnType<typeof vi.fn>;
+  cancelTaskMock: ReturnType<typeof vi.fn>;
+  connectMock: ReturnType<typeof vi.fn>;
+  listTasksMock: ReturnType<typeof vi.fn>;
+  getTaskMock: ReturnType<typeof vi.fn>;
+} {
+  const session = cfg.session ?? makeFakeSession();
+  const sendMessageMock = vi.fn().mockResolvedValue(session);
+  const connectMock = vi.fn().mockResolvedValue(session);
+  const cancelTaskMock = vi.fn().mockResolvedValue(undefined);
+  const listTasksMock = vi.fn().mockResolvedValue(
+    cfg.listResult ?? { tasks: [], totalCount: 0 },
+  );
+  const getTaskMock = vi.fn().mockResolvedValue(cfg.task ?? { taskId: 't0', state: 'running' });
+
+  return {
+    sendMessage: sendMessageMock,
+    cancelTask: cancelTaskMock,
+    connect: connectMock,
+    listTasks: listTasksMock,
+    getTask: getTaskMock,
+    sendMessageMock,
+    cancelTaskMock,
+    connectMock,
+    listTasksMock,
+    getTaskMock,
+  };
+}
+
+export interface FakeDepsOverrides {
+  baseUrl?: string;
+  apiKey?: string;
+  client?: TaskClientLike;
+  agentEntry?: AgentEntryLike | null;
+  listAgentsResult?: ListAgentsResult;
+  maxUploadBytes?: number;
+  fileSize?: number;
+}
+
+export function makeFakeDeps(overrides: FakeDepsOverrides = {}) {
+  const client = overrides.client ?? makeFakeClient();
+  const getBaseUrl = vi.fn().mockResolvedValue(overrides.baseUrl ?? 'http://api.test');
+  const getApiKey = vi.fn().mockReturnValue(overrides.apiKey);
+  const getTaskClient = vi.fn().mockResolvedValue(client);
+  const getAgentByName = vi.fn().mockResolvedValue(overrides.agentEntry ?? null);
+  const listAgents = vi
+    .fn()
+    .mockResolvedValue(overrides.listAgentsResult ?? { agents: [], totalCount: 0 });
+  const validateFilePath = vi.fn((p: string) => p);
+  const fileSize = vi.fn().mockReturnValue(overrides.fileSize ?? 100);
+  const filePartFromPath = vi.fn(async (path: string, opts: { partId?: string; contentType?: string }) => ({
+    type: 'file' as const,
+    partId: opts.partId ?? 'file',
+    file: { id: 'file-id', mimeType: opts.contentType ?? 'application/octet-stream' },
+    _path: path,
+  }));
+  const textPart = vi.fn((text: string, partId: string) => ({
+    type: 'text' as const,
+    partId,
+    text,
+  }));
+
+  const deps: ToolDeps = {
+    getBaseUrl,
+    getApiKey,
+    getTaskClient,
+    getAgentByName,
+    listAgents,
+    validateFilePath,
+    fileSize,
+    maxUploadBytes: overrides.maxUploadBytes ?? 25 * 1024 * 1024,
+    filePartFromPath: filePartFromPath as unknown as ToolDeps['filePartFromPath'],
+    textPart: textPart as unknown as ToolDeps['textPart'],
+  };
+
+  return {
+    deps,
+    client,
+    mocks: {
+      getBaseUrl,
+      getApiKey,
+      getTaskClient,
+      getAgentByName,
+      listAgents,
+      validateFilePath,
+      fileSize,
+      filePartFromPath,
+      textPart,
+    },
+  };
+}
+
+export function asyncIterFrom<T>(items: T[]): AsyncIterable<T> {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const i of items) yield i;
+    },
+  };
+}

package/tests/list-agents.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { listAgents } from '../src/tools.js';
+import { makeFakeDeps } from './helpers.js';
+
+describe('list_agents', () => {
+  it('renders one row per agent with skill names joined by commas', async () => {
+    const { deps } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [
+          {
+            agentName: 'alice',
+            name: 'Alice',
+            listing: 'public',
+            skills: [
+              { id: 'translate', name: 'Translate' },
+              { id: 'summarize', name: 'Summarize' },
+            ],
+          },
+          { agentName: 'bob', listing: 'private' },
+        ],
+        totalCount: 2,
+      },
+    });
+
+    const res = await listAgents({}, deps);
+    const lines = res.content[0].text.split('\n');
+    expect(lines).toEqual([
+      'Agents (2):',
+      'alice | Alice | public | Translate, Summarize',
+      'bob | bob | private | ',
+    ]);
+  });
+
+  it('forwards baseUrl, apiKey, skill, listing, limit to the registry helper', async () => {
+    const { deps, mocks } = makeFakeDeps({
+      apiKey: 'sk-test',
+      baseUrl: 'http://api.test',
+    });
+
+    await listAgents(
+      { skill: 'translate', listing: 'private', limit: 25 },
+      deps,
+    );
+
+    expect(mocks.listAgents).toHaveBeenCalledWith({
+      baseUrl: 'http://api.test',
+      apiKey: 'sk-test',
+      skill: 'translate',
+      listing: 'private',
+      limit: 25,
+    });
+  });
+
+  it('defaults to "public" for missing listing and uses agentName when name is absent', async () => {
+    const { deps } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [{ agentName: 'naked', skills: [] }],
+        totalCount: 1,
+      },
+    });
+
+    const res = await listAgents({}, deps);
+    expect(res.content[0].text).toContain('naked | naked | public |');
+  });
+
+  it('uses agents.length as the count when totalCount is omitted', async () => {
+    const { deps } = makeFakeDeps({
+      listAgentsResult: { agents: [{ agentName: 'a' }, { agentName: 'b' }] },
+    });
+
+    const res = await listAgents({}, deps);
+    expect(res.content[0].text.split('\n')[0]).toBe('Agents (2):');
+  });
+});

package/tests/list-tasks.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import { listTasks } from '../src/tools.js';
+import { makeFakeDeps, makeFakeClient } from './helpers.js';
+
+describe('list_tasks', () => {
+  it('renders one row per task with header showing totalCount', async () => {
+    const client = makeFakeClient({
+      listResult: {
+        tasks: [
+          { taskId: 'a', agentName: 'alice', state: 'running', createdTime: '2026-05-18T00:00:00Z' },
+          { taskId: 'b', agentName: 'bob', state: 'completed', createdTime: '2026-05-18T00:01:00Z' },
+        ],
+        totalCount: 17,
+      },
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await listTasks({}, deps);
+    expect(res.content[0].text.split('\n')).toEqual([
+      'Tasks (17 total):',
+      'a | alice | running | 2026-05-18T00:00:00Z',
+      'b | bob | completed | 2026-05-18T00:01:00Z',
+    ]);
+  });
+
+  it('forwards filters to the client', async () => {
+    const client = makeFakeClient();
+    const { deps } = makeFakeDeps({ client });
+
+    await listTasks({ agentName: 'alice', state: 'failed', limit: 5 }, deps);
+
+    expect(client.listTasksMock).toHaveBeenCalledWith({
+      agentName: 'alice',
+      state: 'failed',
+      limit: 5,
+    });
+  });
+
+  it('substitutes "?" for missing agentName/state', async () => {
+    const client = makeFakeClient({
+      listResult: { tasks: [{ taskId: 'x' }] },
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await listTasks({}, deps);
+    expect(res.content[0].text).toContain('x | ? | ? |');
+  });
+
+  it('falls back to tasks.length when totalCount is omitted', async () => {
+    const client = makeFakeClient({
+      listResult: { tasks: [{ taskId: 'x' }, { taskId: 'y' }] },
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await listTasks({}, deps);
+    expect(res.content[0].text).toMatch(/^Tasks \(2 total\):/);
+  });
+});

package/tests/registry-list.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  listAgentsAuthenticated,
+  PROTOCOL_VERSION_HEADER,
+  CURRENT_PROTOCOL_VERSION,
+} from '../src/registry-list.js';
+
+function mockResponse(body: unknown, ok = true, status = 200): Response {
+  return {
+    ok,
+    status,
+    json: async () => body,
+  } as Response;
+}
+
+describe('listAgentsAuthenticated', () => {
+  it('sends Blocks-Protocol-Version header on every request', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      mockResponse({ agents: [], totalCount: 0 }),
+    );
+
+    await listAgentsAuthenticated({
+      baseUrl: 'http://api.test',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    expect(fetchImpl).toHaveBeenCalledOnce();
+    const [, init] = fetchImpl.mock.calls[0];
+    const headers = init?.headers as Record<string, string>;
+    expect(headers[PROTOCOL_VERSION_HEADER]).toBe(CURRENT_PROTOCOL_VERSION);
+    expect(CURRENT_PROTOCOL_VERSION).toBe('2026-05-01');
+  });
+
+  it('protocol version header is present even when an API key is supplied', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      mockResponse({ agents: [], totalCount: 0 }),
+    );
+
+    await listAgentsAuthenticated({
+      baseUrl: 'http://api.test',
+      apiKey: 'secret-key',
+      listing: 'private',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    const [, init] = fetchImpl.mock.calls[0];
+    const headers = init?.headers as Record<string, string>;
+    expect(headers[PROTOCOL_VERSION_HEADER]).toBe(CURRENT_PROTOCOL_VERSION);
+    expect(headers['Authorization']).toBe('Bearer secret-key');
+  });
+
+  it('builds the registry URL with include=full and listing/scope params', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      mockResponse({ agents: [], totalCount: 0 }),
+    );
+
+    await listAgentsAuthenticated({
+      baseUrl: 'http://api.test/',
+      listing: 'private',
+      skill: 'translate',
+      limit: 50,
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    const [url] = fetchImpl.mock.calls[0];
+    const parsed = new URL(String(url));
+    expect(parsed.pathname).toBe('/api/v1/registry/agents');
+    expect(parsed.searchParams.get('include')).toBe('full');
+    expect(parsed.searchParams.get('listing')).toBe('private');
+    expect(parsed.searchParams.get('scope')).toBe('owned');
+    expect(parsed.searchParams.get('skill')).toBe('translate');
+    expect(parsed.searchParams.get('limit')).toBe('50');
+  });
+
+  it('does not set scope=owned for public listing', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      mockResponse({ agents: [], totalCount: 0 }),
+    );
+
+    await listAgentsAuthenticated({
+      baseUrl: 'http://api.test',
+      listing: 'public',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    const [url] = fetchImpl.mock.calls[0];
+    const parsed = new URL(String(url));
+    expect(parsed.searchParams.get('listing')).toBe('public');
+    expect(parsed.searchParams.get('scope')).toBeNull();
+  });
+
+  it('throws on non-OK responses (e.g. 426 Upgrade Required)', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      mockResponse({}, false, 426),
+    );
+
+    await expect(
+      listAgentsAuthenticated({
+        baseUrl: 'http://api.test',
+        fetchImpl: fetchImpl as unknown as typeof fetch,
+      }),
+    ).rejects.toThrow('HTTP 426');
+  });
+
+  it('returns parsed JSON body on success', async () => {
+    const body = {
+      agents: [{ agentName: 'alice', skills: [] }],
+      totalCount: 1,
+    };
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(mockResponse(body));
+
+    const result = await listAgentsAuthenticated({
+      baseUrl: 'http://api.test',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+    expect(result).toEqual(body);
+  });
+});