mcp-ipfs

Instructions

Implementation Reference

• src/tool_handlers.ts:771-810 (handler)

  The handler function that executes the w3_usage_report tool. Parses input arguments using the schema, constructs and runs the 'w3 usage report' CLI command with optional --space and --json flags, parses NDJSON output if applicable, and returns a formatted MCP response.

  const handleW3UsageReport: ToolHandler = async (args) => {
    const parsed = Schemas.W3UsageReportArgsSchema.safeParse(args);
    if (!parsed.success)
      throw new Error(
        `Invalid arguments for w3_usage_report: ${parsed.error.message}`
      );
    const { spaceDid, json } = parsed.data;
    let command = "usage report";
    if (spaceDid) command += ` --space ${spaceDid}`;
    if (json) command += " --json";
    const { stdout } = await runW3Command(command);
    if (json) {
      try {
        const report = parseNdJson(stdout);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                usageReport: report.length > 0 ? report[0] : {},
              }),
            },
          ],
        };
      } catch (e) {
        logger.warn("Failed to parse usage report JSON, returning raw.");
        return {
          content: [
            { type: "text", text: JSON.stringify({ output: stdout.trim() }) },
          ],
        };
      }
    } else {
      return {
        content: [
          { type: "text", text: JSON.stringify({ output: stdout.trim() }) },
        ],
      };
    }
  };

• src/schemas.ts:321-338 (schema)

  Zod schema for input validation of w3_usage_report tool arguments: optional spaceDid (DID starting with did:key:), optional json boolean (defaults to true). Includes tool description.

  export const W3UsageReportArgsSchema = z
    .object({
      spaceDid: z
        .string()
        .startsWith("did:key:")
        .optional()
        .describe(
          "Optional DID of the space to get usage for (defaults to current space)."
        ),
      json: z
        .boolean()
        .optional()
        .default(true)
        .describe("Format output as JSON (default: true)."),
    })
    .describe(
      "Displays a storage usage report for the current or specified space."
    );

• src/tool_handlers.ts:973-973 (registration)

  Registers the handleW3UsageReport handler under the 'w3_usage_report' key in the toolHandlers map, which is imported and used in src/index.ts to dynamically dispatch tool calls based on the requested tool name.

  w3_usage_report: handleW3UsageReport,