SupaThings MCP

Implementation Reference

• src/index.ts:1115-1174 (handler)

  The handler for the "validate-headings" tool. It takes a project UUID and a list of expected headings, compares them with the headings existing in the Things database, and returns a status indicating whether all required headings are present.

  server.tool(
    "validate-headings",
    {
      project_uuid: z.string().describe("UUID of the project to inspect"),
      expected_headings: z
        .array(z.string())
        .min(1)
        .describe("Heading names that should already exist in the project"),
    },
    async ({ project_uuid, expected_headings }) => {
      const result = await withDatabase((db) => {
        const tasks = getAllTasks(db);
        const project = tasks.find(
          (task) => task.type === "project" && task.id === project_uuid && !task.trashed
        );
        const existingHeadings = tasks
          .filter(
            (task) =>
              task.type === "heading" &&
              task.projectId === project_uuid &&
              !task.trashed
          )
          .map((task) => task.title);
  
        return {
          projectTitle: project?.title ?? null,
          existingHeadings,
        };
      });
  
      const existingByNormalized = new Map(
        result.existingHeadings.map((heading) => [normalizeHeadingName(heading), heading])
      );
      const expected = uniqueHeadingNames(expected_headings);
      const presentHeadings = expected
        .filter((heading) => existingByNormalized.has(normalizeHeadingName(heading)))
        .map((heading) => existingByNormalized.get(normalizeHeadingName(heading)) ?? heading);
      const missingHeadings = expected.filter(
        (heading) => !existingByNormalized.has(normalizeHeadingName(heading))
      );
  
      return buildTextResponse("Validated project headings", {
        projectUuid: project_uuid,
        projectTitle: result.projectTitle,
        expectedHeadings: expected,
        existingHeadings: result.existingHeadings,
        presentHeadings,
        missingHeadings,
        isReady: missingHeadings.length === 0,
        userInstruction:
          missingHeadings.length === 0
            ? "All required headings exist. You can continue creating or moving tasks into those headings."
            : buildHeadingCreationPrompt({
                projectTitle: result.projectTitle ?? undefined,
                suggestedHeadings: expected,
                missingHeadings,
              }),
      });
    }
  );