@blocks-network/mcp-server 0.1.64 → 0.1.65

package/README.md

@@ -118,6 +118,7 @@ Add to your `~/.gemini/settings.json`:
 | `resume_task` | Resume a paused pipe task |
 | `retry_task` | Retry a failed task |
 | `list_agents` | List available agents in the registry |
+| `search_agent` | Search the registry for agents by free-text query (name, description, tags, provider, category) |
 | `get_agent_card` | Get the full agent card for a specific agent |
 | `get_agent_status` | Check live availability for agents (online instance count and total task count). Per-instance live activity counters (`activeTasks`, `concurrentTasksPerInstance`, `startedAt`, `totalActiveTasks`) are reserved in the response shape but currently return `0` — the backend does not yet populate them. |
 | `connect_task` | Connect to an existing task and stream events |

package/dist/index.js

@@ -5,10 +5,10 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { TaskClient, textPart, filePartFromPath, fetchCdmConfig, getAgent, BLOCKS_MAX_UPLOAD_BYTES, } from '@blocks-network/sdk';
-import { listAgentsAuthenticated } from './registry-list.js';
+import { listAllAgentsAuthenticated } from './registry-list.js';
 import { fetchAgentStatus, MAX_AGENT_NAMES } from './agent-status.js';
 import { getConsumerBalance, createConsumerTopUp } from './billing.js';
