taskswipe-mcp 0.1.0

package/README.md

@@ -0,0 +1,175 @@
+# taskswipe-mcp
+
+Your TASK//SWIPE day, from inside Claude Code, Claude Desktop, Codex or Cursor.
+
+```
+you: add "call the bank" and "book the dentist" to today
+you: what's on today?
+you: tick off the bank one
+```
+
+## Two ways to connect
+
+**Hosted (nothing to install)** — point any remote-MCP client at:
+
+```
+https://swipe-todo-react.vercel.app/mcp
+```
+
+with your token as `Authorization: Bearer <TASKSWIPE_ACCESS_TOKEN>`. Stateless
+Streamable HTTP, POST-only. Discovery (`initialize`, `tools/list`) is open;
+every `tools/call` requires the token and runs scoped to that user, so
+row-level security still applies and no service key exists anywhere.
+
+**Local (stdio)** — the rest of this file. Still the right choice when you want
+the server reading credentials from your own machine rather than sending a
+token over the wire.
+
+## Setup
+
+You need your TASK//SWIPE login token — that's it. The production Supabase URL
+and anon key are baked in as defaults (they're public — they ship in the web
+app's JS bundle); self-hosters can override them with `TASKSWIPE_SUPABASE_URL`
+and `TASKSWIPE_SUPABASE_ANON_KEY`.
+
+> **Not on npm yet.** Until `taskswipe-mcp` is published, every client below
+> runs it from this repo by path:
+> `node ~/Developer/swipe-todo-react/mcp/src/index.js`
+> Once it's published, replace that with `npx -y taskswipe-mcp` everywhere.
+
+**Claude Code**
+
+```bash
+claude mcp add taskswipe \
+  -e TASKSWIPE_SUPABASE_URL=https://xxxx.supabase.co \
+  -e TASKSWIPE_SUPABASE_ANON_KEY=eyJ... \
+  -e TASKSWIPE_ACCESS_TOKEN=eyJ... \
+  -- node ~/Developer/swipe-todo-react/mcp/src/index.js
+```
+
+**Codex CLI** — Codex does **not** read the JSON `mcpServers` shape. It has its
+own TOML config at `~/.codex/config.toml`. Either run:
+
+```bash
+codex mcp add taskswipe \
+  --env TASKSWIPE_SUPABASE_URL=https://xxxx.supabase.co \
+  --env TASKSWIPE_SUPABASE_ANON_KEY=eyJ... \
+  --env TASKSWIPE_ACCESS_TOKEN=eyJ... \
+  -- node ~/Developer/swipe-todo-react/mcp/src/index.js
+```
+
+or add the section by hand:
+
+```toml
+[mcp_servers.taskswipe]
+command = "node"
+args = ["/Users/you/Developer/swipe-todo-react/mcp/src/index.js"]
+
+[mcp_servers.taskswipe.env]
+TASKSWIPE_SUPABASE_URL = "https://xxxx.supabase.co"
+TASKSWIPE_SUPABASE_ANON_KEY = "eyJ..."
+TASKSWIPE_ACCESS_TOKEN = "eyJ..."
+```
+
+(`codex mcp list` to confirm it registered; note the section is
+`mcp_servers`, snake_case, not `mcpServers`.)
+
+**Claude Desktop / Cursor** — these do use the JSON shape
+(`claude_desktop_config.json` / `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "taskswipe": {
+      "command": "node",
+      "args": ["/Users/you/Developer/swipe-todo-react/mcp/src/index.js"],
+      "env": {
+        "TASKSWIPE_SUPABASE_URL": "https://xxxx.supabase.co",
+        "TASKSWIPE_SUPABASE_ANON_KEY": "eyJ...",
+        "TASKSWIPE_ACCESS_TOKEN": "eyJ..."
+      }
+    }
+  }
+}
+```
+
+### Getting an access token
+
+Sign in to TASK//SWIPE in a browser, open the console, and run:
+
+```js
+JSON.parse(Object.entries(localStorage).find(([k]) => k.includes('auth-token'))[1]).access_token
+```
+
+It expires on its own, which is the point — a leaked token stops working.
+
+### Making it permanent
+
+Add `TASKSWIPE_REFRESH_TOKEN` next to it — same console snippet, ending in
+`.refresh_token` instead of `.access_token`. With the pair in place the server
+renews itself and keeps the CURRENT session in `~/.taskswipe-mcp-session.json`
+(owner-only file). That file matters: Supabase rotates refresh tokens on every
+use and treats reuse of an old one as theft, so the config values are only the
+seed — after first run the file is the live credential. Signing out of that
+session (or deleting the file AND pasting a fresh pair) is the reset path.
+
+### Password fallback
+
+`TASKSWIPE_EMAIL` + `TASKSWIPE_PASSWORD` also work, and the server prefers a
+token whenever both are present. Understand the trade before using it: MCP
+config files sit unencrypted in your home directory, are frequently committed
+by accident, and are read by every tool on the machine. A password there is a
+permanent credential for your whole account — it does not expire, and rotating
+it means changing it everywhere. The server prints a warning to stderr when it
+signs in this way.
+
+## Codex marketplace
+
+The repo root carries `.codex-plugin/plugin.json` + `.mcp.json`, which makes
+the whole repo an installable Codex plugin. The path to being listed
+(as of 2026-08):
+
+1. **Publish `taskswipe-mcp` to npm** — the plugin manifest runs
+   `npx -y taskswipe-mcp`, which is dead until the package exists.
+   `cd mcp && npm publish --access public` under an npm account.
+2. **Interim listing** — submit the GitHub repo URL to the community registry
+   at codex-marketplace.com (automated review of the manifest).
+3. **Official directory** — OpenAI's self-serve publishing is "coming soon";
+   until then it's a manual submission portal and requires identity
+   verification (individual or business) first.
+
+Users who install it set only `TASKSWIPE_ACCESS_TOKEN` (+
+`TASKSWIPE_REFRESH_TOKEN` to make it permanent) in their own config.
+
+## Tools
+
+| Tool | Does |
+|---|---|
+| `today` | Today's open/done tasks, core task, day score |
+| `add_tasks` | Add up to 10 tasks at once, skipping duplicates |
+| `complete_task` | Tick one off by any part of its text |
+| `capture` | Park an idea (not a task) |
+| `set_core_task` | Set the one thing that matters today |
+| `search` | Across tasks, ideas, journal, lists, backlog |
+
+## What it deliberately cannot do
+
+- **Nothing destructive.** No delete, no clear, no reset. The worst a wrong
+  call can do is add a task you remove or tick one you untick.
+- **10 writes per call, maximum**, and anything over the limit is reported
+  rather than silently dropped.
+- **Everything it writes is tagged `source: 'mcp'`**, so the app can show what
+  came from an assistant.
+
+## Concurrency
+
+The app stores everything as one JSON blob. Two writers means the last one
+wins and silently discards the other's work, so every write here is conditional
+on the row not having changed since it was read — a stale write re-reads and
+re-applies rather than overwriting. See `src/store.js`.
+
+## Security
+
+Your credentials stay on your machine and are used to sign in as *you*, so
+Supabase row-level security still applies — this server can only ever touch
+your own row. No service key, and nothing is proxied through a third party.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "taskswipe-mcp",
+  "version": "0.1.0",
+  "description": "Read and write your TASK//SWIPE day from Claude Code, Claude Desktop, Codex or Cursor.",
+  "type": "module",
+  "bin": {
+    "taskswipe-mcp": "src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@supabase/supabase-js": "^2.45.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// ─────────────────────────────────────────────────────────────────────────────
+// TASK//SWIPE MCP SERVER — stdio transport.
+//
+// Transport is deliberately the only thing in this file. Tools live in
+// tools.js and know nothing about MCP; state access lives in store.js and
+// knows nothing about tools. When the hosted HTTP transport lands (Phase 3 of
+// docs/MCP-STRATEGY.md) it replaces this file alone.
+//
+// stdio has one rule that bites everyone once: STDOUT IS THE PROTOCOL. A stray
+// console.log corrupts the JSON-RPC stream and the client disconnects with a
+// parse error that points nowhere near the cause. Everything diagnostic goes
+// to stderr.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+import { TOOLS, byName } from './tools.js'
+
+const log = (...a) => process.stderr.write(a.join(' ') + '\n')
+
+const server = new Server(
+  { name: 'taskswipe', version: '0.1.0' },
+  { capabilities: { tools: {} } },
+)
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map(t => ({
+    name: t.name,
+    title: t.title,
+    description: t.description,
+    inputSchema: t.inputSchema,
+  })),
+}))
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = byName[req.params.name]
+  if (!tool) {
+    return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }] }
+  }
+  try {
+    const result = await tool.run(req.params.arguments || {})
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
+  } catch (e) {
+    // Returned as a tool error rather than thrown: the model can read it and
+    // tell the user what to fix, instead of the client showing "server error".
+    log(`[taskswipe] ${tool.name} failed:`, e?.message || e)
+    return {
+      isError: true,
+      content: [{ type: 'text', text: `TASK//SWIPE: ${e?.message || 'unknown error'}` }],
+    }
+  }
+})
+
+const transport = new StdioServerTransport()
+await server.connect(transport)
+log('[taskswipe] MCP server ready on stdio —', TOOLS.length, 'tools')

