tidee-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tidee Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# tidee-life-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for tidee. It lets an
+assistant add items to your workspace, read what is there, and mark
+things done — without you switching to the app to write it down.
+
+## Which one do you want?
+
+There are two ways to connect, and most people want the hosted one.
+
+**Hosted** — point your client at `https://app.tidee.com/mcp`. Nothing to
+install, and no token to copy: your client registers itself, tidee asks
+you to approve it in the browser, and that is the whole setup. In Claude
+Code that is one line:
+
+```sh
+claude mcp add --transport http tidee https://app.tidee.com/mcp
+```
+
+**This package** — a local server over stdio, for clients that do not
+speak HTTP MCP, or when you want to point at a development server. It
+needs Node and a token you paste into a config file.
+
+## Setup
+
+1. In tidee, open **Application Settings → Integrations** and create a
+   token. Give it only the access the assistant needs:
+
+   | Access | Tools it enables |
+   |---|---|
+   | Add new items | `capture`, `create_item` |
+   | Read items | `list_boxes`, `list_items` |
+   | Edit and complete existing items | `complete_item` |
+
+   The token is shown once. Copy it then.
+
+2. Add the server to your MCP client's config:
+
+   ```json
+   {
+     "mcpServers": {
+       "tidee": {
+         "command": "npx",
+         "args": ["-y", "tidee-mcp"],
+         "env": { "TIDEE_API_TOKEN": "tdl_…" }
+       }
+     }
+   }
+   ```
+
+3. Restart the client.
+
+## Environment
+
+| Variable | Required | Default |
+|---|---|---|
+| `TIDEE_API_TOKEN` | yes | — |
+| `TIDEE_API_URL` | no | `https://app.tidee.com` |
+
+`TIDEE_API_URL` exists for pointing at a local server during
+development. Leave it unset otherwise.
+
+## Building
+
+```sh
+pnpm run build
+```
+
+Type-checks, then bundles to a single `dist/index.js` with esbuild.
+
+The bundling is not an optimisation. The tool definitions — names,
+schemas, descriptions, and the sentences returned to the model — live in
+`tidee-life-core/mcp`, shared with the hosted server so the two cannot
+drift. That is a private workspace package, so it cannot be a dependency
+of anything published; inlining it means what ships depends only on
+`@modelcontextprotocol/sdk` and `zod`, while there is still exactly one
+definition of the tools.
+
+## Tools
+
+- **`capture`** — the one to reach for. Takes a whole thought in ordinary
+  language and lets tidee work out the separate items, which box each
+  belongs in, and any dates. "Book the MOT and call Sam about Friday"
+  becomes two items, filed.
+- **`create_item`** — one item with an exact title, for when the wording
+  is already decided.
+- **`list_boxes`** — the boxes items are filed in, with their ids.
+- **`list_items`** — read or search items.
+- **`complete_item`** — mark one done.
+
+## Notes
+
+Every tool is a single call to tidee's public API. Planning, filing and
+the never-lose fallback all happen server-side, which is why this server
+holds no logic worth configuring: it is a client, not a second copy of
+the app.
+
+A capture that cannot be interpreted is never discarded — it is stored
+verbatim as one item, and the tool says so.
+
+Captures made through this server count towards the account's capture
+allowance, exactly as they would in the app.
+
+If a token is revoked or expires the tools stop working immediately and
+say why. Create a new one in Settings and update the config.

