@blocks-network/mcp-server 0.1.66 → 0.1.70

package/dist/index.js

@@ -111,8 +111,12 @@ 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. 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.', {
+server.tool('list_agents', 'List available agents in the Blocks Network registry. To find every agent published by a particular provider/organization (e.g. "all agents from Hamilton"), use this tool with the `provider` parameter — it is the correct tool for provider-scoped browsing and needs no search query. 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'),
+    provider: z
+        .string()
+        .optional()
+        .describe('Filter to agents published by this provider (the publishing organization\'s name), matched case-insensitively as a substring (e.g. "hamilton" matches "Hamilton Labs"). This is the reliable way to scope results to a provider — prefer it over typing the provider name into a free-text query, which only fuzzy-matches names/descriptions.'),
     listing: z
         .enum(['public', 'private'])
         .optional()
@@ -126,8 +130,15 @@ server.tool('list_agents', 'List available agents in the Blocks Network registry
         .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'),
+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"). To restrict results to a specific provider/organization, set the `provider` parameter rather than putting the provider name in the query; `query` is optional, so you can search by `provider` and/or `tag` alone (e.g. provider="Hamilton" with no query returns every Hamilton agent). At least one of `query`, `provider`, or `tag` must be supplied. 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()
+        .optional()
+        .describe('Free-text search query. Optional, but at least one of `query`, `provider`, or `tag` must be given. Omit it to browse a provider or tag with no search terms (e.g. provider="Hamilton" alone returns every Hamilton agent).'),
+    provider: z
+        .string()
+        .optional()
+        .describe('Restrict matches to agents published by this provider (the publishing organization\'s name), matched case-insensitively as a substring (e.g. "hamilton" matches "Hamilton Labs"). Use this parameter to scope by provider instead of typing the provider name into `query`, which only fuzzy-matches names/descriptions and is unreliable.'),
     tag: z.string().optional().describe('Additionally filter by tag slug'),
     listing: z
         .enum(['public', 'private'])

package/dist/registry-list.d.ts

@@ -11,6 +11,8 @@ export interface AgentListEntry {
     description?: string;
     listing?: string;
     billingMode?: string;
+    /** Provider (publishing organization) name, as returned by the backend. */
+    orgName?: string;
     tags?: Array<{
         id: string;
         name: string;
@@ -21,6 +23,12 @@ export interface ListAgentsOptions {
     apiKey?: string;
     /** Free-text search query (`q`); matches agent name, description, tags, etc. */
     q?: string;
+    /**
+     * Filter to agents published by a provider whose organization name matches
+     * this value (case-insensitive substring). Composed into the `q` parameter
+     * as a `provider:"…"` qualifier, so it combines (AND) with any `q` text.
+     */
+    provider?: string;
     tag?: string;
     listing?: 'public' | 'private';
     /** Page size for a single request. The backend caps this at 100. */
@@ -39,6 +47,18 @@ export interface ListAgentsResult {
 }
 /** Backend maximum page size for GET /api/v1/registry/agents. */
 export declare const REGISTRY_PAGE_SIZE = 100;
+/**
+ * Combine the free-text query with a provider-name filter into a single `q`
+ * value the registry's search parser understands.
+ *
+ * The backend exposes provider-by-name only through the `provider:` search
+ * qualifier (matched as a case-insensitive substring of the organization
+ * name); the structured `provider` query param takes org UUIDs instead, which
+ * an MCP caller doesn't have. We always quote the value so names containing
+ * spaces survive the tokenizer, and strip embedded quotes so a stray `"`
+ * can't unbalance the qualifier.
+ */
+export declare function composeSearchQuery(q: string | undefined, provider: string | undefined): string | undefined;
 export declare function listAgentsAuthenticated(opts: ListAgentsOptions): Promise<ListAgentsResult>;
 /**
  * Fetch every agent by following the `next` cursor until it's null/absent.

package/dist/registry-list.js

@@ -8,12 +8,32 @@
 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;
+/**
+ * Combine the free-text query with a provider-name filter into a single `q`
+ * value the registry's search parser understands.
+ *
+ * The backend exposes provider-by-name only through the `provider:` search
+ * qualifier (matched as a case-insensitive substring of the organization
+ * name); the structured `provider` query param takes org UUIDs instead, which
+ * an MCP caller doesn't have. We always quote the value so names containing
+ * spaces survive the tokenizer, and strip embedded quotes so a stray `"`
+ * can't unbalance the qualifier.
+ */
+export function composeSearchQuery(q, provider) {
+    const trimmedProvider = provider?.trim();
+    if (!trimmedProvider)
+        return q;
+    const quoted = `provider:"${trimmedProvider.replace(/"/g, '')}"`;
+    const trimmedQ = q?.trim();
+    return trimmedQ ? `${trimmedQ} ${quoted}` : quoted;
+}
 /** 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);
+    const q = composeSearchQuery(opts.q, opts.provider);
+    if (q)
+        params.set('q', q);
     if (opts.tag)
         params.set('tag', opts.tag);
     if (opts.listing) {

package/dist/tools.d.ts

@@ -107,6 +107,8 @@ export interface ToolDeps {
         apiKey?: string;
         /** Free-text search query (`q`); matches agent name, description, tags, etc. */
         q?: string;
+        /** Filter to agents whose provider (organization) name matches (substring). */
+        provider?: string;
         tag?: string;
         listing?: 'public' | 'private';
         /** Optional cap on the total number of agents to fetch across all pages. */
@@ -159,6 +161,8 @@ export interface CancelTaskParams {
 }
 export interface ListAgentsParams {
     tag?: string;
+    /** Filter to agents whose provider (organization) name matches (substring, case-insensitive). */
+    provider?: string;
     listing?: 'public' | 'private';
     limit?: number;
     /**
@@ -170,8 +174,14 @@ export interface ListAgentsParams {
     includeOffline?: boolean;
 }
 export interface SearchAgentsParams {
-    /** Free-text search query; matches agent name, description, tags, etc. */
-    query: string;
+    /**
+     * Free-text search query; matches agent name, description, tags, etc.
+     * Optional, but at least one of `query`, `provider`, or `tag` must be
+     * supplied — a search with no constraints at all is rejected.
+     */
+    query?: string;
+    /** Filter to agents whose provider (organization) name matches (substring, case-insensitive). */
+    provider?: string;
     tag?: string;
     listing?: 'public' | 'private';
     limit?: number;

package/dist/tools.js

@@ -162,6 +162,7 @@ export async function listAgents(params, deps) {
     const result = await deps.listAgents({
         baseUrl,
         apiKey,
+        provider: params.provider,
         tag: params.tag,
         listing: params.listing,
         maxAgents: params.limit,
@@ -185,10 +186,21 @@ export async function listAgents(params, deps) {
 // search_agent
 // ============================================================================
 export async function searchAgents(params, deps) {
-    const query = params.query.trim();
-    if (!query) {
+    const query = params.query?.trim();
+    const provider = params.provider?.trim();
+    const tag = params.tag?.trim();
+    // A search needs at least one constraint. Provider- or tag-only searches are
+    // valid (e.g. "every agent from Hamilton"); only a completely empty request
+    // is rejected, since that's just an unfiltered list and should use
+    // list_agents instead.
+    if (!query && !provider && !tag) {
         return {
-            content: [{ type: 'text', text: 'Search query must not be empty.' }],
+            content: [
+                {
+                    type: 'text',
+                    text: 'Provide at least one of `query`, `provider`, or `tag` to search. To list every agent without a filter, use list_agents.',
+                },
+            ],
             isError: true,
         };
     }
@@ -198,27 +210,48 @@ export async function searchAgents(params, deps) {
         baseUrl,
         apiKey,
         q: query,
-        tag: params.tag,
+        provider,
+        tag,
         listing: params.listing,
         maxAgents: params.limit,
     });
     const total = result.totalCount ?? result.agents.length;
+    // Describe whatever constraints were actually applied so the header reflects
+    // a provider/tag-only search as accurately as a free-text one.
+    const criteria = describeSearchCriteria(query, provider, tag);
     // 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):`;
+        const header = `Agents ${criteria} (${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):`;
+    const header = `Agents ${criteria} (${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}`;
+    const provider = a.orgName ?? '';
+    return `${a.agentName} | ${a.name ?? a.agentName} | ${provider} | ${a.listing ?? 'public'} | ${tags}`;
+}
+/**
+ * Build the result-header phrase from whichever search constraints were
+ * applied, e.g. `matching "trans"`, `from provider "Hamilton"`, or
+ * `matching "trans" from provider "Hamilton" with tag "data"`. At least one
+ * constraint is always present (the handler rejects an empty search).
+ */
+function describeSearchCriteria(query, provider, tag) {
+    const parts = [];
+    if (query)
+        parts.push(`matching "${query}"`);
+    if (provider)
+        parts.push(`from provider "${provider}"`);
+    if (tag)
+        parts.push(`with tag "${tag}"`);
+    return parts.join(' ');
 }
 /**
  * Keep only agents that have at least one online instance, as reported by

package/package.json

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

package/src/index.ts

@@ -194,9 +194,15 @@ server.tool(
 
 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.',
+  'List available agents in the Blocks Network registry. To find every agent published by a particular provider/organization (e.g. "all agents from Hamilton"), use this tool with the `provider` parameter — it is the correct tool for provider-scoped browsing and needs no search query. 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'),
+    provider: z
+      .string()
+      .optional()
+      .describe(
+        'Filter to agents published by this provider (the publishing organization\'s name), matched case-insensitively as a substring (e.g. "hamilton" matches "Hamilton Labs"). This is the reliable way to scope results to a provider — prefer it over typing the provider name into a free-text query, which only fuzzy-matches names/descriptions.',
+      ),
     listing: z
       .enum(['public', 'private'])
       .optional()
@@ -215,9 +221,20 @@ server.tool(
 
 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.',
+  '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"). To restrict results to a specific provider/organization, set the `provider` parameter rather than putting the provider name in the query; `query` is optional, so you can search by `provider` and/or `tag` alone (e.g. provider="Hamilton" with no query returns every Hamilton agent). At least one of `query`, `provider`, or `tag` must be supplied. 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'),
+    query: z
+      .string()
+      .optional()
+      .describe(
+        'Free-text search query. Optional, but at least one of `query`, `provider`, or `tag` must be given. Omit it to browse a provider or tag with no search terms (e.g. provider="Hamilton" alone returns every Hamilton agent).',
+      ),
+    provider: z
+      .string()
+      .optional()
+      .describe(
+        'Restrict matches to agents published by this provider (the publishing organization\'s name), matched case-insensitively as a substring (e.g. "hamilton" matches "Hamilton Labs"). Use this parameter to scope by provider instead of typing the provider name into `query`, which only fuzzy-matches names/descriptions and is unreliable.',
+      ),
     tag: z.string().optional().describe('Additionally filter by tag slug'),
     listing: z
       .enum(['public', 'private'])

package/src/registry-list.ts

@@ -17,6 +17,8 @@ export interface AgentListEntry {
   description?: string;
   listing?: string;
   billingMode?: string;
+  /** Provider (publishing organization) name, as returned by the backend. */
+  orgName?: string;
   tags?: Array<{ id: string; name: string }>;
 }
 
@@ -25,6 +27,12 @@ export interface ListAgentsOptions {
   apiKey?: string;
   /** Free-text search query (`q`); matches agent name, description, tags, etc. */
   q?: string;
+  /**
+   * Filter to agents published by a provider whose organization name matches
+   * this value (case-insensitive substring). Composed into the `q` parameter
+   * as a `provider:"…"` qualifier, so it combines (AND) with any `q` text.
+   */
+  provider?: string;
   tag?: string;
   listing?: 'public' | 'private';
   /** Page size for a single request. The backend caps this at 100. */
@@ -46,6 +54,28 @@ export interface ListAgentsResult {
 /** Backend maximum page size for GET /api/v1/registry/agents. */
 export const REGISTRY_PAGE_SIZE = 100;
 
+/**
+ * Combine the free-text query with a provider-name filter into a single `q`
+ * value the registry's search parser understands.
+ *
+ * The backend exposes provider-by-name only through the `provider:` search
+ * qualifier (matched as a case-insensitive substring of the organization
+ * name); the structured `provider` query param takes org UUIDs instead, which
+ * an MCP caller doesn't have. We always quote the value so names containing
+ * spaces survive the tokenizer, and strip embedded quotes so a stray `"`
+ * can't unbalance the qualifier.
+ */
+export function composeSearchQuery(
+  q: string | undefined,
+  provider: string | undefined,
+): string | undefined {
+  const trimmedProvider = provider?.trim();
+  if (!trimmedProvider) return q;
+  const quoted = `provider:"${trimmedProvider.replace(/"/g, '')}"`;
+  const trimmedQ = q?.trim();
+  return trimmedQ ? `${trimmedQ} ${quoted}` : quoted;
+}
+
 /** Safety backstop so a misbehaving (never-null) cursor can't loop forever. */
 const MAX_PAGES = 1000;
 
@@ -53,7 +83,8 @@ export async function listAgentsAuthenticated(
   opts: ListAgentsOptions,
 ): Promise<ListAgentsResult> {
   const params = new URLSearchParams({ include: 'full' });
-  if (opts.q) params.set('q', opts.q);
+  const q = composeSearchQuery(opts.q, opts.provider);
+  if (q) params.set('q', q);
   if (opts.tag) params.set('tag', opts.tag);
   if (opts.listing) {
     params.set('listing', opts.listing);

package/src/tools.ts

@@ -126,6 +126,8 @@ export interface ToolDeps {
     apiKey?: string;
     /** Free-text search query (`q`); matches agent name, description, tags, etc. */
     q?: string;
+    /** Filter to agents whose provider (organization) name matches (substring). */
+    provider?: string;
     tag?: string;
     listing?: 'public' | 'private';
     /** Optional cap on the total number of agents to fetch across all pages. */
@@ -228,6 +230,8 @@ export interface CancelTaskParams {
 
 export interface ListAgentsParams {
   tag?: string;
+  /** Filter to agents whose provider (organization) name matches (substring, case-insensitive). */
+  provider?: string;
   listing?: 'public' | 'private';
   limit?: number;
   /**
@@ -240,8 +244,14 @@ export interface ListAgentsParams {
 }
 
 export interface SearchAgentsParams {
-  /** Free-text search query; matches agent name, description, tags, etc. */
-  query: string;
+  /**
+   * Free-text search query; matches agent name, description, tags, etc.
+   * Optional, but at least one of `query`, `provider`, or `tag` must be
+   * supplied — a search with no constraints at all is rejected.
+   */
+  query?: string;
+  /** Filter to agents whose provider (organization) name matches (substring, case-insensitive). */
+  provider?: string;
   tag?: string;
   listing?: 'public' | 'private';
   limit?: number;
@@ -438,6 +448,7 @@ export async function listAgents(
   const result = await deps.listAgents({
     baseUrl,
     apiKey,
+    provider: params.provider,
     tag: params.tag,
     listing: params.listing,
     maxAgents: params.limit,
@@ -469,10 +480,22 @@ export async function searchAgents(
   params: SearchAgentsParams,
   deps: ToolDeps,
 ): Promise<ToolResult> {
-  const query = params.query.trim();
-  if (!query) {
+  const query = params.query?.trim();
+  const provider = params.provider?.trim();
+  const tag = params.tag?.trim();
+
+  // A search needs at least one constraint. Provider- or tag-only searches are
+  // valid (e.g. "every agent from Hamilton"); only a completely empty request
+  // is rejected, since that's just an unfiltered list and should use
+  // list_agents instead.
+  if (!query && !provider && !tag) {
     return {
-      content: [{ type: 'text', text: 'Search query must not be empty.' }],
+      content: [
+        {
+          type: 'text',
+          text: 'Provide at least one of `query`, `provider`, or `tag` to search. To list every agent without a filter, use list_agents.',
+        },
+      ],
       isError: true,
     };
   }
@@ -483,31 +506,55 @@ export async function searchAgents(
     baseUrl,
     apiKey,
     q: query,
-    tag: params.tag,
+    provider,
+    tag,
     listing: params.listing,
     maxAgents: params.limit,
   });
 
   const total = result.totalCount ?? result.agents.length;
 
+  // Describe whatever constraints were actually applied so the header reflects
+  // a provider/tag-only search as accurately as a free-text one.
+  const criteria = describeSearchCriteria(query, provider, tag);
+
   // 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):`;
+    const header = `Agents ${criteria} (${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):`;
+  const header = `Agents ${criteria} (${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}`;
+  const provider = a.orgName ?? '';
+  return `${a.agentName} | ${a.name ?? a.agentName} | ${provider} | ${a.listing ?? 'public'} | ${tags}`;
+}
+
+/**
+ * Build the result-header phrase from whichever search constraints were
+ * applied, e.g. `matching "trans"`, `from provider "Hamilton"`, or
+ * `matching "trans" from provider "Hamilton" with tag "data"`. At least one
+ * constraint is always present (the handler rejects an empty search).
+ */
+function describeSearchCriteria(
+  query: string | undefined,
+  provider: string | undefined,
+  tag: string | undefined,
+): string {
+  const parts: string[] = [];
+  if (query) parts.push(`matching "${query}"`);
+  if (provider) parts.push(`from provider "${provider}"`);
+  if (tag) parts.push(`with tag "${tag}"`);
+  return parts.join(' ');
 }
 
 /**

package/tests/list-agents.test.ts

@@ -21,6 +21,7 @@ describe('list_agents', () => {
             agentName: 'alice',
             name: 'Alice',
             listing: 'public',
+            orgName: 'Hamilton Labs',
             tags: [
               { id: 'translate', name: 'Translate' },
               { id: 'summarize', name: 'Summarize' },
@@ -35,10 +36,11 @@ describe('list_agents', () => {
 
     const res = await listAgents({}, deps);
     const lines = res.content[0].text.split('\n');
+    // Row format: agentName | displayName | provider | listing | tags
     expect(lines).toEqual([
       'Agents (2 online of 2 total):',
-      'alice | Alice | public | Translate, Summarize',
-      'bob | bob | private | ',
+      'alice | Alice | Hamilton Labs | public | Translate, Summarize',
+      'bob | bob |  | private | ',
     ]);
   });
 
@@ -62,6 +64,16 @@ describe('list_agents', () => {
     });
   });
 
+  it('forwards the provider filter to the registry helper', async () => {
+    const { deps, mocks } = makeFakeDeps();
+
+    await listAgents({ provider: 'Acme Corp' }, deps);
+
+    expect(mocks.listAgents).toHaveBeenCalledWith(
+      expect.objectContaining({ provider: 'Acme Corp' }),
+    );
+  });
+
   it('defaults to "public" for missing listing and uses agentName when name is absent', async () => {
     const { deps } = makeFakeDeps({
       listAgentsResult: {
@@ -72,7 +84,7 @@ describe('list_agents', () => {
     });
 
     const res = await listAgents({}, deps);
-    expect(res.content[0].text).toContain('naked | naked | public |');
+    expect(res.content[0].text).toContain('naked | naked |  | public |');
   });
 
   it('uses the online agent count for the header, falling back to length for total', async () => {
@@ -124,7 +136,7 @@ describe('list_agents', () => {
     const lines = res.content[0].text.split('\n');
     expect(lines).toEqual([
       'Agents (1 online of 2 total):',
-      'online | Online | public | ',
+      'online | Online |  | public | ',
     ]);
     expect(mocks.fetchAgentStatus).toHaveBeenCalledWith({
       baseUrl: 'http://api.test',
@@ -165,7 +177,7 @@ describe('list_agents', () => {
     const lines = res.content[0].text.split('\n');
     expect(lines).toEqual([
       'Agents (1 online of 2 total):',
-      'valid_name | valid_name | public | ',
+      'valid_name | valid_name |  | public | ',
     ]);
   });
 });

package/tests/registry-list.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 import {
+  composeSearchQuery,
   listAgentsAuthenticated,
   listAllAgentsAuthenticated,
 } from '../src/registry-list.js';
@@ -16,6 +17,36 @@ function mockResponse(body: unknown, ok = true, status = 200): Response {
   } as Response;
 }
 
+describe('composeSearchQuery', () => {
+  it('returns the query unchanged when no provider is given', () => {
+    expect(composeSearchQuery('translate', undefined)).toBe('translate');
+    expect(composeSearchQuery(undefined, undefined)).toBeUndefined();
+  });
+
+  it('emits a quoted provider qualifier when only a provider is given', () => {
+    expect(composeSearchQuery(undefined, 'Acme Corp')).toBe('provider:"Acme Corp"');
+  });
+
+  it('combines free text and provider with a space (AND)', () => {
+    expect(composeSearchQuery('translate', 'Acme')).toBe('translate provider:"Acme"');
+  });
+
+  it('trims whitespace around both inputs', () => {
+    expect(composeSearchQuery('  translate  ', '  Acme  ')).toBe(
+      'translate provider:"Acme"',
+    );
+  });
+
+  it('treats a blank provider as absent', () => {
+    expect(composeSearchQuery('translate', '   ')).toBe('translate');
+    expect(composeSearchQuery(undefined, '   ')).toBeUndefined();
+  });
+
+  it('strips embedded quotes so the qualifier stays balanced', () => {
+    expect(composeSearchQuery(undefined, 'Ac"me')).toBe('provider:"Acme"');
+  });
+});
+
 describe('listAgentsAuthenticated', () => {
   it('sends Blocks-Protocol-Version header on every request', async () => {
     const fetchImpl = vi.fn().mockResolvedValue(
@@ -75,6 +106,39 @@ describe('listAgentsAuthenticated', () => {
     expect(parsed.searchParams.get('limit')).toBe('50');
   });
 
+  it('folds the provider filter into the q param as a quoted qualifier', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      mockResponse({ agents: [], totalCount: 0 }),
+    );
+
+    await listAgentsAuthenticated({
+      baseUrl: 'http://api.test',
+      q: 'translate',
+      provider: 'Acme Corp',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    const [url] = fetchImpl.mock.calls[0];
+    expect(new URL(String(url)).searchParams.get('q')).toBe(
+      'translate provider:"Acme Corp"',
+    );
+  });
+
+  it('sets q to just the provider qualifier when no free text is given', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      mockResponse({ agents: [], totalCount: 0 }),
+    );
+
+    await listAgentsAuthenticated({
+      baseUrl: 'http://api.test',
+      provider: 'Acme',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    const [url] = fetchImpl.mock.calls[0];
+    expect(new URL(String(url)).searchParams.get('q')).toBe('provider:"Acme"');
+  });
+
   it('does not set scope=owned for public listing', async () => {
     const fetchImpl = vi.fn().mockResolvedValue(
       mockResponse({ agents: [], totalCount: 0 }),

package/tests/search-agent.test.ts

@@ -34,6 +34,16 @@ describe('search_agent', () => {
     });
   });
 
+  it('forwards the provider filter to the registry helper', async () => {
+    const { deps, mocks } = makeFakeDeps();
+
+    await searchAgents({ query: 'translate', provider: 'Acme Corp' }, deps);
+
+    expect(mocks.listAgents).toHaveBeenCalledWith(
+      expect.objectContaining({ q: 'translate', provider: 'Acme Corp' }),
+    );
+  });
+
   it('renders matching agents with the query in the header', async () => {
     const { deps } = makeFakeDeps({
       listAgentsResult: {
@@ -42,6 +52,7 @@ describe('search_agent', () => {
             agentName: 'alice',
             name: 'Alice',
             listing: 'public',
+            orgName: 'Hamilton Labs',
             tags: [{ id: 'translate', name: 'Translate' }],
           },
         ],
@@ -52,9 +63,10 @@ describe('search_agent', () => {
 
     const res = await searchAgents({ query: 'trans' }, deps);
     const lines = res.content[0].text.split('\n');
+    // Row format: agentName | displayName | provider | listing | tags
     expect(lines).toEqual([
       'Agents matching "trans" (1 online of 1 total):',
-      'alice | Alice | public | Translate',
+      'alice | Alice | Hamilton Labs | public | Translate',
     ]);
   });
 
@@ -68,15 +80,65 @@ describe('search_agent', () => {
     );
   });
 
-  it('rejects an empty (or whitespace-only) query without calling the registry', async () => {
+  it('rejects a search with no query, provider, or tag 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(res.content[0].text).toContain('at least one of');
     expect(mocks.listAgents).not.toHaveBeenCalled();
   });
 
+  it('allows a provider-only search with no query', async () => {
+    const { deps, mocks } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [{ agentName: 'alice', name: 'Alice', listing: 'public' }],
+        totalCount: 1,
+      },
+      agentStatusResult: allOnline('alice'),
+    });
+
+    const res = await searchAgents({ provider: 'Hamilton' }, deps);
+
+    expect(res.isError).toBeUndefined();
+    expect(mocks.listAgents).toHaveBeenCalledWith(
+      expect.objectContaining({ q: undefined, provider: 'Hamilton' }),
+    );
+    expect(res.content[0].text.split('\n')[0]).toBe(
+      'Agents from provider "Hamilton" (1 online of 1 total):',
+    );
+  });
+
+  it('allows a tag-only search with no query', async () => {
+    const { deps, mocks } = makeFakeDeps({
+      listAgentsResult: { agents: [], totalCount: 0 },
+    });
+
+    const res = await searchAgents({ tag: 'data' }, deps);
+
+    expect(res.isError).toBeUndefined();
+    expect(mocks.listAgents).toHaveBeenCalledWith(
+      expect.objectContaining({ tag: 'data' }),
+    );
+    expect(res.content[0].text.split('\n')[0]).toBe(
+      'Agents with tag "data" (0 online of 0 total):',
+    );
+  });
+
+  it('combines query, provider, and tag in the header', async () => {
+    const { deps } = makeFakeDeps({
+      listAgentsResult: { agents: [], totalCount: 0 },
+    });
+
+    const res = await searchAgents(
+      { query: 'trans', provider: 'Hamilton', tag: 'data' },
+      deps,
+    );
+    expect(res.content[0].text.split('\n')[0]).toBe(
+      'Agents matching "trans" from provider "Hamilton" with tag "data" (0 online of 0 total):',
+    );
+  });
+
   it('drops offline matches by default, keeping only online ones', async () => {
     const { deps } = makeFakeDeps({
       listAgentsResult: {
@@ -98,7 +160,7 @@ describe('search_agent', () => {
     const lines = res.content[0].text.split('\n');
     expect(lines).toEqual([
       'Agents matching "foo" (1 online of 2 total):',
-      'online | Online | public | ',
+      'online | Online |  | public | ',
     ]);
   });