@blocks-network/mcp-server 0.1.55 → 0.1.64

package/tests/billing.test.ts

@@ -0,0 +1,203 @@
+import { describe, it, expect, vi } from 'vitest';
+import { checkBalance, requestTopup } from '../src/tools.js';
+import { getConsumerBalance, createConsumerTopUp } from '../src/billing.js';
+import {
+  PROTOCOL_VERSION_HEADER,
+  CURRENT_PROTOCOL_VERSION,
+} from '../src/protocol-headers.js';
+import { makeFakeDeps } from './helpers.js';
+
+function mockResponse(body: unknown, ok = true, status = 200): Response {
+  return {
+    ok,
+    status,
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  } as Response;
+}
+
+describe('check_balance (handler)', () => {
+  it('returns an error when BLOCKS_API_KEY is missing', async () => {
+    const { deps } = makeFakeDeps();
+
+    const res = await checkBalance({}, deps);
+
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toMatch(/BLOCKS_API_KEY/);
+  });
+
+  it('returns an error when BLOCKS_ORG_ID is missing', async () => {
+    const { deps } = makeFakeDeps({ apiKey: 'bk_test' });
+
+    const res = await checkBalance({}, deps);
+
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toMatch(/BLOCKS_ORG_ID/);
+  });
+
+  it('forwards baseUrl, orgId, apiKey and emits balance JSON', async () => {
+    const balance = {
+      balance: '100.00',
+      reservedBalance: '5.00',
+      availableBalance: '95.00',
+      updatedAt: '2026-05-28T00:00:00Z',
+    };
+    const { deps, mocks } = makeFakeDeps({
+      apiKey: 'bk_test',
+      orgId: 'org_42',
+      balance,
+    });
+
+    const res = await checkBalance({}, deps);
+
+    expect(mocks.getConsumerBalance).toHaveBeenCalledWith({
+      baseUrl: 'http://api.test',
+      apiKey: 'bk_test',
+      orgId: 'org_42',
+    });
+    expect(JSON.parse(res.content[0].text)).toEqual(balance);
+  });
+});
+
+describe('request_topup (handler)', () => {
+  it('returns an error when BLOCKS_ORG_ID is missing', async () => {
+    const { deps } = makeFakeDeps({ apiKey: 'bk_test' });
+
+    const res = await requestTopup({ amountUsd: 25 }, deps);
+
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toMatch(/BLOCKS_ORG_ID/);
+  });
+
+  it('returns the Stripe checkout URL with a human-readable label', async () => {
+    const { deps, mocks } = makeFakeDeps({
+      apiKey: 'bk_test',
+      orgId: 'org_42',
+      topUpSession: {
+        checkoutUrl: 'https://checkout.stripe.test/session/xyz',
+        sessionId: 'cs_test_abc',
+      },
+    });
+
+    const res = await requestTopup({ amountUsd: 25 }, deps);
+
+    expect(mocks.createConsumerTopUp).toHaveBeenCalledWith({
+      baseUrl: 'http://api.test',
+      apiKey: 'bk_test',
+      orgId: 'org_42',
+      amountUsd: 25,
+    });
+    expect(res.content[0].text).toContain('https://checkout.stripe.test/session/xyz');
+    expect(res.content[0].text).toContain('$25.00');
+  });
+});
+
+describe('getConsumerBalance (HTTP helper)', () => {
+  it('GETs /api/v1/billing/:orgId/consumer/balance with Bearer auth', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(
+        mockResponse({
+          balance: '0',
+          reservedBalance: '0',
+          availableBalance: '0',
+          updatedAt: '2026-05-28T00:00:00Z',
+        }),
+      );
+
+    await getConsumerBalance({
+      baseUrl: 'http://api.test',
+      orgId: 'org_42',
+      apiKey: 'bk_test',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    const [url, init] = fetchImpl.mock.calls[0];
+    const parsed = new URL(String(url));
+    expect(parsed.pathname).toBe('/api/v1/billing/org_42/consumer/balance');
+    expect(init?.method).toBe('GET');
+    const headers = init?.headers as Record<string, string>;
+    expect(headers.Authorization).toBe('Bearer bk_test');
+    expect(headers[PROTOCOL_VERSION_HEADER]).toBe(CURRENT_PROTOCOL_VERSION);
+  });
+
+  it('throws on non-OK responses', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(mockResponse({}, false, 403));
+
+    await expect(
+      getConsumerBalance({
+        baseUrl: 'http://api.test',
+        orgId: 'org_42',
+        apiKey: 'bk_test',
+        fetchImpl: fetchImpl as unknown as typeof fetch,
+      }),
+    ).rejects.toThrow('HTTP 403');
+  });
+});
+
+describe('createConsumerTopUp (HTTP helper)', () => {
+  it('POSTs JSON body with whole-cent amount string', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(
+        mockResponse({
+          checkoutUrl: 'https://checkout.stripe.test/x',
+          sessionId: 'cs_test_x',
+        }),
+      );
+
+    await createConsumerTopUp({
+      baseUrl: 'http://api.test',
+      orgId: 'org_42',
+      apiKey: 'bk_test',
+      amountUsd: 19.99,
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    const [url, init] = fetchImpl.mock.calls[0];
+    const parsed = new URL(String(url));
+    expect(parsed.pathname).toBe('/api/v1/billing/org_42/consumer/topup');
+    expect(init?.method).toBe('POST');
+    expect(JSON.parse(String(init?.body))).toEqual({ amount: '19.99' });
+    const headers = init?.headers as Record<string, string>;
+    expect(headers['Content-Type']).toBe('application/json');
+  });
+
+  it('rejects non-positive amounts', async () => {
+    await expect(
+      createConsumerTopUp({
+        baseUrl: 'http://api.test',
+        orgId: 'org_42',
+        apiKey: 'bk_test',
+        amountUsd: 0,
+      }),
+    ).rejects.toThrow(/positive/);
+  });
+
+  it('rejects amounts below the $5 platform minimum', async () => {
+    await expect(
+      createConsumerTopUp({
+        baseUrl: 'http://api.test',
+        orgId: 'org_42',
+        apiKey: 'bk_test',
+        amountUsd: 1,
+      }),
+    ).rejects.toThrow(/at least \$5/);
+  });
+
+  it('throws on non-OK responses with body detail', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(mockResponse({ error: 'amount too small' }, false, 400));
+
+    await expect(
+      createConsumerTopUp({
+        baseUrl: 'http://api.test',
+        orgId: 'org_42',
+        apiKey: 'bk_test',
+        amountUsd: 25,
+        fetchImpl: fetchImpl as unknown as typeof fetch,
+      }),
+    ).rejects.toThrow(/HTTP 400/);
+  });
+});

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');
+  });
+});

