Bulk verify US addresses

Instructions

Implementation Reference

• src/tools/verifications.ts:128-135 (handler)

  The handler function for the lob_bulk_us_verifications_create tool. It extracts 'extra' from args, then makes a POST request to '/bulk/us_verifications' with the remaining arguments merged with extra params via withExtra().

  handler: async (args) => {
    const { extra, ...rest } = args;
    return lob.request({
      method: "POST",
      path: "/bulk/us_verifications",
      body: withExtra(rest, extra),
    });
  },

• src/tools/verifications.ts:117-136 (schema)

  The full registration block for lob_bulk_us_verifications_create including input schema. The schema accepts addresses (array of 1-1000 objects matching usAddressInputSchema), an optional 'case' enum (upper/proper), and optional 'extra' record.

  registerTool(server, {
    name: "lob_bulk_us_verifications_create",
    annotations: { title: "Bulk verify US addresses", ...ToolAnnotationPresets.read },
    description:
      "Verify up to 1,000 US addresses in a single request. Returns one verification result per " +
      "input, in the same order.",
    inputSchema: {
      addresses: z.array(z.object(usAddressInputSchema).passthrough()).min(1).max(1000),
      case: z.enum(["upper", "proper"]).optional(),
      extra: extraParamsSchema,
    },
    handler: async (args) => {
      const { extra, ...rest } = args;
      return lob.request({
        method: "POST",
        path: "/bulk/us_verifications",
        body: withExtra(rest, extra),
      });
    },
  });

• src/tools/verifications.ts:117-136 (registration)

  The tool is registered via registerTool() (from src/tools/helpers.ts) on the MCP server. registerTool wraps the handler with error handling and formats the result as JSON text content.

  registerTool(server, {
    name: "lob_bulk_us_verifications_create",
    annotations: { title: "Bulk verify US addresses", ...ToolAnnotationPresets.read },
    description:
      "Verify up to 1,000 US addresses in a single request. Returns one verification result per " +
      "input, in the same order.",
    inputSchema: {
      addresses: z.array(z.object(usAddressInputSchema).passthrough()).min(1).max(1000),
      case: z.enum(["upper", "proper"]).optional(),
      extra: extraParamsSchema,
    },
    handler: async (args) => {
      const { extra, ...rest } = args;
      return lob.request({
        method: "POST",
        path: "/bulk/us_verifications",
        body: withExtra(rest, extra),
      });
    },
  });

• src/tools/helpers.ts:85-117 (helper)

  The registerTool helper function used to register all tools including lob_bulk_us_verifications_create. It wraps each tool's handler with try/catch error handling and formats results as JSON text content.

  export function registerTool<TShape extends ZodRawShape>(
    server: McpServer,
    def: ToolDefinition<TShape>,
  ): void {
    const a = def.annotations ?? {};
    server.registerTool(
      def.name,
      {
        title: a.title ?? def.name,
        description: def.description,
        inputSchema: def.inputSchema,
        annotations: {
          ...a,
          // Lob is always external; default the hint accordingly.
          openWorldHint: a.openWorldHint ?? true,
        },
      },
      // The SDK's ToolCallback type is parameterised over the exact ZodRawShape and
      // resists the generic erasure here. The runtime contract (validated args in,
      // CallToolResult out) is correct, so we bridge the type boundary with `as never`.
      (async (args: unknown, serverCtx: unknown): Promise<CallToolResult> => {
        try {
          const result = await def.handler(args as never, serverCtx);
          return { content: [{ type: "text", text: stringifyResult(result) }] };
        } catch (err) {
          return {
            isError: true,
            content: [{ type: "text", text: formatErrorForTool(err) }],
          };
        }
      }) as never,
    );
  }

• src/schemas/common.ts:160-166 (helper)

  The withExtra helper function used in the handler to merge typed args with the extraparams escape hatch. The typed fields take precedence over extra values.

  /** Merge an `extra` record into a typed payload, with explicit fields taking precedence. */
  export function withExtra(
    payload: object,
    extra: Record<string, unknown> | undefined,
  ): Record<string, unknown> {
    return { ...(extra ?? {}), ...compact(payload) };
  }