SupaThings MCP

Implementation Reference

• src/index.ts:1999-2014 (handler)

  The 'json' tool handler, which processes a raw JSON payload for creating structured items in Things 3, including project-with-headings structures.

    "json",
    {
      "auth-token": z.string().optional(),
      data: z.string().describe("Raw Things JSON payload. Prefer this tool for creating a brand-new project with headings and nested to-dos in one operation."),
      reveal: z.boolean().optional().describe("Reveal the first created item in Things after processing the JSON payload"),
    },
    async (params) => {
      const enriched = await enrichWriteParams("json", { ...params });
      const url = await openThingsURL("json", buildURLParams(enriched));
      return buildTextResponse("Processed JSON payload in Things", {
        url,
        guidance:
          "Use this tool for structured creation flows, especially brand-new projects that need headings. Do not rely on it to add new headings to an existing project unless the payload is creating the project itself.",
      });
    }
  );