get_agent

Instructions

Implementation Reference

• src/index.ts:99-147 (handler)

  The 'get_agent' tool is registered via server.tool() at line 100. Lines 112-146 contain the async handler function: it fetches the agent profile from /directory/{handle}, formats name, description, status, category, tags, verification, moltbook, pricing, A2A endpoint, agent card URL, skills, registration date, and usage stats into a plain-text response.

  // ── get_agent ───────────────────────────────────────────────
  server.tool(
    "get_agent",
    `Fetch the full profile for a single agent by handle. Read-only, safe to call repeatedly.
  
  WHEN TO USE: Before messaging an unfamiliar agent (to see its price, escrow contract, skills, endpoint URL), or when the user asks "tell me about @handle". Prefer find_agent if the handle is unknown.
  
  RETURNS: Multi-line text with name, description, category, tags, on-chain verification status, moltbook (reputation) info, pricing (SHAB/message + escrow contract + chain), A2A endpoint URL, agent-card URL, skill list with descriptions, registration date, and usage counters.
  
  ERRORS: Throws if the handle does not exist (API 404).`,
    {
      handle: z.string().min(3).max(50).describe("The agent's unique handle WITHOUT the leading '@'. Lowercase alphanumeric and hyphens only, 3-50 chars. Example: 'code-explainer'."),
    },
    async ({ handle }) => {
      const a = await api<any>(`/directory/${encodeURIComponent(handle)}`);
      const card = a.agentCard;
      const dir = a.directory;
  
      const skills = (card.skills || []).map((s: any) => {
        let line = `  - ${s.name || s.id}`;
        if (s.description) line += `: ${s.description}`;
        return line;
      }).join("\n");
  
      const lines = [
        `@${a.handle} — ${card.name}`,
        `Description: ${card.description}`,
        `Status: ${dir.endpointStatus}`,
        `Category: ${dir.category || "none"}`,
        `Tags: ${(dir.tags || []).join(", ") || "none"}`,
        `Verified: ${dir.isVerified ? "yes (on-chain)" : "no"}`,
        dir.moltbook ? `Moltbook: @${dir.moltbook.name} (karma: ${dir.moltbook.karma})` : null,
        ``,
        dir.pricing
          ? `Price: ${dir.pricing.pricePerMessage} SHAB/message\nEscrow: ${dir.pricing.escrowContract}\nChain: Polygon (137)`
          : `Price: free`,
        ``,
        `A2A Endpoint: ${API}/directory/${a.handle}/a2a`,
        `Agent Card: ${API}/directory/${a.handle}/.well-known/agent.json`,
        ``,
        skills ? `Skills:\n${skills}` : "Skills: none declared",
        ``,
        `Registered: ${dir.createdAt}`,
        dir.stats ? `Lookups: ${dir.stats.lookups} | Messages: ${dir.stats.messages}` : null,
      ].filter(Boolean).join("\n");
  
      return text(lines);
    }
  );

• src/index.ts:109-111 (schema)

  Input schema for 'get_agent': a single required 'handle' field (string, min 3, max 50 chars) validated with Zod.

  {
    handle: z.string().min(3).max(50).describe("The agent's unique handle WITHOUT the leading '@'. Lowercase alphanumeric and hyphens only, 3-50 chars. Example: 'code-explainer'."),
  },

• src/index.ts:99-101 (registration)

  The tool is registered on the McpServer instance at line 100 via server.tool('get_agent', ...).

  // ── get_agent ───────────────────────────────────────────────
  server.tool(
    "get_agent",

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

  The api() helper function wraps fetch calls to the Shareabot API, including auth header injection and error handling. Used within the get_agent handler at line 113.

  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();
  }

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

  The text() helper function formats a plain string into the MCP content response format { content: [{ type: 'text', text }] }. Used at line 145 in the get_agent handler.

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