@theronap/cortex-mcp 0.9.60 → 0.9.62

package/bin/cortex-mcp.mjs

@@ -36,11 +36,13 @@ if (cmd === '--version' || cmd === '-v') {
 if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
   process.stdout.write(
     `cortex-mcp ${VERSION} — connect your AI assistant to Cortex\n\n` +
-    `Onboard (one command):\n` +
-    `  npx -y @theronap/cortex-mcp setup <YOUR_TOKEN>\n\n` +
-    `This wires your Claude config so your AI sees your Cortex context and your\n` +
-    `sessions flow into the org automatically. Restart Claude Code after.\n\n` +
+    `Onboard (one command, no token to copy):\n` +
+    `  npx -y @theronap/cortex-mcp login\n\n` +
+    `This opens your browser, you click Approve, and it wires everything up. Restart\n` +
+    `Claude Code after, and your AI sees your Cortex context while your sessions flow\n` +
+    `into the org automatically.\n\n` +
     `Subcommands:\n` +
+    `  login [--label <name>]  browser-approved sign-in — gets a token for you, then runs setup\n` +
     `  setup <token>   wire MCP server + capture hook into ~/.claude config (single editor)\n` +
     `  install [<token>] [--editor auto|all|<id,...>]  wire Cortex into EVERY detected editor + write the capability manifest\n` +
     `  repair          re-run setup at the latest version using your existing token (no token needed)\n` +
@@ -68,7 +70,14 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
 // A graceful drain lets libuv finish those handles first, so the assertion never fires. The MCP
 // server (default branch) runs forever and never reaches an exit path. if/else so the CLI
 // commands don't fall through into the server.
-if (cmd === 'setup') {
+if (cmd === 'login') {
+  // Browser-approved sign-in: no token to copy. Ends by calling runSetup with the token it
+  // collected, so there is still exactly ONE code path that writes a credential to disk.
+  const { runLogin } = await import('../lib/login.mjs')
+  await runLogin(rest, VERSION)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'setup') {
   const { runSetup } = await import('../lib/setup.mjs')
   await runSetup(rest, VERSION)
   const { closeFetch } = await import('../lib/diagnose.mjs')

package/lib/login.mjs

@@ -0,0 +1,148 @@
+import os from 'node:os'
+import { spawn } from 'node:child_process'
+import { resolveBase, CANONICAL_BASE } from './diagnose.mjs'
+
+// `cortex-mcp login` — get a token without the human copy-pasting one out of the web console.
+//
+// WHY THIS EXISTS: the old path was log into the console, find /connect, copy a uuid, paste it into
+// a terminal. That copy-paste is the step that failed on the first non-technical onboarding
+// (2026-08-03), and it is the reason there could never be a real one-line install. Here the person
+// clicks Approve in a browser and types nothing.
+//
+// THE FLOW (server side: /api/device/{start,approve,exchange}):
+//   1. start    — we generate nothing; the server issues a device_code (our secret) + a short
+//                 user_code, and we open the pre-filled approval URL.
+//   2. approve  — happens in their browser, against their login. We never see their password and
+//                 never handle a JWT.
+//   3. exchange — we poll with the device_code; once a human has approved, the token is minted and
+//                 returned exactly once. Then we hand straight off to the normal `setup` wiring.
+//
+// Deliberately a DEVICE flow rather than a loopback redirect. Loopback needs a local port and an
+// open browser on the same machine, so it dies over SSH and on locked-down laptops. With the URL
+// pre-filled, the device flow costs the user the same single click and works everywhere.
+
+/** Open a URL in the user's default browser. Best-effort: never throws, never blocks the flow. */
+function openBrowser(url) {
+  const cmd =
+    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open'
+  const args = process.platform === 'win32' ? ['/c', 'start', '""', url] : [url]
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true })
+    // If the browser cannot be launched we still printed the URL, so this is genuinely non-fatal.
+    child.on('error', () => {})
+    child.unref()
+    return true
+  } catch {
+    return false
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+/** A label the person will recognise on the approval screen. Machine name, not a user name. */
+function deviceLabel() {
+  const host = os.hostname().replace(/\.local$/i, '')
+  return host || `${os.platform()} device`
+}
+
+export async function runLogin(argv = [], version = 'dev') {
+  const base = resolveBase(process.env.CORTEX_URL) || CANONICAL_BASE
+
+  // --label lets a person running several machines tell them apart later; account_tokens.label
+  // carries it, so it survives long after the grant row is swept.
+  const labelFlag = argv.indexOf('--label')
+  const label = labelFlag !== -1 && argv[labelFlag + 1] ? argv[labelFlag + 1] : deviceLabel()
+
+  let start
+  try {
+    const res = await fetch(`${base}/api/device/start`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ label }),
+    })
+    if (!res.ok) throw new Error(`server said ${res.status}`)
+    start = await res.json()
+  } catch (err) {
+    process.stderr.write(
+      `cortex: could not reach ${base} to start login (${err.message}).\n` +
+        `Check your connection, then try again.\n`,
+    )
+    process.exitCode = 1
+    return
+  }
+
+  const opened = openBrowser(start.verificationUriComplete)
+
+  process.stdout.write(
+    `\n  Confirm this code in your browser:  ${start.userCode}\n\n` +
+      (opened
+        ? `  A browser should have opened. If not, go to:\n    ${start.verificationUriComplete}\n\n`
+        : `  Open this in your browser:\n    ${start.verificationUriComplete}\n\n`) +
+      `  Waiting for you to approve it...\n`,
+  )
+
+  // Poll until approved or the grant expires. The server sets the pace (and says slow_down if we
+  // are early), so the cadence stays server-controlled rather than hardcoded here.
+  let interval = (start.interval ?? 2) * 1000
+  const deadline = Date.now() + (start.expiresIn ?? 600) * 1000
+  let token = null
+  let activeOrgId = null
+
+  while (Date.now() < deadline) {
+    await sleep(interval)
+    let res
+    try {
+      res = await fetch(`${base}/api/device/exchange`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ deviceCode: start.deviceCode }),
+      })
+    } catch {
+      continue // transient network blip: keep waiting rather than failing a login mid-approval
+    }
+
+    if (res.status === 429) {
+      interval = Math.min(interval * 2, 10_000) // back off, do not give up
+      continue
+    }
+    if (res.status === 410) {
+      process.stderr.write(`\ncortex: that took too long and the code expired. Run login again.\n`)
+      process.exitCode = 1
+      return
+    }
+    if (res.status === 409 || res.status === 404) {
+      const body = await res.json().catch(() => ({}))
+      process.stderr.write(`\ncortex: ${body.error ?? 'this login is no longer valid'}. Run login again.\n`)
+      process.exitCode = 1
+      return
+    }
+    if (!res.ok) continue
+
+    const body = await res.json().catch(() => ({}))
+    if (body.status === 'approved' && body.personalToken) {
+      token = body.personalToken
+      activeOrgId = body.activeOrgId ?? null
+      break
+    }
+    // 'pending' — the human has not clicked yet. Keep waiting quietly; a spinner that reprints
+    // every two seconds is noise on the one screen where the person is reading instructions.
+  }
+
+  if (!token) {
+    process.stderr.write(`\ncortex: nobody approved that login before it expired. Run login again.\n`)
+    process.exitCode = 1
+    return
+  }
+
+  process.stdout.write(`\n  Approved. Setting up...\n\n`)
+
+  // Hand the raw token straight to the existing installer. We never write it anywhere ourselves —
+  // runSetup owns every file that touches a credential, so there is exactly one code path that
+  // stores a token and one place to audit.
+  const { runSetup } = await import('./setup.mjs')
+  await runSetup([token], version)
+
+  if (activeOrgId) {
+    process.stdout.write(`  New pages will be saved in the space you picked.\n`)
+  }
+}

