things-api 0.12.0 → 0.13.0

package/dist/mcp/server.js

@@ -16,7 +16,7 @@
  */
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ALL_DESC, AREA_FILTER_DESC, AREA_LIMIT_DESC, AREA_PREVIEW_LIMIT, blockedCode, capabilitiesTable, DATE_FORMAT, DEFAULT_LIST_LIMIT, diagnose, FILTER_CONTRACT, FULL_DESC, hasTagPresence, isLooseRef, isValidTimeZone, LIMIT_DESC, looseShadowNotice, MCP_WHEN_LABELS, mutationWireData, noUuidMatch, omitEmpty, OMIT_EMPTY_NOTE, OP_ID_RE, OPERATION_KINDS, openThings, PKG_VERSION, PROJECT_LIMIT_DESC, PROJECT_PREVIEW_LIMIT, REF_FORMAT, ReferenceResolutionError, REMINDER_FORMAT, schemaWarnings, shapeReadPayload, splitWhenSugar, tagFilterFields, tagFlagConflict, validateViewArgs, verifyFailedCode, WHEN_VALUES, } from "../index.js";
+import { ALL_DESC, AREA_FILTER_DESC, AREA_LIMIT_DESC, AREA_PREVIEW_LIMIT, blockedCode, capabilitiesTable, DATE_FORMAT, DEFAULT_LIST_LIMIT, diagnose, FILTER_CONTRACT, FULL_DESC, hasTagPresence, isLooseRef, isValidTimeZone, LIMIT_DESC, looseShadowNotice, MCP_WHEN_LABELS, mutationWireData, noUuidMatch, omitEmpty, OMIT_EMPTY_NOTE, OP_ID_RE, OPERATION_KINDS, openThings, PKG_VERSION, PROJECT_LIMIT_DESC, PROJECT_PREVIEW_LIMIT, REF_FORMAT, REF_RULE_NOTE, ReferenceResolutionError, REMINDER_FORMAT, schemaWarnings, shapeReadPayload, splitWhenSugar, tagFilterFields, tagFlagConflict, validateViewArgs, verifyFailedCode, WHEN_VALUES, } from "../index.js";
 function jsonResult(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
@@ -32,16 +32,22 @@ function readResult(data) {
 /**
  * A read result carrying truncation metadata: the data (already limited) in
  * the first content block, and a second block with the {@link Truncation}
- * numbers plus a one-line note the agent can read when rows were dropped.
+ * numbers plus a one-line note the agent can read when rows were dropped. `meta`
+ * merges extra whole-view metadata into that second block — the today view's
+ * `counts` aggregate (the analog of the CLI envelope's `meta.counts`), so `data`
+ * stays pure domain rows.
  */
-function truncatedResult(data, truncation) {
+function truncatedResult(data, truncation, meta) {
     const note = truncation.truncated
         ? `showing ${truncation.shown} of ${truncation.total} items — pass limit (or all: true) to see more`
         : undefined;
     return {
         content: [
             { type: "text", text: JSON.stringify(omitEmpty(data)) },
-            { type: "text", text: JSON.stringify({ truncation, ...(note !== undefined && { note }) }) },
+            {
+                type: "text",
+                text: JSON.stringify({ truncation, ...meta, ...(note !== undefined && { note }) }),
+            },
         ],
     };
 }
@@ -173,7 +179,11 @@ function moveResult(result) {
             return jsonResult(result.plan);
         case "move-refused":
             return errorResult({
-                code: result.refusal,
+                // A hoisted placement block names its hazard — surface the canonical
+                // `blocked:<hazard>` code, matching a direct reorder hazard block.
+                code: result.hazard !== undefined
+                    ? blockedCode({ hazard: result.hazard, reason: "hazard" })
+                    : result.refusal,
                 message: result.detail,
                 ...(result.remediation !== undefined && { remediation: result.remediation }),
                 ...(result.candidates !== undefined && { details: { candidates: result.candidates } }),
@@ -382,9 +392,10 @@ function buildInstructions(getClient) {
             "confirmation parameter named in their description; refused calls return an error saying " +
             "what to pass.",
         "- Read-result semantics: an item's tags are its direct tags; its effective tags also include " +
-            "tags inherited from its containing project and area. The today and evening markers are " +
-            "present only for an item in Today (evening implies today); an unscheduled start=active item " +
-            "is in Anytime and carries neither. Completing an item makes it findable in Logbook.",
+            "tags inherited from its containing project and area. An item's when is today or evening for " +
+            "a Today member (evening implies today), a future date for a scheduled item, else absent; an " +
+            "unscheduled start=active item is in Anytime and carries no when. Completing an item makes it " +
+            "findable in Logbook.",
         "- For capped reads, pass limit to cap rows or all: true for everything; if both are set, all wins.",
         `- Read results are compact: ${OMIT_EMPTY_NOTE}`,
     ];
@@ -566,8 +577,9 @@ export function createThingsMcpServer(options = {}) {
     };
     // ------------------------------------------------------------------ reads
     server.registerTool("read_view", {
-        description: "Read a Things list as the app presents it: today (split into Today and This " +
-            "Evening), inbox, anytime, upcoming, someday, logbook, or trash. For upcoming, " +
+        description: "Read a Things list as the app presents it: today (one flat list of Today " +
+            "members, each item's when marking Today vs This Evening), inbox, anytime, " +
+            "upcoming, someday, logbook, or trash. For upcoming, " +
             "horizon > 1 also includes future occurrences of repeating items (up to 10 each). " +
             "anytime/someday return sections in canonical order (area + items; null area = the " +
             "top-level block); children of someday/future-scheduled projects are excluded " +
@@ -578,7 +590,9 @@ export function createThingsMcpServer(options = {}) {
             `area_limit (default ${AREA_PREVIEW_LIMIT}) per area block, and on anytime ` +
             `project_limit (default ${PROJECT_PREVIEW_LIMIT}) per project block. ` +
             "all: true lifts every cap; the result's second block reports the counts. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             view: z.enum(["today", "inbox", "anytime", "upcoming", "someday", "logbook", "trash"]),
             ...tagFilterShape,
@@ -587,7 +601,10 @@ export function createThingsMcpServer(options = {}) {
                 .string()
                 .optional()
                 .describe(`today/anytime/someday/upcoming/logbook only: ${AREA_FILTER_DESC}`),
-            evening: z.boolean().optional().describe("today only: show only the This Evening section"),
+            evening: z
+                .boolean()
+                .optional()
+                .describe("today only: show only This-Evening members (when = evening)"),
             show_active_project_items: z
                 .union([z.boolean(), z.number().int().min(1)])
                 .optional()
@@ -698,11 +715,11 @@ export function createThingsMcpServer(options = {}) {
                         limit,
                     });
                     filterMeta = fm;
-                    return truncatedResult(shapeReadPayload("today", view, full), truncation);
+                    return truncatedResult(shapeReadPayload("today", view, full, c.refPromoter()), truncation, { counts: view.counts });
                 }
                 case "inbox": {
                     const { items, truncation } = c.read.inbox({ ...filter, ...zone, limit });
-                    return truncatedResult(shapeReadPayload("inbox", items, full), truncation);
+                    return truncatedResult(shapeReadPayload("inbox", items, full, c.refPromoter()), truncation);
                 }
                 case "anytime": {
                     const { view, truncation, filter: fm, } = c.read.anytime({
@@ -713,7 +730,7 @@ export function createThingsMcpServer(options = {}) {
                         projectLimit,
                     });
                     filterMeta = fm;
-                    return groupedResult(shapeReadPayload("anytime", view, full), truncation);
+                    return groupedResult(shapeReadPayload("anytime", view, full, c.refPromoter()), truncation);
                 }
                 case "upcoming": {
                     const { items, truncation, filter: fm, } = c.read.upcoming({
@@ -724,7 +741,7 @@ export function createThingsMcpServer(options = {}) {
                         limit,
                     });
                     filterMeta = fm;
-                    return truncatedResult(shapeReadPayload("upcoming", items, full), truncation);
+                    return truncatedResult(shapeReadPayload("upcoming", items, full, c.refPromoter()), truncation);
                 }
                 case "someday": {
                     const active = showActiveProjectItems;
@@ -743,7 +760,7 @@ export function createThingsMcpServer(options = {}) {
                         projectLimit: typeof active === "number" ? active : null,
                     });
                     filterMeta = fm;
-                    return groupedResult(shapeReadPayload("someday", view, full), truncation);
+                    return groupedResult(shapeReadPayload("someday", view, full, c.refPromoter()), truncation);
                 }
                 case "logbook": {
                     const { items, truncation, filter: fm, } = c.read.logbook({
@@ -753,11 +770,11 @@ export function createThingsMcpServer(options = {}) {
                         limit,
                     });
                     filterMeta = fm;
-                    return truncatedResult(shapeReadPayload("logbook", items, full), truncation);
+                    return truncatedResult(shapeReadPayload("logbook", items, full, c.refPromoter()), truncation);
                 }
                 case "trash": {
                     const { items, truncation } = c.read.trash({ ...zone, limit });
-                    return truncatedResult(shapeReadPayload("trash", items, full), truncation);
+                    return truncatedResult(shapeReadPayload("trash", items, full, c.refPromoter()), truncation);
                 }
             }
         }, args.tz, () => (filterMeta !== undefined ? { filter: filterMeta } : undefined), () => looseAreaWarnings(getClient(), args.area));
@@ -766,7 +783,9 @@ export function createThingsMcpServer(options = {}) {
         description: "Find items by title/notes substring. Returns open, untrashed items by default; " +
             "include more with logged/trashed/all. Scope with project/area/tag — scope " +
             "references must name existing items. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             query: z.string(),
             ...tagFilterShape,
@@ -821,13 +840,15 @@ export function createThingsMcpServer(options = {}) {
             ...(args.trashed === true && { trashed: true }),
             ...(args.all === true && { all: true }),
         });
-        return truncatedResult(shapeReadPayload("search", items, args.full === true), truncation);
+        return truncatedResult(shapeReadPayload("search", items, args.full === true, getClient().refPromoter()), truncation);
     }, args.tz, undefined, () => looseAreaWarnings(getClient(), args.area)));
     server.registerTool("changes_since", {
         description: "List items created or modified since a moment — including trashed, logged, and " +
             "repeating items (inspect each item's fields to tell them apart). Edits to tags, " +
             "areas, and checklist items do not mark the containing item as modified. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             since: z.string().describe("ISO date-time, e.g. 2026-07-06T08:00:00"),
             ...limitShape,
@@ -849,26 +870,34 @@ export function createThingsMcpServer(options = {}) {
             limit,
             ...(args.tz !== undefined && { zone: args.tz }),
         });
-        return truncatedResult(shapeReadPayload("changes", items, args.full === true), truncation);
+        return truncatedResult(shapeReadPayload("changes", items, args.full === true, getClient().refPromoter()), truncation);
     }, args.tz));
     server.registerTool("get_item", {
         description: "Full detail for one item by uuid: notes, schedule, reminder, deadline, tags " +
             "(direct and inherited), checklist with per-item state, repeat schedule, and its " +
             "project/area/heading. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: { uuid: z.string() },
         annotations: READ_ONLY,
     }, async (args) => readGuard(() => {
         const item = getClient().read.byUuid(args.uuid);
         return item === null
             ? errorResult({ code: "not-found", message: noUuidMatch("item", args.uuid) })
-            : readResult(shapeReadPayload("detail", item, false));
+            : readResult(shapeReadPayload("detail", item, false, getClient().refPromoter()));
     }));
     server.registerTool("get_project", {
-        description: "One project's full contents: metadata plus its to-dos grouped under their headings. " +
-            "The tag filters keep only the child to-dos matching by their own tags (a heading left " +
-            "with none is dropped). " +
-            OMIT_EMPTY_NOTE,
+        description: "One project's full contents: metadata, its live child to-dos as one flat list (items, " +
+            "in index order — each carrying its stage, when, and, when it lives under a heading, " +
+            "its heading ref), the heading catalog (headings — every heading in index order, " +
+            "carrying archived once archived), and its logged children (logbook, most recent " +
+            "first, each carrying its heading ref). Reconstruct a heading's members by filtering " +
+            "items (or logbook) on the heading ref. The tag filters keep only the child to-dos " +
+            "matching by their own tags (a heading left with none is dropped). " +
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             uuid: z.string().describe("Project uuid or unique name"),
             ...tagOnlyShape,
@@ -890,17 +919,19 @@ export function createThingsMcpServer(options = {}) {
             overdue: args.overdue === true,
             ...tagFilterFields(tagPresence(args)),
             ...(args.tz !== undefined && { zone: args.tz }),
-        }), args.full === true));
+        }), args.full === true, getClient().refPromoter()));
     }, args.tz));
     server.registerTool("get_area", {
-        description: "One area's contents: metadata plus its direct to-dos (active first), its " +
-            "projects in canonical order, and later (scheduled/repeating/someday). The area " +
-            "logbook is not returned here — read it with read_view logbook + area; trashed " +
-            "rows live in read_view trash. " +
-            `The project-rows and direct-to-dos sections are capped at ${AREA_PREVIEW_LIMIT} each ` +
+        description: "One area's contents: metadata plus its direct to-dos as one flat list (items, in " +
+            "index order — each row carrying its stage and when) and its projects in canonical " +
+            "order (projects). The area logbook is not returned here — read it with read_view " +
+            "logbook + area; trashed rows live in read_view trash. " +
+            `The project rows and the open/current direct to-dos are capped at ${AREA_PREVIEW_LIMIT} each ` +
             "by default (project_limit / area_limit adjust them; all: true lifts both); the " +
             "second result block reports the counts. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             ref: z.string().describe("Area uuid or unique name"),
             ...tagOnlyShape,
@@ -949,14 +980,16 @@ export function createThingsMcpServer(options = {}) {
                 projectLimit,
             });
             areaNotice = notice;
-            return groupedResult(shapeReadPayload("area-view", view, args.full === true), truncation);
+            return groupedResult(shapeReadPayload("area-view", view, args.full === true, getClient().refPromoter()), truncation);
         }, args.tz, undefined, () => (areaNotice !== undefined ? [areaNotice] : undefined));
     });
     server.registerTool("list_collections", {
         description: "List every project, area, or tag (tags include their parent-tag nesting). Use to " +
             "refresh the inventory summarized in the server instructions. The tag filters scope " +
             "the projects list by each project's own tags (areas/tags reject them). " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             kind: z.enum(["projects", "areas", "tags"]),
             ...tagOnlyShape,
@@ -1001,7 +1034,7 @@ export function createThingsMcpServer(options = {}) {
             })
             : args.kind === "areas"
                 ? c.read.areas()
-                : c.read.tags(), args.full === true));
+                : c.read.tags(), args.full === true, c.refPromoter()));
     }, args.tz));
     // ---------------------------------------------------------------- to-dos
     const whenSchema = z.string().optional().describe(WHEN_VALUES);