package/src/store.js

@@ -0,0 +1,257 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// STATE ACCESS — read/modify/write the one JSONB blob, safely.
+//
+// TASK//SWIPE keeps everything in a single `user_states.state` row, upserted
+// whole. With one writer that is fine. MCP adds a SECOND writer, and a plain
+// upsert means last-write-wins — the web app saves, we save a moment later
+// from a stale read, and everything it just did is silently gone.
+//
+// So every write here is conditional on the `updated_at` we read. If the row
+// moved underneath us the update matches zero rows, and we re-read and re-apply
+// rather than overwrite. Three attempts, then an honest error instead of quiet
+// data loss.
+//
+// (This same race already exists between two browser tabs. The lock below only
+// protects writes made through MCP; fixing the app side is tracked separately.)
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { createClient } from '@supabase/supabase-js'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+// ── REQUEST SCOPE ────────────────────────────────────────────────────────────
+// Locally this server is one process for one person, so a module-level client
+// and a cached user id are exactly right. Over HTTP the same code serves many
+// people, and those two module globals would leak one user's data to the next
+// request — the worst bug this file could possibly have.
+//
+// AsyncLocalStorage rather than a ctx argument threaded through every tool:
+// tools.js calls readState()/mutate() directly and shouldn't have to know
+// which transport it's running under. When a context is active it wins; with
+// none, the env-configured singleton below behaves exactly as before.
+const requestCtx = new AsyncLocalStorage()
+
+/** Run `fn` with an explicit Supabase client + user id (HTTP transport). */
+export const withRequestContext = (ctx, fn) => requestCtx.run(ctx, fn)
+
+const activeClient = () => requestCtx.getStore()?.supa || supa()
+const activeUserId = async () => requestCtx.getStore()?.userId || await userId()
+
+// TASKSWIPE_FAKE swaps the database for an in-memory blob. Used by the test
+// harness to drive the real protocol without real credentials; never set in
+// normal use, and it changes nothing about the code paths above it.
+const FAKE = process.env.TASKSWIPE_FAKE === '1'
+let fakeState = {}
+let fakeStamp = null
+
+const MAX_ATTEMPTS = 3
+
+let client = null
+let cachedUserId = null
+
+function env(name, fallback) {
+  const v = process.env[name] ?? fallback
+  if (!v) throw new Error(`Missing ${name}. See the README for setup.`)
+  return v
+}
+
+// The production project's URL and anon key. These are PUBLIC by design —
+// they ship inside the web app's JS bundle for every visitor — so baking them
+// in leaks nothing and means an installed plugin needs exactly one thing from
+// the user: their own token. Self-hosters override with the env vars.
+const DEFAULT_URL = 'https://pfwckeghmflerxrtvwpa.supabase.co'
+const DEFAULT_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InBmd2NrZWdobWZsZXJ4cnR2d3BhIiwicm9sZSI6ImFub24iLCJpYXQiOjE3Nzg4Njc0NzQsImV4cCI6MjA5NDQ0MzQ3NH0.lhj5zKJT4bR7hvnXQWQHfStm9r4BfrRQ6_LFcxOUJLk'
+
+export function supa() {
+  if (client) return client
+  client = createClient(
+    env('TASKSWIPE_SUPABASE_URL', DEFAULT_URL),
+    env('TASKSWIPE_SUPABASE_ANON_KEY', DEFAULT_ANON_KEY),
+    { auth: { persistSession: false, autoRefreshToken: false } },
+  )
+  return client
+}
+
+// ── SESSION PERSISTENCE ──────────────────────────────────────────────────────
+// An access token lives for an hour; a Supabase refresh token ROTATES every
+// time it's used, and reusing a rotated one revokes the whole session family.
+// So the pasted-into-config token pair is only ever the SEED: after the first
+// refresh, the current pair lives in this file and the env values are stale by
+// design. Delete the file to start over from the env seed.
+const SESSION_FILE = path.join(os.homedir(), '.taskswipe-mcp-session.json')
+
+function loadSavedSession() {
+  try {
+    const j = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf8'))
+    return j?.access_token && j?.refresh_token ? j : null
+  } catch { return null }
+}
+
+function saveSession(session) {
+  try {
+    fs.writeFileSync(
+      SESSION_FILE,
+      JSON.stringify({
+        access_token: session.access_token,
+        refresh_token: session.refresh_token,
+        expires_at: session.expires_at || null,
+      }),
+      { mode: 0o600 },   // it's a credential — owner-only, like an SSH key
+    )
+  } catch (e) {
+    console.error('[taskswipe] could not persist session:', e?.message)
+  }
+}
+
+const jwtExp = (token) => {
+  try { return JSON.parse(Buffer.from(token.split('.')[1], 'base64').toString()).exp || 0 }
+  catch { return 0 }
+}
+
+/**
+ * Make sure the session in `s` has more than 5 minutes left, refreshing and
+ * re-persisting if not. Re-reads the file first so two servers (Claude and
+ * Codex both running) pick up each other's rotations instead of burning a
+ * stale refresh token, which Supabase treats as theft and revokes everything.
+ */
+async function ensureFresh(s) {
+  const { data } = await s.auth.getSession()
+  let session = data?.session
+  if (session && jwtExp(session.access_token) - Date.now() / 1000 > 300) return
+
+  const saved = loadSavedSession()
+  const refresh = saved?.refresh_token || session?.refresh_token || process.env.TASKSWIPE_REFRESH_TOKEN
+  if (!refresh) return          // nothing to refresh with — ride the token out
+
+  const { data: r, error } = await s.auth.refreshSession({ refresh_token: refresh })
+  if (error || !r?.session) {
+    throw new Error(
+      'Session expired and the refresh failed'
+      + (error?.message ? ` (${error.message})` : '')
+      + '. Paste a fresh token pair into the config (see the README), and delete '
+      + SESSION_FILE + ' if it exists.',
+    )
+  }
+  saveSession(r.session)
+  cachedUserId = r.session.user?.id || cachedUserId
+}
+
+/**
+ * Sign in once with the user's own credentials and keep the session for the
+ * process lifetime. Deliberately their credentials, not a service key: the
+ * server then has exactly the access the user has, and RLS still applies.
+ */
+export async function userId() {
+  if (cachedUserId) { await ensureFresh(supa()); return cachedUserId }
+  const s = supa()
+
+  // The persisted session outranks the env seed — after the first rotation
+  // the env tokens are dead history and trying them first would revoke us.
+  const saved = loadSavedSession()
+  if (saved) {
+    const { data, error } = await s.auth.setSession(saved)
+    if (!error && data?.user) {
+      cachedUserId = data.user.id
+      if (data.session) saveSession(data.session)   // setSession may have rotated
+      await ensureFresh(s)
+      return cachedUserId
+    }
+    console.error('[taskswipe] saved session rejected — falling back to the env seed')
+  }
+
+  const token = process.env.TASKSWIPE_ACCESS_TOKEN
+  if (token) {
+    const refresh = process.env.TASKSWIPE_REFRESH_TOKEN || ''
+    if (refresh) {
+      // Full pair: hand it to setSession, which refreshes if the access token
+      // is already stale — so a config pasted yesterday still signs in today.
+      const { data, error } = await s.auth.setSession({ access_token: token, refresh_token: refresh })
+      if (error || !data?.user) {
+        throw new Error(`Could not start a session from the configured tokens${error?.message ? ` (${error.message})` : ''}. Paste a fresh pair — see the README.`)
+      }
+      if (data.session) saveSession(data.session)
+      cachedUserId = data.user.id
+      return cachedUserId
+    }
+    // Access token alone: works until it expires, and can't renew itself —
+    // said out loud so "it stopped after an hour" is a warning, not a mystery.
+    const { data, error } = await s.auth.getUser(token)
+    if (error || !data?.user) throw new Error('TASKSWIPE_ACCESS_TOKEN is not valid or has expired.')
+    await s.auth.setSession({ access_token: token, refresh_token: '' })
+    console.error('[taskswipe] No TASKSWIPE_REFRESH_TOKEN set — this session dies with the access token (~1h). Add the refresh token to make it permanent.')
+    cachedUserId = data.user.id
+    return cachedUserId
+  }
+
+  // A password in an MCP config is a non-expiring credential for the whole
+  // account, sitting in plaintext in a file that gets committed by accident all
+  // the time. It still works — but it should never be the silent default, so
+  // say so. stderr, never stdout: stdout is the protocol.
+  console.error(
+    '[taskswipe] Signing in with a stored password. Prefer TASKSWIPE_ACCESS_TOKEN — '
+    + 'it expires on its own. See the README.',
+  )
+
+  const email = env('TASKSWIPE_EMAIL')
+  const password = env('TASKSWIPE_PASSWORD')
+  const { data, error } = await s.auth.signInWithPassword({ email, password })
+  if (error || !data?.user) throw new Error(`Sign-in failed: ${error?.message || 'unknown error'}`)
+  if (data.session) saveSession(data.session)
+  cachedUserId = data.user.id
+  return cachedUserId
+}
+
+/** Current state plus the stamp a later write must match. */
+export async function readState() {
+  if (FAKE) return { state: fakeState, updatedAt: fakeStamp, userId: 'fake-user' }
+  const id = await activeUserId()
+  const { data, error } = await activeClient()
+    .from('user_states')
+    .select('state, updated_at')
+    .eq('user_id', id)
+    .maybeSingle()
+  if (error) throw new Error(`Could not read your data: ${error.message}`)
+  return { state: data?.state || {}, updatedAt: data?.updated_at || null, userId: id }
+}
+
+/**
+ * Apply `patch(state)` and save, retrying if someone else wrote first.
+ * `patch` must be pure and repeatable — it can be called more than once.
+ */
+export async function mutate(patch) {
+  if (FAKE) {
+    const next = patch(structuredClone(fakeState))
+    if (!next) return { changed: false, state: fakeState }
+    fakeState = next
+    fakeStamp = new Date().toISOString()
+    return { changed: true, state: next }
+  }
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    const { state, updatedAt, userId: id } = await readState()
+    const next = patch(structuredClone(state))
+    if (!next) return { changed: false, state }
+
+    const stamp = new Date().toISOString()
+    let q = activeClient().from('user_states')
+      .update({ state: next, updated_at: stamp })
+      .eq('user_id', id)
+
+    // The lock. A row whose updated_at moved is a row someone else wrote.
+    q = updatedAt ? q.eq('updated_at', updatedAt) : q.is('updated_at', null)
+
+    const { data, error } = await q.select('user_id')
+    if (error) throw new Error(`Could not save: ${error.message}`)
+    if (data && data.length) return { changed: true, state: next }
+
+    // No rows matched — either a concurrent write, or no row exists yet.
+    if (!updatedAt) {
+      const { error: insErr } = await activeClient().from('user_states')
+        .insert({ user_id: id, state: next, updated_at: stamp })
+      if (!insErr) return { changed: true, state: next }
+    }
+    // else: fall through and retry from a fresh read
+  }
+  throw new Error('Your data changed while saving, three times running. Nothing was written — try again.')
+}

