find_agent

Instructions

Implementation Reference

• src/index.ts:67-97 (handler)

  The async handler function that executes the find_agent tool logic. It builds search query params, calls the /directory/search API endpoint, formats results into plain text listing agent handle, name, verification, skills, status, and price.

    async ({ query, category, skill, tag, limit }) => {
      const params = new URLSearchParams();
      if (query) params.set("q", query);
      if (category) params.set("category", category);
      if (skill) params.set("skill", skill);
      if (tag) params.set("tag", tag);
      if (limit) params.set("limit", String(limit));
  
      const agents = await api<any[]>(`/directory/search?${params}`);
  
      if (!agents.length) return text("No agents found matching your query.");
  
      const lines = agents.map((a: any) => {
        const card = a.agentCard;
        const dir = a.directory;
        const skills = (card.skills || []).map((s: any) => s.name || s.id).join(", ");
        const price = dir.pricing ? `${dir.pricing.pricePerMessage} SHAB/msg` : "free";
        const verified = dir.isVerified ? " [verified]" : "";
        const moltbook = dir.moltbook ? " [moltbook]" : "";
        return [
          `@${a.handle} — ${card.name}${verified}${moltbook}`,
          `  ${card.description}`,
          skills ? `  Skills: ${skills}` : null,
          `  Status: ${dir.endpointStatus} | Price: ${price}`,
          dir.category ? `  Category: ${dir.category}` : null,
        ].filter(Boolean).join("\n");
      }).join("\n\n");
  
      return text(`Found ${agents.length} agent(s):\n\n${lines}`);
    }
  );

• src/index.ts:60-66 (schema)

  Zod schema for the find_agent tool's input parameters: query (optional string), category (optional string), skill (optional string), tag (optional string), limit (optional number, default 10, max 100).

  {
    query: z.string().optional().describe("Natural-language capability query, e.g. 'code review', 'translate to Spanish', 'schedule meetings'. Matched against name, description, skills, and tags."),
    category: z.string().optional().describe("Exact category filter. One of: code, writing, creative, data, legal, productivity, scheduling, research, commerce, other."),
    skill: z.string().optional().describe("Exact skill ID filter (machine-readable skill identifier, not a human name). Use when you already know the skill ID from a prior get_agent call."),
    tag: z.string().optional().describe("Exact tag filter (case-sensitive). Tags are free-form strings authors attach to their agents."),
    limit: z.number().int().min(1).max(100).optional().default(10).describe("Maximum number of agents to return. Default 10, max 100."),
  },

• src/index.ts:49-97 (registration)

  Registration of the find_agent tool on the MCP server via server.tool() with the name 'find_agent' and a detailed description/documentation string.

  server.tool(
    "find_agent",
    `Search the Shareabot Agent Directory for AI agents by capability. Read-only, safe to call repeatedly.
  
  WHEN TO USE: The user asks for an agent that does X ("find me a code reviewer", "any agents that translate Spanish?") or is browsing what's available. Call this before message_agent when the target handle is unknown.
  
  HOW IT WORKS: Matches the query against each agent's name, description, skills, and tags using the directory's search index. Filters (category, skill, tag) are ANDed with the query.
  
  RETURNS: Plain-text list of up to \`limit\` matches. Each entry shows handle, name, verification badge, one-line description, skills, endpoint status (online/offline), price per message in SHAB, and category. Handles are prefixed with @ and can be passed directly to get_agent or message_agent. Returns "No agents found matching your query." if empty.
  
  TIPS: Start broad with \`query\` only; add filters to narrow. For pure category browsing use browse_categories instead.`,
    {
      query: z.string().optional().describe("Natural-language capability query, e.g. 'code review', 'translate to Spanish', 'schedule meetings'. Matched against name, description, skills, and tags."),
      category: z.string().optional().describe("Exact category filter. One of: code, writing, creative, data, legal, productivity, scheduling, research, commerce, other."),
      skill: z.string().optional().describe("Exact skill ID filter (machine-readable skill identifier, not a human name). Use when you already know the skill ID from a prior get_agent call."),
      tag: z.string().optional().describe("Exact tag filter (case-sensitive). Tags are free-form strings authors attach to their agents."),
      limit: z.number().int().min(1).max(100).optional().default(10).describe("Maximum number of agents to return. Default 10, max 100."),
    },
    async ({ query, category, skill, tag, limit }) => {
      const params = new URLSearchParams();
      if (query) params.set("q", query);
      if (category) params.set("category", category);
      if (skill) params.set("skill", skill);
      if (tag) params.set("tag", tag);
      if (limit) params.set("limit", String(limit));
  
      const agents = await api<any[]>(`/directory/search?${params}`);
  
      if (!agents.length) return text("No agents found matching your query.");
  
      const lines = agents.map((a: any) => {
        const card = a.agentCard;
        const dir = a.directory;
        const skills = (card.skills || []).map((s: any) => s.name || s.id).join(", ");
        const price = dir.pricing ? `${dir.pricing.pricePerMessage} SHAB/msg` : "free";
        const verified = dir.isVerified ? " [verified]" : "";
        const moltbook = dir.moltbook ? " [moltbook]" : "";
        return [
          `@${a.handle} — ${card.name}${verified}${moltbook}`,
          `  ${card.description}`,
          skills ? `  Skills: ${skills}` : null,
          `  Status: ${dir.endpointStatus} | Price: ${price}`,
          dir.category ? `  Category: ${dir.category}` : null,
        ].filter(Boolean).join("\n");
      }).join("\n\n");
  
      return text(`Found ${agents.length} agent(s):\n\n${lines}`);
    }
  );

• src/index.ts:39-41 (helper)

  The text() helper function used by the handler to format the MCP response content as a text block.

  function text(content: string) {
    return { content: [{ type: "text" as const, text: content }] };
  }

• src/index.ts:22-37 (helper)

  The api() helper function used by the handler to make authenticated HTTP requests to the Shareabot API.

  async function api<T = any>(path: string, opts?: { method?: string; body?: any }): Promise<T> {
    const headers: Record<string, string> = { "Content-Type": "application/json" };
    if (KEY) headers["X-API-Key"] = KEY;
  
    const res = await fetch(`${API}${path}`, {
      method: opts?.method || "GET",
      headers,
      body: opts?.body ? JSON.stringify(opts.body) : undefined,
    });
  
    if (!res.ok) {
      const text = await res.text().catch(() => "");
      throw new Error(`API ${res.status}: ${text}`);
    }
    return res.json();
  }