@@ -2116,7 +2149,9 @@ export function createThingsMcpServer(options = {}) {
             "position the block instead. Refs that span different containers or buckets are refused. " +
             "A Today or This Evening member also holds a slot in its own container, so a set that is " +
             "coherent on BOTH axes is ambiguous — pass `in` to name the axis (the refusal names both " +
-            "choices). The project rows the Today/Evening/day lists intermix with to-dos may be " +
+            "choices). A deadline-forecast set sharing one Upcoming day is dual-axis the same way (the " +
+            "day-block vs its container order); `in: upcoming` or `in: <YYYY-MM-DD>` names the day-block. " +
+            "The project rows the Today/Evening/day lists intermix with to-dos may be " +
             "reordered alongside them. Ordering the Today, Inbox, or Someday lists, a project's " +
             "to-dos, or an area must first be enabled once via `things config set allow-experimental " +
             "true`. To reorder a project's HEADINGS (children follow) use the heading tool's " +
@@ -2129,8 +2164,12 @@ export function createThingsMcpServer(options = {}) {
             in: z
                 .string()
                 .optional()
-                .describe("Disambiguate the axis of a Today/This Evening set: today | evening | anytime | " +
-                "someday | inbox, or a project/area/heading ref (uuid or unique title)"),
+                .describe("Name the axis to reorder on: today | evening | anytime | someday | inbox, a project/" +
+                "area/heading ref (uuid or unique title), upcoming (the one future day the set " +
+                "shares), or a YYYY-MM-DD day-block. A stage-list or container axis sorts one KIND " +
+                "at a time — a mixed to-do+project set is refused (even sharing a container); only " +
+                "today | evening | upcoming | a day-block intermix both kinds. Reorder a project's " +
+                "headings with the heading tool's move_heading action."),
             ...dryRunShape,
         },
         annotations: NON_DESTRUCTIVE,