Pinata MCP

Instructions

Implementation Reference

• src/index.ts:249-291 (registration)

  The updateFile tool is registered with the MCP server, allowing updates to file metadata including name and key-value pairs on Pinata IPFS storage.

  server.tool(
    "updateFile",
    "Update metadata for an existing file on Pinata including name and key-value pairs",
    {
      network: z
        .enum(["public", "private"])
        .default("public")
        .describe("Whether the file is in public or private storage"),
      id: z.string().describe("The unique ID of the file to update"),
      name: z.string().optional().describe("New name for the file"),
      keyvalues: z
        .record(z.any())
        .optional()
        .describe("Metadata key-value pairs to update"),
    },
    async ({ network, id, name, keyvalues }) => {
      try {
        const url = `https://api.pinata.cloud/v3/files/${network}/${id}`;
  
        const payload: { name?: string; keyvalues?: Record<string, unknown> } =
          {};
        if (name) payload.name = name;
        if (keyvalues) payload.keyvalues = keyvalues;
  
        const response = await fetch(url, {
          method: "PUT",
          headers: getHeaders(),
          body: JSON.stringify(payload),
        });
  
        if (!response.ok) {
          throw new Error(
            `Failed to update file: ${response.status} ${response.statusText}`
          );
        }
  
        const data = await response.json();
        return successResponse(data);
      } catch (error) {
        return errorResponse(error);
      }
    }
  );

• src/index.ts:264-290 (handler)

  Handler function that executes the updateFile logic by sending a PUT request to the Pinata API with optional name and keyvalues metadata updates.

  async ({ network, id, name, keyvalues }) => {
    try {
      const url = `https://api.pinata.cloud/v3/files/${network}/${id}`;
  
      const payload: { name?: string; keyvalues?: Record<string, unknown> } =
        {};
      if (name) payload.name = name;
      if (keyvalues) payload.keyvalues = keyvalues;
  
      const response = await fetch(url, {
        method: "PUT",
        headers: getHeaders(),
        body: JSON.stringify(payload),
      });
  
      if (!response.ok) {
        throw new Error(
          `Failed to update file: ${response.status} ${response.statusText}`
        );
      }
  
      const data = await response.json();
      return successResponse(data);
    } catch (error) {
      return errorResponse(error);
    }
  }

• src/index.ts:252-262 (schema)

  Zod schema defining the input parameters for updateFile: network (public/private), id (required), name (optional), and keyvalues (optional).

  {
    network: z
      .enum(["public", "private"])
      .default("public")
      .describe("Whether the file is in public or private storage"),
    id: z.string().describe("The unique ID of the file to update"),
    name: z.string().optional().describe("New name for the file"),
    keyvalues: z
      .record(z.any())
      .optional()
      .describe("Metadata key-value pairs to update"),

• src/index.ts:121-124 (helper)

  Helper function that formats successful API responses into the standard MCP content format with JSON stringified data.

  // Helper for consistent success responses
  const successResponse = (data: unknown) => ({
    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
  });

• src/index.ts:110-119 (helper)

  Helper function that formats error responses into the standard MCP content format with error message and isError flag.

  // Helper for consistent error responses
  const errorResponse = (error: unknown) => ({
    content: [
      {
        type: "text" as const,
        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
      },
    ],
    isError: true,
  });