bubblyphone-agents

Instructions

Implementation Reference

• src/tools/phone-numbers.ts:51-59 (registration)

  Registration of the 'list_phone_numbers' tool with the MCP server. Defines the tool name, description, empty input schema, read-only annotations, and the handler function.

  server.registerTool(
    "list_phone_numbers",
    {
      description: "List your owned phone numbers with their status and configuration.",
      inputSchema: {},
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
    },
    async () => callTool(() => client.get("/phone-numbers"))
  );

• src/tools/phone-numbers.ts:58-58 (handler)

  The handler function for 'list_phone_numbers' that executes the tool logic. Makes a GET request to the /phone-numbers endpoint via the client and wraps it with the callTool helper for error handling.

  async () => callTool(() => client.get("/phone-numbers"))

• src/tools/phone-numbers.ts:13-20 (helper)

  Helper function 'callTool' that wraps API calls with standardized error handling. Catches ApiError exceptions and formats them as tool errors, while successful responses are formatted as JSON tool results.

  async function callTool<T>(fn: () => Promise<T>) {
    try {
      return toolResult(await fn());
    } catch (err) {
      const apiErr = err as ApiError;
      return toolError(`API error (${apiErr.status}): ${apiErr.message}`);
    }
  }

• src/tools/phone-numbers.ts:22-49 (registration)

  The containing function 'registerPhoneNumberTools' that registers all phone number related tools including 'list_phone_numbers'. Shows the pattern of how tools are registered with the MCP server.

  export function registerPhoneNumberTools(server: McpServer, client: BubblyPhoneClient) {
    server.registerTool(
      "search_phone_numbers",
      {
        description:
          "Search for available phone numbers to purchase. Filter by country, area code, or locality. " +
          "Returns numbers with pricing information.",
        inputSchema: {
          country_code: z.string().length(2).optional().describe("Two-letter country code (default: US)"),
          area_code: z.string().optional().describe("Area code to filter by"),
          locality: z.string().optional().describe("City or locality name"),
          number_type: z.enum(["local", "mobile", "toll_free", "national"]).optional().describe("Type of number (default: local)"),
          contains: z.string().optional().describe("Search for numbers containing this string"),
          limit: z.number().min(1).max(50).optional().describe("Max results (default: 20, max: 50)"),
        },
        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
      },
      async (params) => {
        const query: Record<string, string> = {};
        if (params.country_code) query.country = params.country_code;
        if (params.area_code) query.area_code = params.area_code;
        if (params.locality) query.locality = params.locality;
        if (params.number_type) query.number_type = params.number_type;
        if (params.contains) query.contains = params.contains;
        if (params.limit) query.limit = String(params.limit);
        return callTool(() => client.get("/phone-numbers/available", query));
      }
    );

• src/server.ts:21-21 (registration)

  The call site where registerPhoneNumberTools is invoked during server initialization, connecting the phone number tools (including list_phone_numbers) to the MCP server instance.

  registerPhoneNumberTools(server, client);