package/tests/download-artifact.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from 'vitest';
+import { downloadArtifact } from '../src/tools.js';
+import { makeFakeDeps, makeFakeClient, makeFakeSession } from './helpers.js';
+
+describe('download_artifact', () => {
+  it('returns inline text content for a text artifact when savePath is omitted', async () => {
+    const session = makeFakeSession({
+      artifacts: [
+        {
+          fileName: 'output.json',
+          mimeType: 'application/json',
+          data: new TextEncoder().encode('{"ok":true}'),
+        },
+      ],
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't1', state: 'completed' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await downloadArtifact(
+      { taskId: 't1', fileName: 'output.json' },
+      deps,
+    );
+
+    expect(client.connectMock).toHaveBeenCalledWith({ taskId: 't1' });
+    expect(res.isError).toBeUndefined();
+    expect(res.content[0].text).toContain('[artifact: output.json]');
+    expect(res.content[0].text).toContain('{"ok":true}');
+    expect(session.closeMock).toHaveBeenCalledOnce();
+  });
+
+  it('returns base64 content for binary artifacts when savePath is omitted', async () => {
+    const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+    const session = makeFakeSession({
+      artifacts: [{ fileName: 'image.png', mimeType: 'image/png', data: bytes }],
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't2', state: 'completed' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await downloadArtifact(
+      { taskId: 't2', fileName: 'image.png' },
+      deps,
+    );
+
+    expect(res.isError).toBeUndefined();
+    expect(res.content[0].text).toContain('image/png');
+    expect(res.content[0].text).toContain('base64');
+    expect(res.content[0].text).toContain(Buffer.from(bytes).toString('base64'));
+  });
+
+  it('writes to disk when savePath is provided', async () => {
+    const bytes = new TextEncoder().encode('hello');
+    const session = makeFakeSession({
+      artifacts: [{ fileName: 'note.txt', mimeType: 'text/plain', data: bytes }],
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't3', state: 'completed' },
+      session,
+    });
+    const { deps, mocks } = makeFakeDeps({ client });
+
+    const res = await downloadArtifact(
+      { taskId: 't3', fileName: 'note.txt', savePath: 'out/note.txt' },
+      deps,
+    );
+
+    expect(res.isError).toBeUndefined();
+    expect(mocks.resolveSavePath).toHaveBeenCalledWith('out/note.txt');
+    expect(mocks.writeFile).toHaveBeenCalledWith('out/note.txt', bytes);
+    expect(res.content[0].text).toContain('Saved 5 bytes to out/note.txt');
+  });
+
+  it('returns an error when the requested artifact is not found', async () => {
+    const session = makeFakeSession({
+      artifacts: [
+        {
+          fileName: 'other.txt',
+          mimeType: 'text/plain',
+          data: new TextEncoder().encode('x'),
+        },
+      ],
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't4', state: 'completed' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await downloadArtifact(
+      { taskId: 't4', fileName: 'missing.txt' },
+      deps,
+    );
+
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain('"missing.txt" not found');
+    expect(res.content[0].text).toContain('other.txt');
+    expect(session.closeMock).toHaveBeenCalledOnce();
+  });
+
+  it('uses paid TaskClient for paid tasks', async () => {
+    const session = makeFakeSession({
+      artifacts: [
+        {
+          fileName: 'a.txt',
+          mimeType: 'text/plain',
+          data: new TextEncoder().encode('a'),
+        },
+      ],
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't5', state: 'completed', billingMode: 'paid' },
+      session,
+    });
+    const { deps, mocks } = makeFakeDeps({ client });
+
+    await downloadArtifact({ taskId: 't5', fileName: 'a.txt' }, deps);
+
+    expect(mocks.getTaskClient).toHaveBeenCalledWith('free');
+    expect(mocks.getTaskClient).toHaveBeenCalledWith('paid');
+  });
+
+  it('returns an error when connect fails', async () => {
+    const client = makeFakeClient({
+      task: { taskId: 't6', state: 'completed' },
+    });
+    client.connectMock.mockRejectedValueOnce(new Error('connect refused'));
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await downloadArtifact(
+      { taskId: 't6', fileName: 'x.txt' },
+      deps,
+    );
+
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain('connect refused');
+  });
+});

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',
+    });
+  });
+});