Retrieve a letter

Instructions

Implementation Reference

• src/tools/letters.ts:169-176 (handler)

  The handler for lob_letters_get. It is an inline async function that calls lob.request() with method GET and path `/letters/${id}`, retrieving a single letter by its ID.

  registerTool(server, {
    name: "lob_letters_get",
    annotations: { title: "Retrieve a letter", ...ToolAnnotationPresets.read },
    description: "Retrieve a single letter by ID.",
    inputSchema: { id: LETTER_ID },
    handler: async ({ id }) =>
      lob.request({ method: "GET", path: `/letters/${id}` }),
  });

• src/tools/letters.ts:35-35 (schema)

  The LETTER_ID schema used as the input schema for lob_letters_get. Validates that the ID matches the pattern `ltr_`.

  const LETTER_ID = z.string().regex(/^ltr_/).describe("Letter ID (`ltr_…`).");

• src/tools/letters.ts:169-176 (registration)

  Registration of lob_letters_get via registerTool() with name, annotations (title 'Retrieve a letter', read preset), description, inputSchema, and handler.

  registerTool(server, {
    name: "lob_letters_get",
    annotations: { title: "Retrieve a letter", ...ToolAnnotationPresets.read },
    description: "Retrieve a single letter by ID.",
    inputSchema: { id: LETTER_ID },
    handler: async ({ id }) =>
      lob.request({ method: "GET", path: `/letters/${id}` }),
  });

• src/tools/register.ts:37-37 (registration)

  Top-level registration entry point: registerLetterTools is called, which wires up all letter tools including lob_letters_get.

  registerLetterTools(server, lob, tokenStore, pieceCounter);

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

  The registerTool helper function that wraps the MCP server's registerTool with consistent error handling, annotation support, and JSON content formatting.

  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,