-import { sendTask, getTask, listTasks, cancelTask, pauseTask, resumeTask, retryTask, listAgents, getAgentCard, getAgentStatus, connectTask, downloadArtifact, checkBalance, requestTopup, defaultFileSize, } from './tools.js';
+import { sendTask, getTask, listTasks, cancelTask, pauseTask, resumeTask, retryTask, listAgents, searchAgents, getAgentCard, getAgentStatus, connectTask, downloadArtifact, checkBalance, requestTopup, defaultFileSize, } from './tools.js';
 const ALLOWED_ROOT = process.env.BLOCKS_MCP_FILE_ROOT ?? process.cwd();
 if (!process.env.BLOCKS_API_KEY) {
     console.error('Warning: BLOCKS_API_KEY is not set. Private agents and paid tasks will not work.');
@@ -70,7 +70,7 @@ const deps = {
     getOrgId: () => process.env.BLOCKS_ORG_ID,
     getTaskClient,
     getAgentByName: (agentName, options) => getAgent(agentName, options),
-    listAgents: listAgentsAuthenticated,
+    listAgents: listAllAgentsAuthenticated,
     fetchAgentStatus,
     getConsumerBalance,
     createConsumerTopUp,
@@ -111,14 +111,37 @@ server.tool('cancel_task', 'Cancel a running task', { taskId: z.string().describ
 server.tool('pause_task', 'Pause a running pipe task. Resume later with resume_task.', { taskId: z.string().describe('The task ID to pause') }, (params) => pauseTask(params, deps));
 server.tool('resume_task', 'Resume a paused pipe task', { taskId: z.string().describe('The task ID to resume') }, (params) => resumeTask(params, deps));
 server.tool('retry_task', 'Retry a failed task', { taskId: z.string().describe('The task ID to retry') }, (params) => retryTask(params, deps));
-server.tool('list_agents', 'List available agents in the Blocks Network registry. Use listing="private" with an API key to discover your private agents.', {
+server.tool('list_agents', 'List available agents in the Blocks Network registry. By default only agents with at least one online instance are returned; set includeOffline=true to also list registered agents that are currently offline. Use listing="private" with an API key to discover your private agents.', {
     tag: z.string().optional().describe('Filter by tag slug'),
     listing: z
         .enum(['public', 'private'])
         .optional()
         .describe('Filter by listing visibility (default: public)'),
-    limit: z.number().optional().describe('Max results to return'),
+    limit: z
+        .number()
+        .optional()
+        .describe('Max agents to fetch across all pages; omit to fetch all'),
+    includeOffline: z
+        .boolean()
+        .optional()
+        .describe('Include agents with no online instances (default: false)'),
 }, (params) => listAgents(params, deps));
+server.tool('search_agent', 'Search the Blocks Network registry for agents matching a free-text query. The query matches against agent name, display name, description, tags, provider, and category, and supports field qualifiers (e.g. "agentname:translate", tag:"data"), quoted phrases, and negation ("-deprecated"). By default only agents with at least one online instance are returned; set includeOffline=true to also include matching agents that are currently offline. Use listing="private" with an API key to search your private agents.', {
+    query: z.string().describe('Free-text search query'),
+    tag: z.string().optional().describe('Additionally filter by tag slug'),
+    listing: z
+        .enum(['public', 'private'])
+        .optional()
+        .describe('Filter by listing visibility (default: public)'),
+    limit: z
+        .number()
+        .optional()
+        .describe('Max matching agents to fetch across all pages; omit to fetch all'),
+    includeOffline: z
+        .boolean()
+        .optional()
+        .describe('Include agents with no online instances (default: false)'),
+}, (params) => searchAgents(params, deps));
 server.tool('get_agent_card', 'Get the full agent card for a specific agent', { agentName: z.string().describe('Agent name to look up') }, (params) => getAgentCard(params, deps));
 server.tool('get_agent_status', 'Check live availability for one or more agents: how many instances are online, total task count for the agent, and SDK/CLI versions per instance. (Per-instance live activity counters such as `activeTasks`, `concurrentTasksPerInstance`, `startedAt`, and `totalActiveTasks` are reserved in the response shape but not yet populated by the backend — they currently return 0.)', {
     agentNames: z

package/dist/registry-list.d.ts

@@ -19,13 +19,35 @@ export interface AgentListEntry {
 export interface ListAgentsOptions {
     baseUrl: string;
     apiKey?: string;
+    /** Free-text search query (`q`); matches agent name, description, tags, etc. */
+    q?: string;
     tag?: string;
     listing?: 'public' | 'private';
+    /** Page size for a single request. The backend caps this at 100. */
     limit?: number;
+    /** Opaque pagination cursor returned as `next` by a previous request. */
+    cursor?: string;
     fetchImpl?: typeof fetch;
 }
 export interface ListAgentsResult {
     agents: AgentListEntry[];
     totalCount?: number;
+    /** Opaque cursor for the next page, or null/absent when there are no more. */
+    next?: string | null;
+    /** Total agents with at least one online instance (ignores cursor). */
+    totalOnlineCount?: number;
 }
+/** Backend maximum page size for GET /api/v1/registry/agents. */
+export declare const REGISTRY_PAGE_SIZE = 100;
 export declare function listAgentsAuthenticated(opts: ListAgentsOptions): Promise<ListAgentsResult>;
+/**
+ * Fetch every agent by following the `next` cursor until it's null/absent.
+ *
+ * Uses the backend's maximum page size (100) to minimise round-trips. The
+ * optional `maxAgents` cap bounds the total number of agents collected and
+ * shrinks the final page request so we never over-fetch. The latest
+ * `totalCount`/`totalOnlineCount` seen are carried forward to the result.
+ */
+export declare function listAllAgentsAuthenticated(opts: ListAgentsOptions & {
+    maxAgents?: number;
+}): Promise<ListAgentsResult>;

package/dist/registry-list.js

@@ -6,8 +6,14 @@
  * optional Bearer API key for private/owned listings.
  */
 import { PROTOCOL_VERSION_HEADER, CURRENT_PROTOCOL_VERSION, } from './protocol-headers.js';
+/** Backend maximum page size for GET /api/v1/registry/agents. */
+export const REGISTRY_PAGE_SIZE = 100;
+/** Safety backstop so a misbehaving (never-null) cursor can't loop forever. */
+const MAX_PAGES = 1000;
 export async function listAgentsAuthenticated(opts) {
     const params = new URLSearchParams({ include: 'full' });
+    if (opts.q)
+        params.set('q', opts.q);
     if (opts.tag)
         params.set('tag', opts.tag);
     if (opts.listing) {
@@ -17,6 +23,8 @@ export async function listAgentsAuthenticated(opts) {
     }
     if (opts.limit)
         params.set('limit', String(opts.limit));
+    if (opts.cursor)
+        params.set('cursor', opts.cursor);
     const url = `${opts.baseUrl.replace(/\/+$/, '')}/api/v1/registry/agents?${params}`;
     const headers = {
         [PROTOCOL_VERSION_HEADER]: CURRENT_PROTOCOL_VERSION,
@@ -30,3 +38,42 @@ export async function listAgentsAuthenticated(opts) {
     }
     return (await response.json());
 }
+/**
+ * Fetch every agent by following the `next` cursor until it's null/absent.
+ *
+ * Uses the backend's maximum page size (100) to minimise round-trips. The
+ * optional `maxAgents` cap bounds the total number of agents collected and
+ * shrinks the final page request so we never over-fetch. The latest
+ * `totalCount`/`totalOnlineCount` seen are carried forward to the result.
+ */
+export async function listAllAgentsAuthenticated(opts) {
+    const agents = [];
+    let cursor = opts.cursor;
+    let totalCount;
+    let totalOnlineCount;
+    const cap = opts.maxAgents;
+    for (let page = 0; page < MAX_PAGES; page++) {
+        const remaining = cap !== undefined ? cap - agents.length : undefined;
+        if (remaining !== undefined && remaining <= 0)
+            break;
+        const pageSize = remaining !== undefined
+            ? Math.min(REGISTRY_PAGE_SIZE, remaining)
+            : REGISTRY_PAGE_SIZE;
+        const result = await listAgentsAuthenticated({
+            ...opts,
+            limit: pageSize,
+            cursor,
+        });
+        agents.push(...result.agents);
+        if (result.totalCount !== undefined)
+            totalCount = result.totalCount;
+        if (result.totalOnlineCount !== undefined) {
+            totalOnlineCount = result.totalOnlineCount;
+        }
+        cursor = result.next ?? undefined;
+        if (!cursor)
+            break;
+    }
+    const trimmed = cap !== undefined ? agents.slice(0, cap) : agents;
+    return { agents: trimmed, totalCount, totalOnlineCount, next: null };
+}

package/dist/tools.d.ts

@@ -7,7 +7,7 @@
  */
 import { textPart, filePartFromPath, type TaskInfo, type SendMessageRequestPart } from '@blocks-network/sdk';
 import type { ListAgentsResult } from './registry-list.js';
-import type { AgentStatusResponse } from './agent-status.js';
+import { type AgentStatusResponse } from './agent-status.js';
 import type { ConsumerBalance, TopUpSession } from './billing.js';
 export interface ArtifactRef {
     fileName?: string;
@@ -105,9 +105,12 @@ export interface ToolDeps {
     listAgents(options: {
         baseUrl: string;
         apiKey?: 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;
@@ -158,6 +161,25 @@ export interface ListAgentsParams {
     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 {
     agentName: string;
@@ -185,6 +207,7 @@ export declare function getTask(params: GetTaskParams, deps: ToolDeps): Promise<
 export declare function listTasks(params: ListTasksParams, deps: ToolDeps): Promise<ToolResult>;
 export declare function cancelTask(params: CancelTaskParams, deps: ToolDeps): Promise<ToolResult>;
 export declare function listAgents(params: ListAgentsParams, deps: ToolDeps): Promise<ToolResult>;
+export declare function searchAgents(params: SearchAgentsParams, deps: ToolDeps): Promise<ToolResult>;
 export declare function getAgentCard(params: GetAgentCardParams, deps: ToolDeps): Promise<ToolResult>;
 export declare function connectTask(params: ConnectTaskParams, deps: ToolDeps): Promise<ToolResult>;
 export declare function downloadArtifact(params: DownloadArtifactParams, deps: ToolDeps): Promise<ToolResult>;

package/dist/tools.js

@@ -6,6 +6,7 @@
  * touching the network or the filesystem.
  */
 import { statSync } from 'node:fs';
+import { MAX_AGENT_NAMES, AGENT_NAME_PATTERN, } from './agent-status.js';
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -163,15 +164,87 @@ export async function listAgents(params, deps) {
         apiKey,
         tag: params.tag,
         listing: params.listing,
-        limit: params.limit,
+        maxAgents: params.limit,
     });
-    const lines = result.agents.map((a) => {
-        const tags = a.tags?.map((t) => t.name).join(', ') ?? '';
-        return `${a.agentName} | ${a.name ?? a.agentName} | ${a.listing ?? 'public'} | ${tags}`;
+    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, deps) {
+    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) {
+    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, ctx, deps) {
+    const queryable = agents.filter((a) => AGENT_NAME_PATTERN.test(a.agentName));
+    if (queryable.length === 0)
+        return [];
+    const online = new Set();
+    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
 // ============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocks-network/mcp-server",
-  "version": "0.1.64",
+  "version": "0.1.65",
   "description": "MCP server for Blocks Network consumer operations",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -14,7 +14,7 @@ import {
   BLOCKS_MAX_UPLOAD_BYTES,
 } from '@blocks-network/sdk';
 
-import { listAgentsAuthenticated } from './registry-list.js';
+import { listAllAgentsAuthenticated } from './registry-list.js';
 import { fetchAgentStatus, MAX_AGENT_NAMES } from './agent-status.js';
 import { getConsumerBalance, createConsumerTopUp } from './billing.js';
 import {
@@ -26,6 +26,7 @@ import {
   resumeTask,
   retryTask,
   listAgents,
+  searchAgents,
   getAgentCard,
   getAgentStatus,
   connectTask,
@@ -106,7 +107,7 @@ const deps: ToolDeps = {
   getTaskClient,
   getAgentByName: (agentName, options) =>
     getAgent(agentName, options) as Promise<AgentEntryLike | null>,
-  listAgents: listAgentsAuthenticated,
+  listAgents: listAllAgentsAuthenticated,
   fetchAgentStatus,
   getConsumerBalance,
   createConsumerTopUp,
@@ -193,18 +194,47 @@ server.tool(
 
 server.tool(
   'list_agents',
-  'List available agents in the Blocks Network registry. Use listing="private" with an API key to discover your private agents.',
+  'List available agents in the Blocks Network registry. By default only agents with at least one online instance are returned; set includeOffline=true to also list registered agents that are currently offline. Use listing="private" with an API key to discover your private agents.',
   {
     tag: z.string().optional().describe('Filter by tag slug'),
     listing: z
       .enum(['public', 'private'])
       .optional()
       .describe('Filter by listing visibility (default: public)'),
-    limit: z.number().optional().describe('Max results to return'),
+    limit: z
+      .number()
+      .optional()
+      .describe('Max agents to fetch across all pages; omit to fetch all'),
+    includeOffline: z
+      .boolean()
+      .optional()
+      .describe('Include agents with no online instances (default: false)'),
   },
   (params) => listAgents(params, deps),
 );
 
+server.tool(
+  'search_agent',
+  'Search the Blocks Network registry for agents matching a free-text query. The query matches against agent name, display name, description, tags, provider, and category, and supports field qualifiers (e.g. "agentname:translate", tag:"data"), quoted phrases, and negation ("-deprecated"). By default only agents with at least one online instance are returned; set includeOffline=true to also include matching agents that are currently offline. Use listing="private" with an API key to search your private agents.',
+  {
+    query: z.string().describe('Free-text search query'),
+    tag: z.string().optional().describe('Additionally filter by tag slug'),
+    listing: z
+      .enum(['public', 'private'])
+      .optional()
+      .describe('Filter by listing visibility (default: public)'),
+    limit: z
+      .number()
+      .optional()
+      .describe('Max matching agents to fetch across all pages; omit to fetch all'),
+    includeOffline: z
+      .boolean()
+      .optional()
+      .describe('Include agents with no online instances (default: false)'),
+  },
+  (params) => searchAgents(params, deps),
+);
+
 server.tool(
   'get_agent_card',
   'Get the full agent card for a specific agent',

package/src/registry-list.ts

@@ -23,27 +23,44 @@ export interface AgentListEntry {
 export interface ListAgentsOptions {
   baseUrl: string;
   apiKey?: string;
+  /** Free-text search query (`q`); matches agent name, description, tags, etc. */
+  q?: string;
   tag?: string;
   listing?: 'public' | 'private';
+  /** Page size for a single request. The backend caps this at 100. */
   limit?: number;
+  /** Opaque pagination cursor returned as `next` by a previous request. */
+  cursor?: string;
   fetchImpl?: typeof fetch;
 }
 
 export interface ListAgentsResult {
   agents: AgentListEntry[];
   totalCount?: number;
+  /** Opaque cursor for the next page, or null/absent when there are no more. */
+  next?: string | null;
+  /** Total agents with at least one online instance (ignores cursor). */
+  totalOnlineCount?: number;
 }
 
+/** Backend maximum page size for GET /api/v1/registry/agents. */
+export const REGISTRY_PAGE_SIZE = 100;
+
+/** Safety backstop so a misbehaving (never-null) cursor can't loop forever. */
+const MAX_PAGES = 1000;
+
 export async function listAgentsAuthenticated(
   opts: ListAgentsOptions,
 ): Promise<ListAgentsResult> {
   const params = new URLSearchParams({ include: 'full' });
+  if (opts.q) params.set('q', opts.q);
   if (opts.tag) params.set('tag', opts.tag);
   if (opts.listing) {
     params.set('listing', opts.listing);
     if (opts.listing === 'private') params.set('scope', 'owned');
   }
   if (opts.limit) params.set('limit', String(opts.limit));
+  if (opts.cursor) params.set('cursor', opts.cursor);
 
   const url = `${opts.baseUrl.replace(/\/+$/, '')}/api/v1/registry/agents?${params}`;
   const headers: Record<string, string> = {
@@ -58,3 +75,47 @@ export async function listAgentsAuthenticated(
   }
   return (await response.json()) as ListAgentsResult;
 }
+
+/**
+ * Fetch every agent by following the `next` cursor until it's null/absent.
+ *
+ * Uses the backend's maximum page size (100) to minimise round-trips. The
+ * optional `maxAgents` cap bounds the total number of agents collected and
+ * shrinks the final page request so we never over-fetch. The latest
+ * `totalCount`/`totalOnlineCount` seen are carried forward to the result.
+ */
+export async function listAllAgentsAuthenticated(
+  opts: ListAgentsOptions & { maxAgents?: number },
+): Promise<ListAgentsResult> {
+  const agents: AgentListEntry[] = [];
+  let cursor = opts.cursor;
+  let totalCount: number | undefined;
+  let totalOnlineCount: number | undefined;
+  const cap = opts.maxAgents;
+
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const remaining = cap !== undefined ? cap - agents.length : undefined;
+    if (remaining !== undefined && remaining <= 0) break;
+    const pageSize =
+      remaining !== undefined
+        ? Math.min(REGISTRY_PAGE_SIZE, remaining)
+        : REGISTRY_PAGE_SIZE;
+
+    const result = await listAgentsAuthenticated({
+      ...opts,
+      limit: pageSize,
+      cursor,
+    });
+    agents.push(...result.agents);
+    if (result.totalCount !== undefined) totalCount = result.totalCount;
+    if (result.totalOnlineCount !== undefined) {
+      totalOnlineCount = result.totalOnlineCount;
+    }
+
+    cursor = result.next ?? undefined;
+    if (!cursor) break;
+  }
+
+  const trimmed = cap !== undefined ? agents.slice(0, cap) : agents;
+  return { agents: trimmed, totalCount, totalOnlineCount, next: null };
+}

package/src/tools.ts

@@ -15,7 +15,11 @@ import {
 } from '@blocks-network/sdk';
 
 import type { ListAgentsResult } from './registry-list.js';
-import type { AgentStatusResponse } from './agent-status.js';
+import {
+  MAX_AGENT_NAMES,
+  AGENT_NAME_PATTERN,
+  type AgentStatusResponse,
+} from './agent-status.js';
 import type { ConsumerBalance, TopUpSession } from './billing.js';
 
 // ============================================================================
@@ -120,9 +124,12 @@ export interface ToolDeps {
   listAgents(options: {
     baseUrl: string;
     apiKey?: 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;
@@ -223,6 +230,26 @@ export interface ListAgentsParams {
   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 {
@@ -413,17 +440,106 @@ export async function listAgents(
     apiKey,
     tag: params.tag,
     listing: params.listing,
-    limit: params.limit,
+    maxAgents: params.limit,
   });
 
-  const lines = result.agents.map((a) => {
-    const tags = a.tags?.map((t) => t.name).join(', ') ?? '';
-    return `${a.agentName} | ${a.name ?? a.agentName} | ${a.listing ?? 'public'} | ${tags}`;
+  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
 // ============================================================================

package/tests/list-agents.test.ts

@@ -2,6 +2,16 @@ import { describe, it, expect } from 'vitest';
 import { listAgents } from '../src/tools.js';
 import { makeFakeDeps } from './helpers.js';
 
+// A status response where every named agent has one online instance, so the
+// default online-only filter is a no-op for these agents.
+function allOnline(...names: string[]) {
+  const agents: Record<string, unknown> = {};
+  for (const name of names) {
+    agents[name] = { agentName: name, instances: [], onlineCount: 1, taskCount: 0 };
+  }
+  return { agents };
+}
+
 describe('list_agents', () => {
   it('renders one row per agent with tag names joined by commas', async () => {
     const { deps } = makeFakeDeps({
@@ -20,18 +30,19 @@ describe('list_agents', () => {
         ],
         totalCount: 2,
       },
+      agentStatusResult: allOnline('alice', 'bob'),
     });
 
     const res = await listAgents({}, deps);
     const lines = res.content[0].text.split('\n');
     expect(lines).toEqual([
-      'Agents (2):',
+      'Agents (2 online of 2 total):',
       'alice | Alice | public | Translate, Summarize',
       'bob | bob | private | ',
     ]);
   });
 
-  it('forwards baseUrl, apiKey, tag, listing, limit to the registry helper', async () => {
+  it('forwards baseUrl, apiKey, tag, listing, limit (as maxAgents) to the registry helper', async () => {
     const { deps, mocks } = makeFakeDeps({
       apiKey: 'sk-test',
       baseUrl: 'http://api.test',
@@ -47,7 +58,7 @@ describe('list_agents', () => {
       apiKey: 'sk-test',
       tag: 'translate',
       listing: 'private',
-      limit: 25,
+      maxAgents: 25,
     });
   });
 
@@ -57,18 +68,104 @@ describe('list_agents', () => {
         agents: [{ agentName: 'naked', tags: [] }],
         totalCount: 1,
       },
+      agentStatusResult: allOnline('naked'),
     });
 
     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 () => {
+  it('uses the online agent count for the header, falling back to length for total', async () => {
     const { deps } = makeFakeDeps({
       listAgentsResult: { agents: [{ agentName: 'a' }, { agentName: 'b' }] },
+      agentStatusResult: allOnline('a', 'b'),
+    });
+
+    const res = await listAgents({}, deps);
+    expect(res.content[0].text.split('\n')[0]).toBe('Agents (2 online of 2 total):');
+  });
+
+  it('reports the registry total separately from the online count', async () => {
+    const { deps } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [{ agentName: 'online' }, { agentName: 'offline' }],
+        totalCount: 50,
+      },
+      agentStatusResult: {
+        agents: {
+          online: { agentName: 'online', instances: [], onlineCount: 1, taskCount: 0 },
+          offline: { agentName: 'offline', instances: [], onlineCount: 0, taskCount: 0 },
+        },
+      },
+    });
+
+    const res = await listAgents({}, deps);
+    expect(res.content[0].text.split('\n')[0]).toBe('Agents (1 online of 50 total):');
+  });
+
+  it('drops offline agents by default, keeping only those with online instances', async () => {
+    const { deps, mocks } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [
+          { agentName: 'online', name: 'Online' },
+          { agentName: 'offline', name: 'Offline' },
+        ],
+        totalCount: 2,
+      },
+      agentStatusResult: {
+        agents: {
+          online: { agentName: 'online', instances: [], onlineCount: 1, taskCount: 0 },
+          offline: { agentName: 'offline', instances: [], onlineCount: 0, taskCount: 0 },
+        },
+      },
     });
 
     const res = await listAgents({}, deps);
-    expect(res.content[0].text.split('\n')[0]).toBe('Agents (2):');
+    const lines = res.content[0].text.split('\n');
+    expect(lines).toEqual([
+      'Agents (1 online of 2 total):',
+      'online | Online | public | ',
+    ]);
+    expect(mocks.fetchAgentStatus).toHaveBeenCalledWith({
+      baseUrl: 'http://api.test',
+      apiKey: undefined,
+      agentNames: ['online', 'offline'],
+    });
+  });
+
+  it('includes offline agents and skips the status check when includeOffline is true', async () => {
+    const { deps, mocks } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [
+          { agentName: 'online' },
+          { agentName: 'offline' },
+        ],
+        totalCount: 2,
+      },
+    });
+
+    const res = await listAgents({ includeOffline: true }, deps);
+    expect(res.content[0].text.split('\n')[0]).toBe('Agents (2 of 2 total):');
+    expect(mocks.fetchAgentStatus).not.toHaveBeenCalled();
+  });
+
+  it('drops agents whose names the status endpoint cannot query', async () => {
+    const { deps } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [
+          { agentName: 'valid_name' },
+          { agentName: 'has-dash' },
+        ],
+        totalCount: 2,
+      },
+      agentStatusResult: allOnline('valid_name'),
+    });
+
+    const res = await listAgents({}, deps);
+    const lines = res.content[0].text.split('\n');
+    expect(lines).toEqual([
+      'Agents (1 online of 2 total):',
+      'valid_name | valid_name | public | ',
+    ]);
   });
 });

package/tests/registry-list.test.ts

@@ -1,5 +1,8 @@
 import { describe, it, expect, vi } from 'vitest';
-import { listAgentsAuthenticated } from '../src/registry-list.js';
+import {
+  listAgentsAuthenticated,
+  listAllAgentsAuthenticated,
+} from '../src/registry-list.js';
 import {
   PROTOCOL_VERSION_HEADER,
   CURRENT_PROTOCOL_VERSION,
@@ -117,4 +120,125 @@ describe('listAgentsAuthenticated', () => {
     });
     expect(result).toEqual(body);
   });
+
+  it('forwards the cursor query param when provided', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      mockResponse({ agents: [], totalCount: 0 }),
+    );
+
+    await listAgentsAuthenticated({
+      baseUrl: 'http://api.test',
+      cursor: 'abc123',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    const [url] = fetchImpl.mock.calls[0];
+    expect(new URL(String(url)).searchParams.get('cursor')).toBe('abc123');
+  });
+});
+
+describe('listAllAgentsAuthenticated', () => {
+  function agent(name: string) {
+    return { agentName: name, tags: [] };
+  }
+
+  it('follows the next cursor across pages and aggregates results', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        mockResponse({
+          agents: [agent('a'), agent('b')],
+          next: 'c1',
+          totalCount: 5,
+          totalOnlineCount: 3,
+        }),
+      )
+      .mockResolvedValueOnce(
+        mockResponse({ agents: [agent('c'), agent('d')], next: 'c2' }),
+      )
+      .mockResolvedValueOnce(
+        mockResponse({ agents: [agent('e')], next: null }),
+      );
+
+    const result = await listAllAgentsAuthenticated({
+      baseUrl: 'http://api.test',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    expect(result.agents.map((a) => a.agentName)).toEqual(['a', 'b', 'c', 'd', 'e']);
+    expect(result.totalCount).toBe(5);
+    expect(result.totalOnlineCount).toBe(3);
+    expect(fetchImpl).toHaveBeenCalledTimes(3);
+
+    // First request carries no cursor; follow-ups carry the prior page's next.
+    expect(new URL(String(fetchImpl.mock.calls[0][0])).searchParams.get('cursor')).toBeNull();
+    expect(new URL(String(fetchImpl.mock.calls[1][0])).searchParams.get('cursor')).toBe('c1');
+    expect(new URL(String(fetchImpl.mock.calls[2][0])).searchParams.get('cursor')).toBe('c2');
+  });
+
+  it('stops after a single page when next is absent', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      mockResponse({ agents: [agent('a')], totalCount: 1 }),
+    );
+
+    const result = await listAllAgentsAuthenticated({
+      baseUrl: 'http://api.test',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    expect(fetchImpl).toHaveBeenCalledOnce();
+    expect(result.agents.map((a) => a.agentName)).toEqual(['a']);
+  });
+
+  it('requests the max page size (limit=100) by default', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      mockResponse({ agents: [], next: null }),
+    );
+
+    await listAllAgentsAuthenticated({
+      baseUrl: 'http://api.test',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    expect(new URL(String(fetchImpl.mock.calls[0][0])).searchParams.get('limit')).toBe('100');
+  });
+
+  it('caps the total agents and shrinks the final page request', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        mockResponse({ agents: [agent('a'), agent('b')], next: 'c1' }),
+      )
+      .mockResolvedValueOnce(
+        mockResponse({ agents: [agent('c'), agent('d')], next: 'c2' }),
+      );
+
+    const result = await listAllAgentsAuthenticated({
+      baseUrl: 'http://api.test',
+      maxAgents: 3,
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    expect(result.agents.map((a) => a.agentName)).toEqual(['a', 'b', 'c']);
+    // Two requests only. The cap bounds each page size: first page asks for
+    // min(100, 3)=3; after 2 returned, the second asks for the remaining 1.
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+    expect(new URL(String(fetchImpl.mock.calls[0][0])).searchParams.get('limit')).toBe('3');
+    expect(new URL(String(fetchImpl.mock.calls[1][0])).searchParams.get('limit')).toBe('1');
+  });
+
+  it('terminates when a backend returns a stuck non-null cursor', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      mockResponse({ agents: [agent('a')], next: 'always' }),
+    );
+
+    const result = await listAllAgentsAuthenticated({
+      baseUrl: 'http://api.test',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    // Bounded by the internal page guard rather than looping forever.
+    expect(fetchImpl).toHaveBeenCalledTimes(1000);
+    expect(result.agents).toHaveLength(1000);
+  });
 });

package/tests/search-agent.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from 'vitest';
+import { searchAgents } from '../src/tools.js';
+import { makeFakeDeps } from './helpers.js';
+
+// A status response where every named agent has one online instance, so the
+// default online-only filter is a no-op for these agents.
+function allOnline(...names: string[]) {
+  const agents: Record<string, unknown> = {};
+  for (const name of names) {
+    agents[name] = { agentName: name, instances: [], onlineCount: 1, taskCount: 0 };
+  }
+  return { agents };
+}
+
+describe('search_agent', () => {
+  it('forwards the query to the registry helper as `q`', async () => {
+    const { deps, mocks } = makeFakeDeps({
+      apiKey: 'sk-test',
+      baseUrl: 'http://api.test',
+    });
+
+    await searchAgents(
+      { query: 'translate', tag: 'language', listing: 'private', limit: 25 },
+      deps,
+    );
+
+    expect(mocks.listAgents).toHaveBeenCalledWith({
+      baseUrl: 'http://api.test',
+      apiKey: 'sk-test',
+      q: 'translate',
+      tag: 'language',
+      listing: 'private',
+      maxAgents: 25,
+    });
+  });
+
+  it('renders matching agents with the query in the header', async () => {
+    const { deps } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [
+          {
+            agentName: 'alice',
+            name: 'Alice',
+            listing: 'public',
+            tags: [{ id: 'translate', name: 'Translate' }],
+          },
+        ],
+        totalCount: 1,
+      },
+      agentStatusResult: allOnline('alice'),
+    });
+
+    const res = await searchAgents({ query: 'trans' }, deps);
+    const lines = res.content[0].text.split('\n');
+    expect(lines).toEqual([
+      'Agents matching "trans" (1 online of 1 total):',
+      'alice | Alice | public | Translate',
+    ]);
+  });
+
+  it('trims whitespace from the query before sending it', async () => {
+    const { deps, mocks } = makeFakeDeps();
+
+    await searchAgents({ query: '  hello  ' }, deps);
+
+    expect(mocks.listAgents).toHaveBeenCalledWith(
+      expect.objectContaining({ q: 'hello' }),
+    );
+  });
+
+  it('rejects an empty (or whitespace-only) query without calling the registry', async () => {
+    const { deps, mocks } = makeFakeDeps();
+
+    const res = await searchAgents({ query: '   ' }, deps);
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain('must not be empty');
+    expect(mocks.listAgents).not.toHaveBeenCalled();
+  });
+
+  it('drops offline matches by default, keeping only online ones', async () => {
+    const { deps } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [
+          { agentName: 'online', name: 'Online' },
+          { agentName: 'offline', name: 'Offline' },
+        ],
+        totalCount: 2,
+      },
+      agentStatusResult: {
+        agents: {
+          online: { agentName: 'online', instances: [], onlineCount: 1, taskCount: 0 },
+          offline: { agentName: 'offline', instances: [], onlineCount: 0, taskCount: 0 },
+        },
+      },
+    });
+
+    const res = await searchAgents({ query: 'foo' }, deps);
+    const lines = res.content[0].text.split('\n');
+    expect(lines).toEqual([
+      'Agents matching "foo" (1 online of 2 total):',
+      'online | Online | public | ',
+    ]);
+  });
+
+  it('includes offline matches and skips the status check when includeOffline is true', async () => {
+    const { deps, mocks } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [{ agentName: 'online' }, { agentName: 'offline' }],
+        totalCount: 2,
+      },
+    });
+
+    const res = await searchAgents({ query: 'foo', includeOffline: true }, deps);
+    expect(res.content[0].text.split('\n')[0]).toBe(
+      'Agents matching "foo" (2 of 2 total):',
+    );
+    expect(mocks.fetchAgentStatus).not.toHaveBeenCalled();
+  });
+});