package/src/tools.js

@@ -0,0 +1,242 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// TOOLS — shaped like the sentences people say, not like the database.
+//
+// The lazy design exposes get_state / set_state. That makes the model read a
+// few hundred KB to add one task, and hands it the whole blob to write back.
+// Every tool here takes a small payload and returns only what changed.
+//
+// Safety, deliberately baked in rather than prompted for:
+//   · nothing destructive — no delete, no clear, no reset. The worst a bad
+//     call can do is add a task you remove, or tick one you untick.
+//   · hard caps per call, so a model looping on a bad plan can't write 400 rows.
+//   · everything written carries source:'mcp' so the app can show it and you
+//     can undo a batch.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { readState, mutate } from './store.js'
+
+const MAX_ADD = 10
+const uid = () => Math.random().toString(36).slice(2, 11)
+const today = () => {
+  const d = new Date()
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+}
+
+const arr = (v) => (Array.isArray(v) ? v : [])
+
+/** Match a task the way a person refers to it: by substring, not by id. */
+function findTask(list, ref) {
+  const q = String(ref || '').trim().toLowerCase()
+  if (!q) return null
+  const open = list.filter(t => !t.done)
+  const pools = [open, list]
+  for (const pool of pools) {
+    const exact = pool.find(t => (t.text || '').toLowerCase() === q)
+    if (exact) return exact
+    const starts = pool.find(t => (t.text || '').toLowerCase().startsWith(q))
+    if (starts) return starts
+    const has = pool.filter(t => (t.text || '').toLowerCase().includes(q))
+    if (has.length === 1) return has[0]
+    if (has.length > 1) return { ambiguous: has.map(t => t.text) }
+  }
+  return null
+}
+
+export const TOOLS = [
+  {
+    name: 'today',
+    title: "Today's plan",
+    description:
+      "What TASK//SWIPE has for today: open and completed tasks, the core task, "
+      + "the day score if posted, and today's timed blocks. Call this before "
+      + "answering anything about what the user is doing today.",
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    async run() {
+      const { state } = await readState()
+      const tasks = arr(state.todayTasks)
+      const score = state.dayScores?.[today()]
+      return {
+        date: today(),
+        core_task: state.coreTask?.task || state.coreTask || null,
+        open: tasks.filter(t => !t.done).map(t => ({ text: t.text, at: t.at || null, category: t.category || null })),
+        done: tasks.filter(t => t.done).map(t => t.text),
+        day_score: score ? { score: score.score, of: 10 } : null,
+        counts: { open: tasks.filter(t => !t.done).length, done: tasks.filter(t => t.done).length },
+      }
+    },
+  },
+
+  {
+    name: 'add_tasks',
+    title: 'Add tasks to today',
+    description:
+      'Add one or more tasks to today\'s list. Batch them in a single call — '
+      + 'people add several at once. Maximum 10 per call. Skips exact duplicates.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tasks: {
+          type: 'array', minItems: 1, maxItems: MAX_ADD,
+          items: { type: 'string', minLength: 1, maxLength: 200 },
+          description: 'Task descriptions, as the user said them.',
+        },
+        category: {
+          type: 'string',
+          enum: ['work', 'health', 'admin', 'social', 'projects', 'personal', 'mindset', 'learning'],
+          description: 'Optional category for all of them.',
+        },
+      },
+      required: ['tasks'], additionalProperties: false,
+    },
+    async run({ tasks, category }) {
+      const all = tasks.map(t => String(t).trim()).filter(Boolean)
+      const wanted = all.slice(0, MAX_ADD)
+      // Silently dropping the overflow would have the model believe it added
+      // all twelve. Say what didn't make it so it can add the rest.
+      const dropped = all.slice(MAX_ADD)
+      let added = [], skipped = []
+      await mutate(state => {
+        const list = arr(state.todayTasks)
+        const have = new Set(list.map(t => (t.text || '').toLowerCase()))
+        const fresh = []
+        for (const text of wanted) {
+          if (have.has(text.toLowerCase())) { skipped.push(text); continue }
+          have.add(text.toLowerCase())
+          fresh.push({
+            id: uid(), text, done: false, createdDate: today(),
+            category: category || 'personal',
+            source: 'mcp',          // attributed, so the app can show + undo it
+          })
+        }
+        added = fresh.map(t => t.text)
+        if (!fresh.length) return null
+        return { ...state, todayTasks: [...list, ...fresh] }
+      })
+      return {
+        added, skipped,
+        not_added_over_limit: dropped,
+        message: `Added ${added.length} to today`
+          + (skipped.length ? `, skipped ${skipped.length} already there` : '')
+          + (dropped.length ? `. ${dropped.length} were over the ${MAX_ADD}-per-call limit and were NOT added — call again for those.` : '.'),
+      }
+    },
+  },
+
+  {
+    name: 'complete_task',
+    title: 'Tick a task off',
+    description:
+      'Mark a task on today\'s list as done. Refer to it however the user did — '
+      + 'a few words is enough, no id needed. Returns the exact task matched.',
+    inputSchema: {
+      type: 'object',
+      properties: { task: { type: 'string', minLength: 1, description: 'Any part of the task text.' } },
+      required: ['task'], additionalProperties: false,
+    },
+    async run({ task }) {
+      let result = null
+      await mutate(state => {
+        const list = arr(state.todayTasks)
+        const hit = findTask(list, task)
+        if (!hit) { result = { ok: false, reason: 'no_match' }; return null }
+        if (hit.ambiguous) { result = { ok: false, reason: 'ambiguous', candidates: hit.ambiguous }; return null }
+        if (hit.done) { result = { ok: true, already: true, task: hit.text }; return null }
+        result = { ok: true, task: hit.text }
+        return {
+          ...state,
+          todayTasks: list.map(t => (t.id === hit.id ? { ...t, done: true, completedAt: Date.now() } : t)),
+        }
+      })
+      if (!result?.ok && result?.reason === 'no_match') {
+        return { ok: false, message: `Nothing on today's list matches "${task}".` }
+      }
+      if (result?.reason === 'ambiguous') {
+        return { ok: false, message: `That matches several: ${result.candidates.join(', ')}. Be more specific.` }
+      }
+      return { ok: true, message: result.already ? `"${result.task}" was already done.` : `Ticked off "${result.task}".` }
+    },
+  },
+
+  {
+    name: 'capture',
+    title: 'Capture an idea',
+    description:
+      'Park a thought as an idea — NOT a task. Use this when the user says '
+      + '"remember this", "note that down", or floats something they might do '
+      + 'later. Use add_tasks when it is actually something to do today.',
+    inputSchema: {
+      type: 'object',
+      properties: { text: { type: 'string', minLength: 1, maxLength: 500 } },
+      required: ['text'], additionalProperties: false,
+    },
+    async run({ text }) {
+      const clean = String(text).trim()
+      await mutate(state => ({
+        ...state,
+        ideas: [{ id: uid(), text: clean, createdAt: Date.now(), source: 'mcp' }, ...arr(state.ideas)],
+      }))
+      return { ok: true, message: `Captured: "${clean}"` }
+    },
+  },
+
+  {
+    name: 'set_core_task',
+    title: 'Set the core task',
+    description:
+      "Set the ONE thing that would make today count. There is exactly one, so "
+      + 'this replaces any existing core task.',
+    inputSchema: {
+      type: 'object',
+      properties: { task: { type: 'string', minLength: 1, maxLength: 200 } },
+      required: ['task'], additionalProperties: false,
+    },
+    async run({ task }) {
+      const clean = String(task).trim()
+      let previous = null
+      await mutate(state => {
+        previous = state.coreTask?.task || state.coreTask || null
+        return { ...state, coreTask: { task: clean, setAt: Date.now(), source: 'mcp' } }
+      })
+      return { ok: true, core_task: clean, replaced: previous, message: `Core task set to "${clean}".` }
+    },
+  },
+
+  {
+    name: 'search',
+    title: 'Search everything',
+    description:
+      'Search across tasks, ideas, journal entries, lists and the backlog. '
+      + 'Use when the user asks whether they wrote something down, or what they '
+      + 'were doing about a topic.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', minLength: 2 },
+        limit: { type: 'integer', minimum: 1, maximum: 50, default: 20 },
+      },
+      required: ['query'], additionalProperties: false,
+    },
+    async run({ query, limit = 20 }) {
+      const { state } = await readState()
+      const q = String(query).toLowerCase()
+      const hits = []
+      const add = (where, text, extra = {}) => {
+        if (text && String(text).toLowerCase().includes(q)) hits.push({ where, text: String(text), ...extra })
+      }
+      arr(state.todayTasks).forEach(t => add('today', t.text, { done: !!t.done }))
+      arr(state.backlogTasks).forEach(t => add('backlog', t.text))
+      arr(state.taskDatabase).forEach(t => add('database', t.text))
+      arr(state.ideas).forEach(i => add('ideas', i.text))
+      arr(state.decompress).forEach(d => add('decompress', d.text))
+      Object.entries(state.journal || {}).forEach(([date, entries]) =>
+        arr(entries).forEach(e => add('journal', e?.text, { date })))
+      arr(state.lists).forEach(l => arr(l.items).forEach(i => add(`list:${l.title || l.name}`, i?.text ?? i)))
+      Object.entries(state.plannedTasks || {}).forEach(([date, list]) =>
+        arr(list).forEach(t => add('planned', t.text, { date })))
+
+      return { query, count: hits.length, results: hits.slice(0, limit) }
+    },
+  },
+]
+
+export const byName = Object.fromEntries(TOOLS.map(t => [t.name, t]))