package/dist/index.js

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// ../tidee-life-core/dist/src/mcp/tools.js
+import { z } from "zod";
+
+// ../tidee-life-config/dist/src/item-types.js
+var ITEM_TYPES = {
+  search: {
+    icon: null,
+    name: "search",
+    label: "Search",
+    isPrimary: false
+  },
+  todoBox: {
+    icon: "tidee-box",
+    name: "todoBox",
+    label: "Box",
+    isPrimary: true
+  },
+  todoText: {
+    icon: null,
+    name: "todoText",
+    label: "Text",
+    isPrimary: true
+  }
+};
+
+// ../tidee-life-config/dist/src/api-token.js
+var API_TOKEN_SCOPES = {
+  /** Create items from free text through the capture service. */
+  capture: "capture",
+  /** Read items, boxes and the workspace. */
+  itemsRead: "items:read",
+  /** Create, edit, complete and move items. */
+  itemsWrite: "items:write"
+};
+var ALL_API_TOKEN_SCOPES = Object.values(API_TOKEN_SCOPES);
+var KNOWN_SCOPES = new Set(ALL_API_TOKEN_SCOPES);
+var API_TOKEN_EXPIRY_OPTION_DAYS = [90, 365, null];
+var KNOWN_EXPIRY_DAYS = new Set(API_TOKEN_EXPIRY_OPTION_DAYS);
+
+// ../tidee-life-config/dist/src/capture-source.js
+var CAPTURE_SOURCE = {
+  /** Quick Capture manual mode — user typed a title. */
+  manual: "manual",
+  /** Quick Capture AI mode — dictated, planned, and reviewed before commit. */
+  ai: "ai",
+  /** Inline add on a pane row or mobile screen. */
+  inline: "inline",
+  /**
+   * Dictated and committed WITHOUT the user seeing the plan. The only
+   * source that starts life unreviewed, and the only one that stores a
+   * transcript. Surfaced afterwards in the capture review strip.
+   */
+  eyesFree: "eyesFree",
+  /**
+   * Phase 4 — arrived from Slack (`/tidee`, an `@tidee` mention, or the
+   * message shortcut). Counted: Slack is a Free-tier feature precisely
+   * because its captures count. Free plus uncounted would be an
+   * unlimited capture path around the 50.
+   */
+  slack: "slack",
+  /**
+   * Phase 4 — arrived through the MCP server or the public API. Counted:
+   * an MCP `capture` runs the same planner at the same cost as an in-app
+   * AI capture, and a literal `create_item` is still an item the user now
+   * has. Exempting either would make the cap bypassable by anyone willing
+   * to install a config file.
+   */
+  mcp: "mcp"
+};
+var COUNTED_CAPTURE_SOURCES = [
+  CAPTURE_SOURCE.manual,
+  CAPTURE_SOURCE.ai,
+  CAPTURE_SOURCE.inline,
+  CAPTURE_SOURCE.eyesFree,
+  CAPTURE_SOURCE.slack,
+  CAPTURE_SOURCE.mcp
+];
+var KNOWN_CAPTURE_SOURCES = new Set(Object.values(CAPTURE_SOURCE));
+
+// ../tidee-life-config/dist/src/item-ownership.js
+var ITEM_OWNERSHIP = {
+  owner: {
+    id: "owner",
+    name: "item.ownership.owner.text",
+    capabilities: [6, 1, 2, 3, 4, 5, 7, 8]
+  },
+  editor: {
+    id: "editor",
+    name: "item.ownership.editor.text",
+    capabilities: [6, 1, 2]
+  },
+  readonly: {
+    id: "readonly",
+    name: "item.ownership.readonly.text",
+    capabilities: [6]
+  }
+};
+var ITEM_OWNERSHIP_CAPABILITIES = {
+  1: {
+    category: 1,
+    desc: "item.ownership.capability.1"
+  },
+  2: {
+    category: 2,
+    desc: "item.ownership.capability.2"
+  },
+  3: {
+    category: 1,
+    desc: "item.ownership.capability.3"
+  },
+  4: {
+    category: 1,
+    desc: "item.ownership.capability.4"
+  },
+  5: {
+    category: 1,
+    desc: "item.ownership.capability.5"
+  },
+  6: {
+    category: 1,
+    desc: "item.ownership.capability.6"
+  },
+  7: {
+    category: 1,
+    desc: "item.ownership.capability.7"
+  },
+  8: {
+    category: 1,
+    desc: "item.ownership.capability.8"
+  }
+};
+var ITEM_OWNERSHIP_OPTIONS = Object.keys(ITEM_OWNERSHIP).map((ownershipId) => ({
+  label: ITEM_OWNERSHIP[ownershipId].name,
+  value: ITEM_OWNERSHIP[ownershipId].id
+}));
+var ITEM_OWNERSHIP_CAPABILITY_LOOKUP = Object.keys(ITEM_OWNERSHIP).reduce((all, current) => {
+  const capabilityDescs = ITEM_OWNERSHIP[current].capabilities.map((capabilityId) => ITEM_OWNERSHIP_CAPABILITIES[capabilityId].desc);
+  return {
+    ...all,
+    [current]: capabilityDescs
+  };
+}, {});
+var DEFAULT_ITEM_OWNERSHIP = ITEM_OWNERSHIP.readonly.id;
+
+// ../tidee-life-config/dist/src/organisation-ownership.js
+var ORGANISATION_OWNERSHIP_CAPABILITIES = {
+  1: {
+    category: 1,
+    desc: "organisations.modal.organisation.ownership.capability.1"
+  },
+  2: {
+    category: 2,
+    desc: "organisations.modal.organisation.ownership.capability.2"
+  },
+  4: {
+    category: 4,
+    desc: "organisations.modal.organisation.ownership.capability.4"
+  },
+  5: {
+    category: 5,
+    desc: "organisations.modal.organisation.ownership.capability.5"
+  },
+  // Phase 3 slice N — admins can transfer ownership of items
+  // in the org, even ones they don't own themselves (the
+  // offboarding path). Enforced server-side by transferItem
+  // Ownership; owner-only sharing still holds.
+  6: {
+    category: 6,
+    desc: "organisations.modal.organisation.ownership.capability.6"
+  }
+};
+var ORGANISATION_OWNERSHIP_TYPES = {
+  admin: {
+    id: "admin",
+    name: "organisation.ownership.administrator.text",
+    capabilities: [1, 2, 4, 5, 6]
+  },
+  member: {
+    id: "member",
+    name: "organisation.ownership.member.text",
+    capabilities: []
+  }
+};
+var ORGANISATION_OWNERSHIP_OPTIONS = Object.keys(ORGANISATION_OWNERSHIP_TYPES).map((ownershipId) => ({
+  label: ORGANISATION_OWNERSHIP_TYPES[ownershipId].name,
+  value: ORGANISATION_OWNERSHIP_TYPES[ownershipId].id
+}));
+var ORGANISATION_OWNERSHIP_CAPABILITY_LOOKUP = Object.keys(ORGANISATION_OWNERSHIP_TYPES).reduce((all, current) => {
+  const capabilityDescs = ORGANISATION_OWNERSHIP_TYPES[current].capabilities.map((capabilityId) => ORGANISATION_OWNERSHIP_CAPABILITIES[capabilityId].desc);
+  return {
+    ...all,
+    [current]: capabilityDescs
+  };
+}, { admin: [], member: [] });
+
+// ../tidee-life-config/dist/src/oauth.js
+var OAUTH_ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
+var OAUTH_REFRESH_TOKEN_TTL_SECONDS = 60 * 60 * 24 * 60;
+var OAUTH_REGISTRATION_WINDOW_MS = 60 * 60 * 1e3;
+
+// ../tidee-life-config/dist/src/index.js
+var ALLOWED_PRIORITIZABLE_TYPES = [ITEM_TYPES.todoText.name];
+
+// ../tidee-life-core/dist/src/mcp/tools.js
+var describeToolError = (failure) => {
+  const { code, status, message } = failure ?? {};
+  if (code === "error.free.tier.capture.limit") {
+    return "This tidee account has used all its free captures. The item was not saved. Upgrading in tidee removes the limit.";
+  }
+  if (code === "error.api.token.scope.missing") {
+    return "This tidee token is not permitted to do that. Create a token with the needed access in Application Settings \u2192 Integrations.";
+  }
+  if (status === 401) {
+    return "This tidee token is not valid \u2014 it may have been revoked or expired. Create a new one in Application Settings \u2192 Integrations.";
+  }
+  if (code)
+    return code;
+  if (status)
+    return `tidee returned ${status}.`;
+  return message || "The request to tidee failed.";
+};
+var tool = (spec) => spec;
+var TIDEE_TOOLS = [
+  tool({
+    name: "capture",
+    title: "Capture into tidee",
+    scope: API_TOKEN_SCOPES.capture,
+    // Written to be CHOSEN correctly rather than to document an
+    // endpoint. The failure mode this description exists to prevent
+    // is an assistant looping create_item once per sentence.
+    description: 'Add one or more items to the user\u2019s tidee workspace from ordinary language. Give it the whole thought as the user said it \u2014 "book the MOT and call Sam about Friday" \u2014 and tidee works out the separate items, which box each belongs in, and any dates. It REWORDS as it files: "get some milk tomorrow" becomes an item called "milk" with a date. That is wanted when the user is thinking aloud, and wrong when they have chosen their words \u2014 if they quoted a title, use create_item instead. Nothing is ever lost: if the text cannot be interpreted it is stored verbatim as a single item.',
+    inputSchema: {
+      text: z.string().describe("What the user wants to remember, in their own words."),
+      parentId: z.string().optional().describe("Box id to put everything in. Omit to let tidee choose, which is usually right. Ids come from list_boxes.")
+    },
+    async run(api2, { text, parentId }) {
+      const data = await api2.capture({ text, parentId });
+      const titles = (data.created ?? []).map((c) => c.title);
+      if (titles.length === 0)
+        return "Nothing was created.";
+      const quoted = titles.map((t) => `"${t}"`).join(", ");
+      if (data.usedFallback) {
+        return `Saved as one item: ${quoted}. tidee could not split that into separate items, so it kept the text as given.`;
+      }
+      return `Added ${titles.length} item(s) to tidee: ${quoted}`;
+    }
+  }),
+  tool({
+    name: "create_item",
+    title: "Create one tidee item",
+    scope: API_TOKEN_SCOPES.itemsWrite,
+    description: 'Add a single item with an exact title, optionally with a date. The title is stored EXACTLY as given \u2014 nothing rewrites or shortens it. Use this whenever the user has settled on wording: they put it in quotes, they dictated it, or you are copying something verbatim. Quotation marks in particular mean "these words" \u2014 use this tool and pass what is inside them, and put any date in targetDate rather than leaving it in the title. Use capture instead only when the user is talking loosely and wants tidee to work out the wording, the boxes and the dates for them.',
+    inputSchema: {
+      title: z.string().describe("The item title, used exactly as given."),
+      parentId: z.string().optional().describe("Box id to file it in. Ids come from list_boxes."),
+      targetDate: z.string().optional().describe('When the user should DO this, as local time with no timezone: "2026-09-10T09:00:00". Not the date of an event the task is merely about \u2014 "book a table for the 14th" needs doing before the 14th, so leave it out and let the user choose. Default to 09:00 when no time was given. Omit when no date was mentioned.')
+    },
+    async run(api2, { title, parentId, targetDate }) {
+      await api2.createItem({ title, parentId, targetDate });
+      if (targetDate) {
+        const day = String(targetDate).slice(0, 10);
+        return `Added "${title}" to tidee, for ${day}.`;
+      }
+      return `Added "${title}" to tidee.`;
+    }
+  }),
+  tool({
+    name: "list_boxes",
+    title: "List tidee boxes",
+    scope: API_TOKEN_SCOPES.itemsRead,
+    description: "The user\u2019s boxes \u2014 the containers items are filed in. Call this when you need a box id for capture or create_item, or when the user asks what they have.",
+    inputSchema: {},
+    async run(api2) {
+      const data = await api2.listBoxes();
+      const boxes = data.boxes ?? [];
+      if (boxes.length === 0)
+        return "This workspace has no boxes yet.";
+      return boxes.map((b) => `${b.name} (id: ${b.id})`).join("\n");
+    }
+  }),
+  tool({
+    name: "list_items",
+    title: "List or search tidee items",
+    scope: API_TOKEN_SCOPES.itemsRead,
+    description: "Read items from the workspace. Narrow with q to search titles, or parentId to look inside one box. Use this before completing something, to find the item\u2019s id.",
+    inputSchema: {
+      q: z.string().optional().describe("Search text matched against titles."),
+      parentId: z.string().optional().describe("Only items inside this box."),
+      limit: z.number().optional().describe("How many to return. Defaults to 50, capped at 200.")
+    },
+    async run(api2, { q, parentId, limit }) {
+      const data = await api2.listItems({ q, parentId, limit });
+      const items = data.items ?? [];
+      if (items.length === 0)
+        return "No matching items.";
+      return items.map((i) => {
+        const due = i.targetDate ? ` \u2014 due ${String(i.targetDate).slice(0, 10)}` : "";
+        return `${i.completed ? "[done] " : ""}${i.title} (id: ${i.id})${due}`;
+      }).join("\n");
+    }
+  }),
+  tool({
+    name: "complete_item",
+    title: "Complete a tidee item",
+    scope: API_TOKEN_SCOPES.itemsWrite,
+    description: "Mark an item done. Needs the item\u2019s id, which comes from list_items \u2014 find the item first rather than guessing an id.",
+    inputSchema: {
+      id: z.string().describe("The item id, as returned by list_items.")
+    },
+    async run(api2, { id }) {
+      await api2.completeItem({ id });
+      return "Marked complete in tidee.";
+    }
+  })
+];
+
+// src/index.ts
+var API_URL = (process.env.TIDEE_API_URL || "https://app.tidee.com").replace(
+  /\/+$/,
+  ""
+);
+var API_TOKEN = process.env.TIDEE_API_TOKEN;
+if (!API_TOKEN) {
+  process.stderr.write(
+    "tidee-mcp: TIDEE_API_TOKEN is not set. Create a token in tidee under Application Settings \u2192 Integrations, then set it in this server\u2019s environment.\n"
+  );
+  process.exit(1);
+}
+var HttpApiError = class extends Error {
+  code;
+  status;
+  constructor(status, code) {
+    super(code || `tidee returned ${status}`);
+    this.status = status;
+    this.code = code;
+  }
+};
+var call = async (path, init) => {
+  const url = new URL(`${API_URL}${path}`);
+  for (const [key, value] of Object.entries(init.query ?? {})) {
+    if (value !== void 0 && value !== "") {
+      url.searchParams.set(key, value);
+    }
+  }
+  let response;
+  try {
+    response = await fetch(url, {
+      method: init.method,
+      headers: {
+        Authorization: `Bearer ${API_TOKEN}`,
+        "Content-Type": "application/json"
+      },
+      body: init.body === void 0 ? void 0 : JSON.stringify(init.body)
+    });
+  } catch (error) {
+    throw new Error(
+      `Could not reach tidee at ${API_URL}. ${error?.message ?? ""}`.trim(),
+      { cause: error }
+    );
+  }
+  const body = await response.json().catch(() => null);
+  if (!response.ok) {
+    const code = body?.error?.code;
+    throw new HttpApiError(response.status, code);
+  }
+  return body;
+};
+var api = {
+  capture: ({ text, parentId }) => call("/api/v1/capture", {
+    method: "POST",
+    body: { text, parentId }
+  }),
+  createItem: ({ title, parentId, targetDate }) => call("/api/v1/items", {
+    method: "POST",
+    body: { title, parentId, targetDate }
+  }),
+  listBoxes: () => call("/api/v1/boxes", { method: "GET" }),
+  listItems: ({ q, parentId, limit }) => call("/api/v1/items", {
+    method: "GET",
+    query: {
+      ...q ? { q } : {},
+      ...parentId ? { parentId } : {},
+      ...limit ? { limit: String(limit) } : {}
+    }
+  }),
+  completeItem: ({ id }) => call(`/api/v1/items/${encodeURIComponent(id)}`, {
+    method: "PATCH",
+    body: { completed: true }
+  })
+};
+var server = new McpServer({ name: "tidee", version: "1.0.0" });
+for (const spec of TIDEE_TOOLS) {
+  server.registerTool(
+    spec.name,
+    {
+      title: spec.title,
+      description: spec.description,
+      inputSchema: spec.inputSchema
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async (args) => {
+      try {
+        return {
+          content: [
+            {
+              type: "text",
+              text: await spec.run(api, args)
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: describeToolError(
+                error
+              )
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "tidee-mcp",
+	"version": "1.0.0",
+	"description": "MCP server for tidee — let an assistant add items to your workspace, read what is there, and mark things done.",
+	"keywords": [
+		"mcp",
+		"modelcontextprotocol",
+		"tidee",
+		"todo",
+		"ai",
+		"assistant"
+	],
+	"license": "MIT",
+	"author": "tidee Ltd",
+	"homepage": "https://www.tidee.com",
+	"repository": {
+		"type": "git",
+		"url": "git+https://gitlab.com/joetidee/tidee-life.git",
+		"directory": "packages/tidee-life-mcp"
+	},
+	"bugs": {
+		"url": "https://www.tidee.com/en/contact"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"bin": {
+		"tidee-mcp": "dist/index.js"
+	},
+	"files": [
+		"dist/index.js",
+		"README.md",
+		"LICENSE"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "rm -rf dist && tsc --noEmit && esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --external:@modelcontextprotocol/sdk --external:zod --outfile=dist/index.js",
+		"lint": "eslint ./src"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "1.27.1",
+		"zod": "^3.25.76"
+	},
+	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"@types/node": "^22.16.0",
+		"esbuild": "^0.28.2",
+		"eslint": "^9.21.0",
+		"globals": "^17.4.0",
+		"tidee-life-core": "workspace:1.0.0",
+		"typescript": "^5.8.3",
+		"typescript-eslint": "^8.56.1"
+	}
+}