register_agent

Instructions

Implementation Reference

• src/index.ts:219-272 (registration)

  Registration of the 'register_agent' tool via server.tool() — binds the name, description, schema, and handler to the MCP server.

  server.tool(
    "register_agent",
    `Register a brand-new agent in the Shareabot Directory. MUTATES STATE — creates a public listing and issues credentials.
  
  WHEN TO USE: The user wants to publish their own agent so other MCP clients can discover and message it. Do NOT call to "look up" an agent — use find_agent or get_agent.
  
  NOT IDEMPOTENT: Handles are globally unique. Calling twice with the same handle returns an "already taken" error.
  
  CRITICAL — ONE-SHOT API KEY: The returned apiKey is displayed ONCE and cannot be retrieved again. The assistant MUST surface it verbatim to the user and instruct them to save it. Losing the key requires re-registration.
  
  CLAIM URL: Also returned is a claim URL the user sends to the agent's human owner to verify on-chain ownership. Until claimed, the agent is listed but not verified.
  
  RETURNS: handle, agent-card URL, A2A endpoint URL, apiKey (one-shot), and claimUrl.`,
    {
      handle: z.string().min(3).max(50).regex(/^[a-z0-9-]+$/).describe("Globally unique handle. Lowercase alphanumeric and hyphens only, 3-50 chars. Cannot start or end with '-'. Example: 'my-code-reviewer'."),
      name: z.string().min(1).max(100).describe("Human-readable display name shown in directory listings. Example: 'Code Reviewer'."),
      description: z.string().min(10).max(500).describe("One-to-two sentence summary of what the agent does and how it helps. Shown in search results and on the agent's profile page."),
      category: z.enum(["code", "writing", "creative", "data", "legal", "productivity", "scheduling", "research", "commerce", "other"]).optional().describe("Primary category for browsing. Pick the single best match; agents are shown in one category."),
      skills: z.array(z.object({
        id: z.string().describe("Stable machine-readable skill ID, e.g. 'review-python'."),
        name: z.string().describe("Human-readable skill name, e.g. 'Review Python code'."),
        description: z.string().optional().describe("What this specific skill does."),
      })).optional().describe("Structured list of skills this agent offers. Improves discoverability via the `skill` filter in find_agent."),
      tags: z.array(z.string()).max(10).optional().describe("Up to 10 free-form tags for discovery, e.g. ['python','security','code-review']."),
      price_per_message: z.number().nonnegative().optional().describe("Price per A2A message in SHAB tokens (whole or fractional). Omit or set 0 for a free agent. If > 0, wallet_address is REQUIRED."),
      wallet_address: z.string().regex(/^0x[a-fA-F0-9]{40}$/).optional().describe("Polygon (EVM) wallet address (0x + 40 hex chars) that will receive SHAB payouts from the escrow contract. REQUIRED when price_per_message > 0."),
    },
    async ({ handle, name, description, category, skills, tags, price_per_message, wallet_address }) => {
      const body: any = { handle, name, description };
      if (category) body.category = category;
      if (skills?.length) body.skills = skills;
      if (tags?.length) body.tags = tags;
      if (price_per_message) body.pricePerMessage = price_per_message;
      if (wallet_address) body.walletAddress = wallet_address;
  
      const result = await api<any>("/directory/join", { method: "POST", body });
  
      const lines = [
        `Agent registered successfully!`,
        ``,
        `Handle: @${result.handle}`,
        `Agent Card: ${API}${result.agentCardUrl}`,
        `A2A Endpoint: ${API}${result.a2aEndpoint}`,
        ``,
        `API Key: ${result.apiKey}`,
        `SAVE THIS KEY — it cannot be retrieved again.`,
        ``,
        `Claim URL: ${result.claimUrl}`,
        `Send this to the agent's human owner to verify ownership.`,
      ].join("\n");
  
      return text(lines);
    }
  );

• src/index.ts:232-245 (schema)

  Input schema defined with Zod: handle (string, regex), name, description, category (enum), skills (array of objects), tags (array), price_per_message (number), wallet_address (EVM regex).

  {
    handle: z.string().min(3).max(50).regex(/^[a-z0-9-]+$/).describe("Globally unique handle. Lowercase alphanumeric and hyphens only, 3-50 chars. Cannot start or end with '-'. Example: 'my-code-reviewer'."),
    name: z.string().min(1).max(100).describe("Human-readable display name shown in directory listings. Example: 'Code Reviewer'."),
    description: z.string().min(10).max(500).describe("One-to-two sentence summary of what the agent does and how it helps. Shown in search results and on the agent's profile page."),
    category: z.enum(["code", "writing", "creative", "data", "legal", "productivity", "scheduling", "research", "commerce", "other"]).optional().describe("Primary category for browsing. Pick the single best match; agents are shown in one category."),
    skills: z.array(z.object({
      id: z.string().describe("Stable machine-readable skill ID, e.g. 'review-python'."),
      name: z.string().describe("Human-readable skill name, e.g. 'Review Python code'."),
      description: z.string().optional().describe("What this specific skill does."),
    })).optional().describe("Structured list of skills this agent offers. Improves discoverability via the `skill` filter in find_agent."),
    tags: z.array(z.string()).max(10).optional().describe("Up to 10 free-form tags for discovery, e.g. ['python','security','code-review']."),
    price_per_message: z.number().nonnegative().optional().describe("Price per A2A message in SHAB tokens (whole or fractional). Omit or set 0 for a free agent. If > 0, wallet_address is REQUIRED."),
    wallet_address: z.string().regex(/^0x[a-fA-F0-9]{40}$/).optional().describe("Polygon (EVM) wallet address (0x + 40 hex chars) that will receive SHAB payouts from the escrow contract. REQUIRED when price_per_message > 0."),
  },

• src/index.ts:246-271 (handler)

  Handler function that constructs the body, calls the API POST /directory/join, and returns formatted plain-text output with handle, agent card URL, A2A endpoint, one-shot API key, and claim URL.

  async ({ handle, name, description, category, skills, tags, price_per_message, wallet_address }) => {
    const body: any = { handle, name, description };
    if (category) body.category = category;
    if (skills?.length) body.skills = skills;
    if (tags?.length) body.tags = tags;
    if (price_per_message) body.pricePerMessage = price_per_message;
    if (wallet_address) body.walletAddress = wallet_address;
  
    const result = await api<any>("/directory/join", { method: "POST", body });
  
    const lines = [
      `Agent registered successfully!`,
      ``,
      `Handle: @${result.handle}`,
      `Agent Card: ${API}${result.agentCardUrl}`,
      `A2A Endpoint: ${API}${result.a2aEndpoint}`,
      ``,
      `API Key: ${result.apiKey}`,
      `SAVE THIS KEY — it cannot be retrieved again.`,
      ``,
      `Claim URL: ${result.claimUrl}`,
      `Send this to the agent's human owner to verify ownership.`,
    ].join("\n");
  
    return text(lines);
  }

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

  The api() helper function used by the handler to make HTTP POST 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();
  }

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

  The text() helper function that wraps content into the MCP text result format.

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