package/lib/server.mjs

@@ -235,8 +235,8 @@ export async function runServer(version) {
   server.registerTool(
     'timeline_pull',
     {
-      title: 'Pull unattributed messaging threads to triage',
-      description: "Surface messaging threads captured in the org (email, etc.) that AREN'T yet attributed to a project — the backlog awaiting your judgment. Call it as you work; when you recognize which KNOWN project a surfaced thread is about, attribute it with attribute_thread. Threads you don't recognize: leave them (they self-heal as the graph fills). Pass a `project` you're working on to RANK the backlog by relevance (threads sharing participants with that project come first, marked ★). Returns participants + subject + recency per thread — enough to recognize, not the message bodies.",
+      title: 'Pull the unclaimed backlog to triage',
+      description: "Surface everything captured in the org that NO ONE has judged yet — the backlog awaiting your judgment. Two sections: unattributed EMAIL threads (grouped, since a thread is what you actually triage), and unclaimed RECORDS from every other source (commits, sessions, docs, calendar) one by one. Call it as you work; when you recognize which KNOWN project a surfaced thread is about, attribute it with attribute_thread. Things you don't recognize: leave them — they stay in the backlog and self-heal as the graph fills. Pass a `project` you're working on to RANK the thread half by relevance (threads sharing participants with that project come first, marked ★); records are always newest-first. Returns enough to RECOGNIZE an item — participants, subject, title, recency — never the bodies.",
       inputSchema: {
         limit: z.number().optional().describe('max threads to return (default 20)'),
         project: z.string().optional().describe('optional KNOWN project slug to rank the backlog by relevance to what you are working on; omit for the whole backlog newest-first'),
@@ -252,18 +252,37 @@ export async function runServer(version) {
         const body = await res.text()
         throw new Error(classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message)
       }
-      const { threads } = await res.json()
-      if (!threads?.length) return { content: [{ type: 'text', text: 'No unattributed threads in the backlog.' }] }
-      const lines = threads.map((t) => {
-        const who = (t.participants ?? []).map((p) => String(p).replace(/^email:/, '')).join(', ')
-        const when = t.lastAt ? String(t.lastAt).slice(0, 10) : '—'
-        const rel = t.relevance && t.relevance.score > 0 ? ` · ★${t.relevance.score} ${t.relevance.reason}` : ''
-        return `- ${t.threadKey} — ${t.subject ?? '(no subject)'} · ${who || 'unknown participants'} · ${t.eventCount} msg · ${when}${rel}`
-      })
-      const header = project
-        ? `Unattributed threads (${threads.length}), ranked for project:${project} (★ = shares participants)`
-        : `Unattributed threads (${threads.length})`
-      return { content: [{ type: 'text', text: `${header} — attribute recognized ones with attribute_thread(threadKey, project):\n${lines.join('\n')}` }] }
+      const { threads, records } = await res.json()
+      if (!threads?.length && !records?.length) return { content: [{ type: 'text', text: 'Nothing in the backlog — everything captured so far has been claimed.' }] }
+
+      const sections = []
+
+      if (threads?.length) {
+        const lines = threads.map((t) => {
+          const who = (t.participants ?? []).map((p) => String(p).replace(/^email:/, '')).join(', ')
+          const when = t.lastAt ? String(t.lastAt).slice(0, 10) : '—'
+          const rel = t.relevance && t.relevance.score > 0 ? ` · ★${t.relevance.score} ${t.relevance.reason}` : ''
+          return `- ${t.threadKey} — ${t.subject ?? '(no subject)'} · ${who || 'unknown participants'} · ${t.eventCount} msg · ${when}${rel}`
+        })
+        const header = project
+          ? `Unattributed threads (${threads.length}), ranked for project:${project} (★ = shares participants)`
+          : `Unattributed threads (${threads.length})`
+        sections.push(`${header} — attribute recognized ones with attribute_thread(threadKey, project):\n${lines.join('\n')}`)
+      }
+
+      // The other 12 sources. No thread concept exists for a commit or a session log, so each is one
+      // row. `node` is shown when the record already carries a project — often the whole answer, and it
+      // is why these are NOT ranked by relevance: a record that already has a node needs judgment least.
+      if (records?.length) {
+        const lines = records.map((r) => {
+          const when = r.occurredAt ? String(r.occurredAt).slice(0, 10) : '—'
+          const node = r.node ? ` · → ${r.node}` : ''
+          return `- ${r.source}/${r.recordType ?? 'record'} — ${r.title ?? '(untitled)'} · ${when}${node}  [${r.recordId}]`
+        })
+        sections.push(`Unclaimed records (${records.length}) from other sources — newest first:\n${lines.join('\n')}`)
+      }
+
+      return { content: [{ type: 'text', text: sections.join('\n\n') }] }
     },
   )
 
@@ -542,6 +561,12 @@ export async function runServer(version) {
         const allBody = m.tiers.flatMap((t) => (t.sections ?? []).map((s) => s.body)).join('\n')
         const stamps = [...new Set((allBody.match(/\[\[repo:[a-z0-9][a-z0-9-]*\/[a-z0-9_.-]+\]\]/gi) ?? []).map((s) => s.toLowerCase()))]
         if (stamps.length) footer += `\n— This page carries ${stamps.join(', ')} — \`read_page "${name}"\` with history: true for its event timeline (page = present, timeline = history).`
+        // Gate 4's per-node backlog nudge (also gate 3's KWA-36). The SERVER decides whether this
+        // fires — it sends `nudge` only when 25+ records are unclaimed AND the page has gone 7+ days
+        // unedited — so there is no threshold logic here to drift out of sync. It rides in the footer
+        // because that is the surface with evidence behind it: a session read a page through a [[link]],
+        // saw the footer, and repaired the page. A dashboard nobody opens would not have.
+        if (m.backlog?.nudge) footer += `\n— ${m.backlog.nudge}`
         const brainTag = tagBrain ? `  ·  brain: ${m.brain}` : ''
         return `# ${m.title ?? name} (full authored page${brainTag})\n\n${blocks.join('\n\n---\n\n')}\n\n${footer}`
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.60",
+  "version": "0.9.62",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {