taskswipe-mcp 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # taskswipe-mcp
 
-Your TASK//SWIPE day, from inside Claude Code, Claude Desktop, Codex or Cursor.
+Your TASKKA day, from inside Claude Code, Claude Desktop, Codex or Cursor.
 
 ```
 you: add "call the bank" and "book the dentist" to today
@@ -27,15 +27,14 @@ token over the wire.
 
 ## Setup
 
-You need your TASK//SWIPE login token — that's it. The production Supabase URL
+You need your TASKKA 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.
+> **Published:** https://www.npmjs.com/package/taskswipe-mcp — so anywhere the
+> examples below run it by path, `npx -y taskswipe-mcp` works instead and needs
+> nothing checked out.
 
 **Claude Code**
 
@@ -74,6 +73,50 @@ TASKSWIPE_ACCESS_TOKEN = "eyJ..."
 (`codex mcp list` to confirm it registered; note the section is
 `mcp_servers`, snake_case, not `mcpServers`.)
 
+**Hermes Agent** (Nous) — local stdio, tokens refresh themselves. Paste into `~/.hermes/config.yaml`, then install the skill:
+
+```yaml
+mcp_servers:
+  taskka:
+    command: "npx"
+    args: ["-y", "taskswipe-mcp"]
+    env:
+      TASKSWIPE_ACCESS_TOKEN: "eyJ..."
+      TASKSWIPE_REFRESH_TOKEN: "..."
+```
+
+```bash
+hermes skills install https://taskka.app/.well-known/skills/taskka/SKILL.md
+```
+
+Copy both snippets from TASKKA → SETTINGS → AGENTS (signed in) so the tokens are live.
+
+**OpenClaw** — same local server. Paste into `openclaw.json` (or Control UI → Settings → MCP):
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "taskka": {
+        "command": "npx",
+        "args": ["-y", "taskswipe-mcp"],
+        "env": {
+          "TASKSWIPE_ACCESS_TOKEN": "eyJ...",
+          "TASKSWIPE_REFRESH_TOKEN": "..."
+        }
+      }
+    }
+  }
+}
+```
+
+```bash
+openclaw skills install https://taskka.app/.well-known/skills/taskka/SKILL.md
+openclaw mcp doctor taskka --probe
+```
+
+Hosted HTTP (`https://taskka.app/mcp` + `Authorization: Bearer <access>`) works for a Control-UI one-shot. Access tokens die in about an hour — always-on Hermes/OpenClaw gateways should use stdio above.
+
 **Claude Desktop / Cursor** — these do use the JSON shape
 (`claude_desktop_config.json` / `.cursor/mcp.json`):
 
@@ -95,7 +138,7 @@ TASKSWIPE_ACCESS_TOKEN = "eyJ..."
 
 ### Getting an access token
 
-Sign in to TASK//SWIPE in a browser, open the console, and run:
+Sign in to TASKKA in a browser, open the console, and run:
 
 ```js
 JSON.parse(Object.entries(localStorage).find(([k]) => k.includes('auth-token'))[1]).access_token
@@ -129,9 +172,7 @@ 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.
+1. ~~Publish to npm~~ — **done**, `taskswipe-mcp@0.1.0`.
 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";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "taskswipe-mcp",
-  "version": "0.1.0",
-  "description": "Read and write your TASK//SWIPE day from Claude Code, Claude Desktop, Codex or Cursor.",
+  "version": "0.2.1",
+  "description": "Read and write your TASKKA day from Claude Code, Claude Desktop, Codex or Cursor.",
   "type": "module",
   "bin": {
     "taskswipe-mcp": "src/index.js"

package/src/brief.js

@@ -0,0 +1,384 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// THE BRIEF — the whole system, in about a page.
+//
+// THE PROBLEM. An agent connecting to TASKKA could reach six tools covering
+// three of twenty-five tabs, and had no way to find out what the other
+// twenty-two even were. Answering "how am I doing?" meant guessing which tools
+// existed, calling several, and stitching. Answering anything about food, lifts,
+// money, habits, goals or study was impossible — not because the data was
+// private but because nothing described it.
+//
+// The lazy fix is get_state. That hands over a few hundred KB of arrays so the
+// model can count them itself: slow, expensive, and mostly a waste, because
+// ninety-nine percent of that blob is history nobody asked about.
+//
+// ── WHAT THIS DOES INSTEAD ──────────────────────────────────────────────────
+//
+// SUMMARISE, NEVER SERIALISE. No array goes out whole. Everything is a count,
+// a headline, or the two or three items that actually need a decision. The
+// brief is bounded — roughly the same size for someone on day 900 as on day 3 —
+// because size here should track how much is GOING ON, not how much has ever
+// happened.
+//
+// SIGNALS, NOT DATA. "3 habits missed 4 days" is the sentence an agent can act
+// on. The habits array is a puzzle it has to solve first, badly, every time.
+//
+// SAY WHAT EXISTS. `areas` lists every part of the app with a one-line state,
+// including the empty ones — an agent cannot ask about a tab it has no idea is
+// there, and "nothing logged" is a useful answer to "what should I do next?".
+//
+// LAYERED. The brief is the map. `detail(area)` is the drill-down, and the
+// existing tools do the writing. One cheap call to orient, one targeted call
+// for depth — instead of six calls and a guess.
+//
+// Pure and state-in/JSON-out on purpose, so it can be tested without a network.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const arr = (v) => (Array.isArray(v) ? v : [])
+const num = (v) => (Number.isFinite(+v) ? +v : 0)
+
+const dayStr = (d = new Date()) =>
+  `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+
+const daysAgo = (n, from = new Date()) => {
+  const d = new Date(from)
+  d.setDate(d.getDate() - n)
+  return dayStr(d)
+}
+
+const lastN = (n, from = new Date()) => Array.from({ length: n }, (_, i) => daysAgo(i, from))
+
+/** A completion is 'YYYY-MM-DD' or {date, kind}; a MISSED day is not a doing. */
+const stackDoneDays = (s) => new Set(arr(s?.completions)
+  .filter(c => (typeof c === 'string' ? true : c?.kind !== 'missed'))
+  .map(c => (typeof c === 'string' ? c : c?.date))
+  .filter(Boolean))
+
+const habitDoneDays = (h) => new Set(arr(h?.completions).map(c => (typeof c === 'string' ? c : c?.date)).filter(Boolean))
+
+/** How many of the last `win` days had a tick — the honest read of a streak. */
+const hitRate = (days, win, from) => lastN(win, from).reduce((n, d) => n + (days.has(d) ? 1 : 0), 0)
+
+const partOfDay = (h) => (h < 5 ? 'night' : h < 12 ? 'morning' : h < 17 ? 'afternoon' : h < 22 ? 'evening' : 'night')
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function buildBrief(state = {}, now = new Date()) {
+  const today = dayStr(now)
+  const S = state || {}
+
+  // ── TODAY ─────────────────────────────────────────────────────────────────
+  const tasks = arr(S.todayTasks)
+  const open = tasks.filter(t => !t.done)
+  const done = tasks.filter(t => t.done)
+  const timed = open.filter(t => t.at).sort((a, b) => String(a.at).localeCompare(String(b.at)))
+  const hhmm = `${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}`
+
+  // ── ATTENTION: the things a person would want raised ──────────────────────
+  // Ordered by severity so an agent can take the top one and be right most of
+  // the time. This is the part worth reading if it reads nothing else.
+  const attention = []
+
+  const overdue = timed.filter(t => String(t.at) < hhmm)
+  if (overdue.length) {
+    attention.push({ area: 'today', severity: 3,
+      what: `${overdue.length} scheduled ${overdue.length === 1 ? 'task is' : 'tasks are'} past their time`,
+      items: overdue.slice(0, 3).map(t => `${t.at} ${t.text}`) })
+  }
+
+  const missed = arr(S.missedTasks)
+  if (missed.length) {
+    attention.push({ area: 'dropped', severity: missed.length >= 3 ? 2 : 1,
+      what: `${missed.length} unfinished from earlier days sitting in LOG → DROPPED`,
+      items: missed.slice(0, 4).map(t => t.text) })
+  }
+
+  // Habits are the app's committed tier: quiet ones are the real signal.
+  const quietHabits = arr(S.habits)
+    .map(h => ({ name: h.name || h.title, hits: hitRate(habitDoneDays(h), 7, now) }))
+    .filter(h => h.hits === 0)
+  if (quietHabits.length) {
+    attention.push({ area: 'habits', severity: 2,
+      what: `${quietHabits.length} habit${quietHabits.length === 1 ? '' : 's'} untouched for a week`,
+      items: quietHabits.slice(0, 4).map(h => h.name) })
+  }
+
+  const decay = S.decayState || {}
+  if (num(decay.quietStreak) >= 2) {
+    attention.push({ area: 'squares', severity: 2,
+      what: `${decay.quietStreak} quiet days in a row — squares are decaying` })
+  }
+
+  if (!S.coreTask && open.length > 3) {
+    attention.push({ area: 'today', severity: 1,
+      what: `${open.length} things open and nothing named as the one that matters` })
+  }
+
+  attention.sort((a, b) => b.severity - a.severity)
+
+  // ── AREAS: one line each, including the empty ones ────────────────────────
+  const foodToday = arr(S.foodLog?.[today])
+  const kcal = Math.round(foodToday.reduce((n, e) =>
+    n + (num(e.per100?.kcal) * num(e.grams)) / 100, 0))
+  const health = S.healthDaily?.[today] || {}
+
+  const stacks = arr(S.stacks).filter(s => !s.retiredAt).map(s => ({
+    name: s.name,
+    hits: hitRate(stackDoneDays(s), Math.round((num(s.graduationTarget) || 14) * 1.5), now),
+    target: num(s.graduationTarget) || 14,
+  }))
+  const readyStacks = stacks.filter(s => s.hits >= s.target)
+
+  const goalFrames = S.goals && typeof S.goals === 'object' ? Object.values(S.goals).flat() : []
+  const building = goalFrames.find(g => g?.id === S.activeGoalId)
+
+  const maps = arr(S.studyMaps)
+  const learningTopics = maps.flatMap(m => arr(m.nodes).filter(n => n.status === 'learning')
+    .map(n => `${m.title}: ${n.title}`))
+
+  const biz = arr(S.businessIdeas)
+  const areas = {
+    today: `${open.length} open, ${done.length} done${S.coreTask ? `, core: ${S.coreTask.task || S.coreTask}` : ''}`,
+    dropped: missed.length
+      ? `${missed.length} unfinished from earlier days (LOG → DROPPED)`
+      : 'nothing sitting in DROPPED',
+    backlog: `${arr(S.backlogTasks).length} parked`,
+    docket: `${arr(S.docketTasks).length} coming-up with no clock`,
+    deck: `${arr(S.deck).length} cards waiting to be swiped`,
+    recurring: `${arr(S.recurringTasks).length} rules`,
+    lists: `${arr(S.lists).length} lists`,
+    frame: `${arr(S.frameworks).length} living frameworks`,
+    business: biz.length
+      ? `${biz.filter(i => i?.stage !== 'ship' && i?.stage !== 'drop').length} live ideas on the spark-to-ship path`
+      : 'no ideas on the path',
+    people: `${arr(S.people).length} people`,
+    things: `${arr(S.things).length} kept`,
+    missions: `${arr(S.missions).filter(m => !m.done).length} open`,
+    goals: goalFrames.length
+      ? `${goalFrames.length} goals${building ? `, building: ${building.text}` : ', none on the crane'}`
+      : 'none set',
+    habits: arr(S.habits).length
+      ? `${arr(S.habits).length} habits, ${arr(S.habits).filter(h => habitDoneDays(h).has(today)).length} ticked today`
+      : 'none',
+    stacks: stacks.length
+      ? `${stacks.length} building${readyStacks.length ? `, ${readyStacks.length} ready to graduate` : ''}`
+      : 'none',
+    food: foodToday.length
+      ? `${kcal} kcal logged today, ${arr(S.pantry).length} foods on the shelf`
+      : `nothing logged today, ${arr(S.pantry).length} foods on the shelf`,
+    lift: `${arr(S.liftSessions).length} sessions logged`,
+    walk: health.steps ? `${health.steps} steps today` : 'no step data today',
+    money: arr(S.moneyTx).length ? `${arr(S.moneyTx).length} transactions` : 'nothing tracked',
+    mind: S.moods?.[today]?.length
+      ? `${S.moods[today].length} check-ins today`
+      : 'no check-in today',
+    day_score: S.dayScores?.[today] ? `${S.dayScores[today].score}/10 posted` : 'not posted',
+    study: maps.length
+      ? `${maps.length} maps, ${learningTopics.length} topics in progress`
+      : 'none',
+    reader: `${arr(S.books).length} books`,
+    parley: `${arr(S.parleyDeck).length} cards`,
+    squares: `${num(S.totalSquares)} total${num(decay.quietStreak) ? `, ${decay.quietStreak} quiet days` : ''}`,
+  }
+
+  return {
+    now: { date: today, time: hhmm, part_of_day: partOfDay(now.getHours()) },
+
+    // The one sentence an agent should lead with. Everything below is evidence.
+    headline: attention[0]?.what
+      || (open.length ? `${open.length} open today, nothing overdue` : 'nothing open today'),
+
+    today: {
+      core_task: S.coreTask?.task || S.coreTask || null,
+      open: open.length,
+      done: done.length,
+      // Only the ones with a time — an untimed list of forty is not a schedule.
+      next: timed.filter(t => String(t.at) >= hhmm).slice(0, 3).map(t => `${t.at} ${t.text}`),
+      overdue: overdue.slice(0, 5).map(t => `${t.at} ${t.text}`),
+      open_titles: open.slice(0, 12).map(t => t.text),
+    },
+
+    attention: attention.slice(0, 6),
+    areas,
+
+    // Where to look next, so an agent does not have to guess which tools exist.
+    drill: {
+      more_on_an_area: "detail(area) — any key from `areas`",
+      today_in_full: 'today()',
+      dropped_in_full: 'detail({ area: "dropped" })',
+      find_anything: 'search(query)',
+      write: 'add_tasks, complete_task, capture, set_core_task, recover_dropped',
+    },
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DETAIL — one area, still summarised.
+//
+// The point of splitting this out is that an agent pays for depth only where it
+// asked for it. Each branch returns the shape someone would actually reason
+// with, not the rows.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function buildDetail(state = {}, area = '', now = new Date()) {
+  const S = state || {}
+  const today = dayStr(now)
+  const key = String(area || '').toLowerCase().trim()
+
+  switch (key) {
+    case 'today': {
+      const tasks = arr(S.todayTasks)
+      return {
+        open: tasks.filter(t => !t.done).map(t => ({
+          text: t.text, at: t.at || null, category: t.category || null,
+          why: t.why || null, timer: t.timer || null, sticky: !!t.sticky,
+        })),
+        done: tasks.filter(t => t.done).map(t => t.text),
+        dropped: arr(S.missedTasks).slice(0, 20).map(t => t.text),
+      }
+    }
+    case 'dropped':
+    case 'log':
+      return {
+        where: 'LOG → DROPPED. Tasks that aged out unfinished from earlier days. Not the backlog, not CUT.',
+        count: arr(S.missedTasks).length,
+        items: arr(S.missedTasks).slice(0, 40).map(t => ({
+          text: t.text,
+          expired: t.expiredDate || null,
+          category: t.category || null,
+        })),
+        recover: 'recover_dropped({ task }) puts one back on today',
+      }
+    case 'docket':
+    case 'calendar':
+      return {
+        docket: arr(S.docketTasks).slice(0, 40).map(t => t.text || t.task),
+        planned_days: Object.keys(S.plannedTasks || {}).length,
+      }
+    case 'lists':
+      return arr(S.lists).slice(0, 30).map(l => ({
+        name: l.title || l.name, items: arr(l.items).length,
+      }))
+    case 'frame':
+      return arr(S.frameworks).slice(0, 20).map(f => ({
+        name: f.name, when: f.when || null, decisions: arr(f.decisions).length,
+      }))
+    case 'business':
+      return arr(S.businessIdeas).slice(0, 40).map(i => ({
+        title: i.title, stage: i.stage || 'spark', next: i.next || null,
+      }))
+    case 'people':
+      return arr(S.people).slice(0, 40).map(p => ({
+        name: p.name, role: p.role || null, company: p.company || null,
+      }))
+    case 'things':
+      return { kept: arr(S.things).length, categories: arr(S.thingsCats).length }
+    case 'habits':
+      return arr(S.habits).map(h => {
+        const days = habitDoneDays(h)
+        return { name: h.name || h.title, today: days.has(today), last_7: hitRate(days, 7, now), lifetime: days.size }
+      })
+    case 'stacks':
+      return arr(S.stacks).map(s => {
+        const days = stackDoneDays(s)
+        const target = num(s.graduationTarget) || 14
+        const window = Math.round(target * 1.5)
+        return {
+          name: s.name, cue: s.anchor || null, minimum: s.minimum || null,
+          retired: !!s.retiredAt,
+          hits: hitRate(days, window, now), target, window,
+          ready: hitRate(days, window, now) >= target,
+          today: days.has(today),
+        }
+      })
+    case 'goals': {
+      const frames = S.goals && typeof S.goals === 'object' ? S.goals : {}
+      return Object.entries(frames).flatMap(([frame, list]) => arr(list).map(g => ({
+        frame, text: g.text, bricks: `${num(g.earnedBricks)}/${num(g.targetBricks) || 20}`,
+        building: g.id === S.activeGoalId,
+        steps: arr(g.steps).length ? arr(g.steps).map(st => `${st.stage}: ${st.text}`) : null,
+      })))
+    }
+    case 'food': {
+      const day = arr(S.foodLog?.[today])
+      const shopping = arr(S.foodShoppingList)
+      const openShopping = shopping.filter(row => !row.done)
+      const tot = day.reduce((a, e) => {
+        const f = num(e.grams) / 100
+        return {
+          kcal: a.kcal + num(e.per100?.kcal) * f,
+          protein: a.protein + num(e.per100?.protein) * f,
+          carbs: a.carbs + num(e.per100?.carbs) * f,
+          fat: a.fat + num(e.per100?.fat) * f,
+        }
+      }, { kcal: 0, protein: 0, carbs: 0, fat: 0 })
+      return {
+        today: day.map(e => `${e.meal}: ${e.name} ${e.grams}${e.unit || 'g'}`),
+        totals: Object.fromEntries(Object.entries(tot).map(([k, v]) => [k, Math.round(v)])),
+        targets: S.foodTargets || null,
+        pantry_size: arr(S.pantry).length,
+        pantry_catalog_size: arr(S.pantry).length,
+        pantry_stock: arr(S.pantryStock).slice(0, 100).map(row => ({
+          name: row.name,
+          quantity: num(row.quantity),
+          unit: row.unit || 'each',
+          location: row.location || null,
+          expires_on: row.expiresOn || null,
+          minimum: num(row.minimum),
+        })),
+        shopping_list: openShopping.slice(0, 60).map(row => ({
+          name: row.name,
+          quantity: num(row.quantity) || 1,
+          unit: row.unit || 'each',
+          source: row.source || 'manual',
+        })),
+        shopping_counts: {
+          open: openShopping.length,
+          bought: shopping.length - openShopping.length,
+          returned: Math.min(openShopping.length, 60),
+        },
+        ordering_rules: String(S.aiPlaybookOverlays?.food || '').slice(0, 4000) || null,
+        saved_meals: arr(S.meals).map(m => m.name),
+      }
+    }
+    case 'study':
+      return arr(S.studyMaps).map(m => ({
+        map: m.title, aim: m.blurb || null,
+        topics: arr(m.nodes).map(n => ({
+          title: n.title, status: n.status,
+          // The tutor's note is the memory of this topic — the single most
+          // useful thing an agent can read about someone's learning.
+          next: (n.note || '').split(/^##\s+Next\s*$/mi)[1]?.split('\n').map(l => l.trim()).find(Boolean) || null,
+        })),
+      }))
+    case 'lift':
+      return {
+        sessions: arr(S.liftSessions).slice(-8).map(s => ({
+          date: s.date, name: s.name || null,
+          exercises: arr(s.exercises).map(e => e.name).slice(0, 12),
+        })),
+        routines: arr(S.liftRoutines).map(r => r.name),
+      }
+    case 'mind': {
+      // The day note is composed of tagged segments; an agent wants the prose.
+      const segs = arr(S.moodDayJournals?.[today])
+      return {
+        today: arr(S.moods?.[today]).map(m => m.mood || m.key),
+        day_score: S.dayScores?.[today] || null,
+        note: segs.map(x => x.text).filter(Boolean).join(' ').slice(0, 800) || null,
+      }
+    }
+    case 'squares':
+      return {
+        total: num(S.totalSquares),
+        decay: S.decayState || null,
+        recent_losses: arr(S.decayLog).slice(-5),
+      }
+    case 'backlog':
+      return arr(S.backlogTasks).slice(0, 40).map(t => ({ text: t.text, horizon: t.horizon || null }))
+    case 'missions':
+      return arr(S.missions).map(m => ({ title: m.title, done: !!m.done, tasks: arr(m.taskIds).length }))
+    default:
+      return { error: `unknown area "${area}"`, known: Object.keys(buildBrief(S, now).areas) }
+  }
+}

package/src/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // ─────────────────────────────────────────────────────────────────────────────
-// TASK//SWIPE MCP SERVER — stdio transport.
+// TASKKA 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
@@ -51,11 +51,16 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     log(`[taskswipe] ${tool.name} failed:`, e?.message || e)
     return {
       isError: true,
-      content: [{ type: 'text', text: `TASK//SWIPE: ${e?.message || 'unknown error'}` }],
+      content: [{ type: 'text', text: `TASKKA: ${e?.message || 'unknown error'}` }],
     }
   }
 })
 
