@blocks-network/mcp-server 0.1.62 → 0.1.64

package/src/tools.ts

@@ -15,6 +15,8 @@ import {
 } 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';
 
 // ============================================================================
 // Types — minimal local shapes mirroring @blocks-network/sdk surfaces.
@@ -85,6 +87,9 @@ export interface TaskClientLike {
     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>;
 }
 
@@ -115,15 +120,34 @@ export interface ToolDeps {
   listAgents(options: {
     baseUrl: string;
     apiKey?: string;
-    skill?: 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>;
 }
 
 // ============================================================================
@@ -196,7 +220,7 @@ export interface CancelTaskParams {
 }
 
 export interface ListAgentsParams {
-  skill?: string;
+  tag?: string;
   listing?: 'public' | 'private';
   limit?: number;
 }
@@ -210,6 +234,24 @@ export interface ConnectTaskParams {
   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;
+}
+
 // ============================================================================
 // send_task
 // ============================================================================
@@ -369,14 +411,14 @@ export async function listAgents(
   const result = await deps.listAgents({
     baseUrl,
     apiKey,
-    skill: params.skill,
+    tag: params.tag,
     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 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') }] };
@@ -487,6 +529,207 @@ export async function connectTask(
   }
 }
 
+// ============================================================================
+// download_artifact
+// ============================================================================
+
+function bytesToBase64(bytes: Uint8Array): string {
+  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: DownloadArtifactParams,
+  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);
+
+  let session: TaskSessionLike;
+  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: TaskIdParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  const client = await deps.getTaskClient();
+  await client.pauseTask(params.taskId);
+  return { content: [{ type: 'text', text: `Task ${params.taskId} paused.` }] };
+}
+
+export async function resumeTask(
+  params: TaskIdParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  const client = await deps.getTaskClient();
+  await client.resumeTask(params.taskId);
+  return { content: [{ type: 'text', text: `Task ${params.taskId} resumed.` }] };
+}
+
+export async function retryTask(
+  params: TaskIdParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  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: GetAgentStatusParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  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: ToolDeps): { apiKey: string; orgId: string } | ToolResult {
+  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: Record<string, never>,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  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: RequestTopUpParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  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)
 // ============================================================================

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