@blocks-network/mcp-server 0.1.62 → 0.1.65

package/src/tools.ts

@@ -15,6 +15,12 @@ import {
 } from '@blocks-network/sdk';
 
 import type { ListAgentsResult } from './registry-list.js';
+import {
+  MAX_AGENT_NAMES,
+  AGENT_NAME_PATTERN,
+  type AgentStatusResponse,
+} from './agent-status.js';
+import type { ConsumerBalance, TopUpSession } from './billing.js';
 
 // ============================================================================
 // Types — minimal local shapes mirroring @blocks-network/sdk surfaces.
@@ -85,6 +91,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 +124,37 @@ export interface ToolDeps {
   listAgents(options: {
     baseUrl: string;
     apiKey?: string;
-    skill?: string;
+    /** Free-text search query (`q`); matches agent name, description, tags, etc. */
+    q?: string;
+    tag?: string;
     listing?: 'public' | 'private';
-    limit?: number;
+    /** Optional cap on the total number of agents to fetch across all pages. */
+    maxAgents?: 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,9 +227,29 @@ export interface CancelTaskParams {
 }
 
 export interface ListAgentsParams {
-  skill?: string;
+  tag?: string;
   listing?: 'public' | 'private';
   limit?: number;
+  /**
+   * Include agents that have no online instances. Defaults to false: the
+   * registry returns every registered agent regardless of whether any
+   * instance is currently running, so by default we filter to agents with
+   * at least one online instance to avoid surfacing unreachable agents.
+   */
+  includeOffline?: boolean;
+}
+
+export interface SearchAgentsParams {
+  /** Free-text search query; matches agent name, description, tags, etc. */
+  query: string;
+  tag?: string;
+  listing?: 'public' | 'private';
+  limit?: number;
+  /**
+   * Include agents that have no online instances. Defaults to false so we
+   * only surface agents that can actually take a task. See ListAgentsParams.
+   */
+  includeOffline?: boolean;
 }
 
 export interface GetAgentCardParams {
@@ -210,6 +261,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,19 +438,108 @@ export async function listAgents(
   const result = await deps.listAgents({
     baseUrl,
     apiKey,
-    skill: params.skill,
+    tag: params.tag,
     listing: params.listing,
-    limit: params.limit,
+    maxAgents: 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 total = result.totalCount ?? result.agents.length;
+
+  // The registry returns every registered agent regardless of whether any
+  // instance is currently running. Default to online-only so we never
+  // surface agents that can't actually take a task; `includeOffline` opts
+  // back into the full registry view.
+  if (params.includeOffline) {
+    const lines = result.agents.map(formatAgentRow);
+    const header = `Agents (${result.agents.length} of ${total} total):`;
+    return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
+  }
+
+  const online = await filterOnlineAgents(result.agents, { baseUrl, apiKey }, deps);
+  const lines = online.map(formatAgentRow);
+  const header = `Agents (${online.length} online of ${total} total):`;
+  return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
+}
+
+// ============================================================================
+// search_agent
+// ============================================================================
+
+export async function searchAgents(
+  params: SearchAgentsParams,
+  deps: ToolDeps,
+): Promise<ToolResult> {
+  const query = params.query.trim();
+  if (!query) {
+    return {
+      content: [{ type: 'text', text: 'Search query must not be empty.' }],
+      isError: true,
+    };
+  }
+
+  const baseUrl = await deps.getBaseUrl();
+  const apiKey = deps.getApiKey();
+  const result = await deps.listAgents({
+    baseUrl,
+    apiKey,
+    q: query,
+    tag: params.tag,
+    listing: params.listing,
+    maxAgents: params.limit,
   });
-  const header = `Agents (${result.totalCount ?? result.agents.length}):`;
+
+  const total = result.totalCount ?? result.agents.length;
+
+  // Mirror list_agents: default to online-only so we never surface agents
+  // that can't actually take a task; `includeOffline` opts back into the
+  // full set of matches.
+  if (params.includeOffline) {
+    const lines = result.agents.map(formatAgentRow);
+    const header = `Agents matching "${query}" (${result.agents.length} of ${total} total):`;
+    return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
+  }
+
+  const online = await filterOnlineAgents(result.agents, { baseUrl, apiKey }, deps);
+  const lines = online.map(formatAgentRow);
+  const header = `Agents matching "${query}" (${online.length} online of ${total} total):`;
   return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
 }
 
+function formatAgentRow(a: ListAgentsResult['agents'][number]): string {
+  const tags = a.tags?.map((t) => t.name).join(', ') ?? '';
+  return `${a.agentName} | ${a.name ?? a.agentName} | ${a.listing ?? 'public'} | ${tags}`;
+}
+
+/**
+ * Keep only agents that have at least one online instance, as reported by
+ * the agent-status service. Agent names that the status endpoint can't
+ * accept (too many, or invalid characters) are queried in valid batches;
+ * any name that's unqueryable is treated as offline and dropped.
+ */
+async function filterOnlineAgents(
+  agents: ListAgentsResult['agents'],
+  ctx: { baseUrl: string; apiKey?: string },
+  deps: ToolDeps,
+): Promise<ListAgentsResult['agents']> {
+  const queryable = agents.filter((a) => AGENT_NAME_PATTERN.test(a.agentName));
+  if (queryable.length === 0) return [];
+
+  const online = new Set<string>();
+  for (let i = 0; i < queryable.length; i += MAX_AGENT_NAMES) {
+    const batch = queryable.slice(i, i + MAX_AGENT_NAMES);
+    const status = await deps.fetchAgentStatus({
+      baseUrl: ctx.baseUrl,
+      apiKey: ctx.apiKey,
+      agentNames: batch.map((a) => a.agentName),
+    });
+    for (const [name, info] of Object.entries(status.agents)) {
+      if ((info.onlineCount ?? 0) > 0) online.add(name);
+    }
+  }
+
+  return agents.filter((a) => online.has(a.agentName));
+}
+
 // ============================================================================
 // get_agent_card
 // ============================================================================
@@ -487,6 +645,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/);
+  });
+});