-const transport = new StdioServerTransport()
-await server.connect(transport)
-log('[taskswipe] MCP server ready on stdio —', TOOLS.length, 'tools')
+if (process.argv[2] === 'setup') {
+  const { runSetup } = await import('./setup.js')
+  await runSetup(process.argv.slice(3))
+} else {
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  log('[taskswipe] MCP server ready on stdio —', TOOLS.length, 'tools')
+}

package/src/ob1.js

@@ -0,0 +1,104 @@
+// OB1 / Open Brain — durable cross-tool memory (Supabase + MCP).
+// TASKKA talks to the same HTTP MCP Codex and Grok already use.
+// Do not dump the vault into it. Capture a concise lesson, not a file.
+
+import { looksLikeSecret } from './os.js'
+
+const MAX_CAPTURE = 4000
+
+function endpoint() {
+  const raw = String(process.env.OPEN_BRAIN_URL || process.env.OB1_MCP_URL || '').trim()
+  if (!raw) return ''
+  const key = String(process.env.OPEN_BRAIN_KEY || process.env.OB1_KEY || '').trim()
+  if (!key || /[?&]key=/.test(raw)) return raw
+  return raw.includes('?') ? `${raw}&key=${encodeURIComponent(key)}` : `${raw}?key=${encodeURIComponent(key)}`
+}
+
+export function ob1Configured() {
+  return !!endpoint()
+}
+
+function parseMcpBody(text) {
+  const src = String(text || '').trim()
+  if (!src) return {}
+  if (src.startsWith('{')) {
+    try { return JSON.parse(src) } catch { /* SSE below */ }
+  }
+  for (const block of src.split('\n\n')) {
+    const line = block.split('\n').find(l => l.startsWith('data: '))
+    if (!line) continue
+    try { return JSON.parse(line.slice(6)) } catch { /* next */ }
+  }
+  return { error: { message: 'ob1_unreadable' } }
+}
+
+async function mcpCall(name, args = {}) {
+  const url = endpoint()
+  if (!url) throw Object.assign(new Error('ob1_unconfigured'), { status: 503 })
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+    },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: Date.now(),
+      method: 'tools/call',
+      params: { name, arguments: args },
+    }),
+  })
+  const raw = await res.text()
+  const msg = parseMcpBody(raw)
+  if (!res.ok) {
+    throw Object.assign(new Error(msg.error?.message || `ob1_${res.status}`), { status: res.status === 401 ? 403 : 502 })
+  }
+  if (msg.error) {
+    throw Object.assign(new Error(msg.error.message || 'ob1_failed'), { status: 502 })
+  }
+  const text = (msg.result?.content || []).map(c => c.text || '').filter(Boolean).join('\n')
+  if (msg.result?.isError) {
+    throw Object.assign(new Error(text || 'ob1_tool_error'), { status: 502 })
+  }
+  return { text, result: msg.result }
+}
+
+export function formatOb1Capture({ text, source, title } = {}) {
+  const body = String(text || '').trim()
+  const head = ['TASKKA', source, title].filter(Boolean).join(' · ')
+  const packed = head ? `${head}\n\n${body}` : body
+  return packed.slice(0, MAX_CAPTURE)
+}
+
+export async function ob1Status() {
+  if (!ob1Configured()) return { configured: false, thoughts: 0 }
+  try {
+    const { text } = await mcpCall('thought_stats', {})
+    const total = Number((text.match(/Total thoughts:\s*(\d+)/i) || [])[1] || 0)
+    return { configured: true, thoughts: total, summary: text.slice(0, 1200) }
+  } catch (e) {
+    return { configured: true, thoughts: 0, error: e.message || 'ob1_status_failed' }
+  }
+}
+
+export async function searchOb1(query, { limit = 8, threshold = 0.5 } = {}) {
+  const q = String(query || '').trim()
+  if (q.length < 2) return { query: q, results: [] }
+  const { text } = await mcpCall('search_thoughts', { query: q, limit, threshold })
+  return { query: q, text }
+}
+
+export async function listOb1({ limit = 8, days } = {}) {
+  const args = { limit }
+  if (days) args.days = days
+  const { text } = await mcpCall('list_thoughts', args)
+  return { text }
+}
+
+export async function captureOb1({ text, source, title } = {}) {
+  const content = formatOb1Capture({ text, source, title })
+  if (!content.trim()) throw Object.assign(new Error('empty_thought'), { status: 400 })
+  if (looksLikeSecret(content)) throw Object.assign(new Error('secrets_forbidden'), { status: 400 })
+  const { text: reply } = await mcpCall('capture_thought', { content })
+  return { ok: true, message: reply || 'Captured in OB1.' }
+}