lithtrix_blob_upload

Instructions

Implementation Reference

• tools/blobs.js:133-192 (registration)

  The registerBlobTools function is called from index.js (line 48) to register all blob tools. Line 134 starts the registration of 'lithtrix_blob_upload' tool on the MCP server via server.tool().

  export function registerBlobTools(server) {
    server.tool(
      "lithtrix_blob_upload",
      "Upload binary bytes via PUT /v1/blobs (raw body + Content-Type). " +
        "Decode base64 from content_base64. For large files prefer direct HTTP multipart/raw PUT. " +
        "Requires LITHTRIX_API_KEY. Subject to BLOB_MAX_UPLOAD_BYTES and BLOB_STORAGE_LIMIT.",
      {
        content_base64: z
          .string()
          .min(1)
          .describe("Standard base64-encoded file bytes (no data: URL prefix)"),
        content_type: z
          .string()
          .min(1)
          .max(255)
          .describe("MIME type sent as Content-Type (e.g. application/pdf)"),
        filename: z
          .string()
          .max(512)
          .optional()
          .describe("Optional display filename (sent as filename query on the request)"),
      },
      async ({ content_base64, content_type, filename }) => {
        const apiKey = process.env.LITHTRIX_API_KEY;
        if (!apiKey) return missingApiKeyResponse();
  
        let binary;
        try {
          binary = Buffer.from(content_base64, "base64");
        } catch (err) {
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify({ error: `Invalid base64: ${err.message}` }),
              },
            ],
            isError: true,
          };
        }
  
        const url = new URL("/v1/blobs", LITHTRIX_API_URL);
        if (filename !== undefined) url.searchParams.set("filename", filename);
  
        let response;
        try {
          response = await fetch(url.toString(), {
            method: "PUT",
            headers: {
              Authorization: `Bearer ${apiKey}`,
              "Content-Type": content_type,
            },
            body: binary,
          });
        } catch (err) {
          return networkErrorResponse(err);
        }
        return apiJsonResponse(response);
      }
    );

• tools/blobs.js:155-191 (handler)

  The async handler function that executes 'lithtrix_blob_upload': decodes base64 from content_base64, sends PUT /v1/blobs with the binary body and Content-Type, and returns the API JSON response.

  async ({ content_base64, content_type, filename }) => {
    const apiKey = process.env.LITHTRIX_API_KEY;
    if (!apiKey) return missingApiKeyResponse();
  
    let binary;
    try {
      binary = Buffer.from(content_base64, "base64");
    } catch (err) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({ error: `Invalid base64: ${err.message}` }),
          },
        ],
        isError: true,
      };
    }
  
    const url = new URL("/v1/blobs", LITHTRIX_API_URL);
    if (filename !== undefined) url.searchParams.set("filename", filename);
  
    let response;
    try {
      response = await fetch(url.toString(), {
        method: "PUT",
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "Content-Type": content_type,
        },
        body: binary,
      });
    } catch (err) {
      return networkErrorResponse(err);
    }
    return apiJsonResponse(response);
  }

• tools/blobs.js:139-154 (schema)

  Zod schema definitions for the tool's input parameters: content_base64 (base64 string), content_type (MIME type), and optional filename (display name, sent as query param).

  {
    content_base64: z
      .string()
      .min(1)
      .describe("Standard base64-encoded file bytes (no data: URL prefix)"),
    content_type: z
      .string()
      .min(1)
      .max(255)
      .describe("MIME type sent as Content-Type (e.g. application/pdf)"),
    filename: z
      .string()
      .max(512)
      .optional()
      .describe("Optional display filename (sent as filename query on the request)"),
  },

• tools/blobs.js:16-30 (helper)

  Helper function missingApiKeyResponse() used when LITHTRIX_API_KEY is not set.

  function missingApiKeyResponse() {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            error:
              "LITHTRIX_API_KEY environment variable is not set. " +
              "Register at https://lithtrix.ai and use lithtrix_register, then set the key.",
          }),
        },
      ],
      isError: true,
    };
  }

• tools/blobs.js:46-73 (helper)

  Helper function apiJsonResponse() that processes the API response, handling errors and returning JSON content.

  async function apiJsonResponse(response) {
    let body;
    try {
      body = await response.json();
    } catch {
      body = { message: `Invalid JSON (HTTP ${response.status})` };
    }
  
    if (!response.ok) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              error: body.message ?? `Lithtrix API error (HTTP ${response.status})`,
              error_code: body.error_code ?? "UNKNOWN",
              status: body.status,
            }),
          },
        ],
        isError: true,
      };
    }
  
    return {
      content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
    };
  }