@theronap/cortex-mcp 0.2.0 → 0.4.0

package/bin/cortex-mcp.mjs

@@ -5,6 +5,7 @@
  * Subcommands:
  *   (none)            run the MCP server (stdio) — used by your Claude config
  *   setup <TOKEN>     wire BOTH the MCP server + capture hook into your Claude config
+ *   doctor            live health check — is the token actually working? (no restart needed)
  *   capture           the Stop-hook capturer (invoked by Claude Code, not by hand)
  *   --version | -v
  *   --help | -h
@@ -15,7 +16,7 @@
  * Get your token from the Cortex console → Connect your AI.
  */
 
-const VERSION = '0.2.0'
+const VERSION = '0.4.0'
 const cmd = process.argv[2]
 const rest = process.argv.slice(3)
 
@@ -33,6 +34,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `sessions flow into the org automatically. Restart Claude Code after.\n\n` +
     `Subcommands:\n` +
     `  setup <token>   wire MCP server + capture hook into ~/.claude config\n` +
+    `  doctor          live health check — confirm your token works (no restart needed)\n` +
     `  capture         Stop-hook capturer (invoked by Claude Code)\n` +
     `  (no args)       run the MCP server (used by your Claude config)\n\n` +
     `Get your token from the Cortex console → Connect your AI.\n`,
@@ -42,10 +44,15 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
 
 if (cmd === 'setup') {
   const { runSetup } = await import('../lib/setup.mjs')
-  runSetup(rest)
+  await runSetup(rest)
   process.exit(0)
 }
 
+if (cmd === 'doctor') {
+  const { runDoctor } = await import('../lib/doctor.mjs')
+  process.exit(await runDoctor())
+}
+
 if (cmd === 'capture') {
   const { runCapture } = await import('../lib/capture.mjs')
   await runCapture()

package/lib/capture.mjs

@@ -1,4 +1,5 @@
 import { readFileSync } from 'fs'
+import { fetchCortex, classify } from './diagnose.mjs'
 
 // Claude Code Stop hook → POSTs a session digest to Cortex cloud, which
 // summarizes server-side and upserts ONE record per session. Node-native
@@ -40,23 +41,31 @@ export async function runCapture() {
 
   if (!transcript && !hook.session_id) { process.stderr.write('cortex: empty session, skipping\n'); return }
 
-  const res = await fetch(`${base}/api/ingest`, {
-    method: 'POST',
-    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      source: 'claude-code',
-      project: repo,
-      sessionId: hook.session_id,
-      transcript,
-      title: `Worked in ${repo}`,
-      payload: { session_id: hook.session_id, cwd: hook.cwd },
-    }),
-  }).catch((e) => { process.stderr.write(`cortex: ingest failed: ${e}\n`); return null })
-
-  if (res && res.ok) {
+  let res
+  try {
+    res = await fetchCortex(`${base}/api/ingest`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        source: 'claude-code',
+        project: repo,
+        sessionId: hook.session_id,
+        transcript,
+        title: `Worked in ${repo}`,
+        payload: { session_id: hook.session_id, cwd: hook.cwd },
+      }),
+    })
+  } catch (e) {
+    // Never break a session — just report and move on.
+    process.stderr.write(`cortex: ${e.message}\n`)
+    return
+  }
+
+  if (res.ok) {
     const j = await res.json().catch(() => ({}))
     process.stderr.write(`cortex: ${j.inserted ? 'captured' : 'updated'} "${j.title ?? repo}" → ${repo}\n`)
-  } else if (res) {
-    process.stderr.write(`cortex: ingest ${res.status}\n`)
+  } else {
+    const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+    process.stderr.write(`cortex: ingest failed — ${d.message}\n`)
   }
 }

package/lib/diagnose.mjs

@@ -0,0 +1,110 @@
+// Shared health / diagnosis helpers for the cortex MCP client.
+//
+// The whole reason this file exists: a transient infrastructure block (Vercel firewall / bot
+// protection / deployment protection) once surfaced as a bare "Cortex API 403: unknown", which
+// read like an auth failure and sent everyone chasing token regeneration for hours. The fix is
+// to tell the truth about WHAT failed.
+//
+// KEY SIGNAL: the Cortex app ALWAYS returns JSON ({ error: ... }). So a NON-JSON body on a
+// 4xx/5xx means infrastructure handled the request, not Cortex auth — re-running setup or
+// regenerating the token will not help; it is usually transient and worth a retry.
+
+export const isUuid = (s) =>
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s ?? '')
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+// A non-OK response → an actionable diagnosis: { kind, retriable, message }.
+//   kind: 'auth'  → token bad/revoked/wrong-deployment (NOT retriable)
+//         'infra' → blocked by infrastructure, non-JSON body (retriable, usually transient)
+//         'app'   → a real Cortex API error with a JSON message (retriable only if 5xx)
+export function classify(status, contentType, bodyText, requestId) {
+  const isJson = (contentType ?? '').includes('application/json')
+  let appError = null
+  if (isJson) { try { appError = JSON.parse(bodyText)?.error ?? null } catch { /* not json after all */ } }
+  const rid = requestId ? ` [request id: ${requestId}]` : ''
+
+  if (status === 401 || (isJson && appError === 'invalid token')) {
+    return {
+      kind: 'auth', retriable: false,
+      message: `Token rejected (HTTP ${status}: ${appError ?? 'unauthorized'}). The token is invalid, ` +
+        `revoked, or for a different deployment — not an infrastructure problem. Get a fresh token from ` +
+        `the Cortex console → Connect your AI, then re-run setup.${rid}`,
+    }
+  }
+  if (!isJson) {
+    return {
+      kind: 'infra', retriable: true,
+      message: `Blocked by infrastructure (HTTP ${status}, non-JSON response) — NOT by Cortex auth. This is ` +
+        `usually a transient firewall / bot-protection hiccup; retrying often clears it. If it persists, check ` +
+        `Vercel firewall / deployment protection on the API route. Re-running setup will not help.${rid}`,
+    }
+  }
+  return {
+    kind: 'app', retriable: status >= 500,
+    message: `Cortex API ${status}: ${appError ?? 'unknown error'}.${rid}`,
+  }
+}
+
+// fetch with retry on TRANSIENT responses only (429, 5xx, and infra-style non-JSON 403).
+// App-level 401/403-with-JSON are returned immediately (retrying won't change the verdict).
+// Throws a clear network error if the host is unreachable after retries.
+export async function fetchCortex(url, opts = {}, { retries = 2, baseDelayMs = 400 } = {}) {
+  let lastErr
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const res = await fetch(url, opts)
+      const ct = res.headers.get('content-type') ?? ''
+      const transient =
+        res.status === 429 ||
+        res.status >= 500 ||
+        (res.status === 403 && !ct.includes('application/json')) // infra block, not app authz
+      if (transient && attempt < retries) {
+        await sleep(baseDelayMs * 2 ** attempt)
+        continue
+      }
+      return res
+    } catch (e) {
+      lastErr = e
+      if (attempt < retries) { await sleep(baseDelayMs * 2 ** attempt); continue }
+    }
+  }
+  throw new Error(
+    `Could not reach Cortex at ${url} — ${lastErr?.message ?? 'network error'}. ` +
+    `Check your connection (and CORTEX_URL if you set it).`,
+  )
+}
+
+// Live health probe: hit /api/mcp-context with the token and classify the result.
+// Returns { ok, status, projectCount?, requestId?, diagnosis? }.
+export async function checkToken(token, base) {
+  if (!token) {
+    return { ok: false, status: 0, diagnosis: { kind: 'config', retriable: false,
+      message: 'No CORTEX_TOKEN found. Run: npx -y @theronap/cortex-mcp setup <your-token>' } }
+  }
+  if (!isUuid(token)) {
+    return { ok: false, status: 0, diagnosis: { kind: 'config', retriable: false,
+      message: `Token "${String(token).slice(0, 8)}…" is not a valid Cortex token (expected a UUID). ` +
+        `Re-run setup with the token from the console.` } }
+  }
+  const url = `${(base ?? 'https://cortex-console.vercel.app').replace(/\/$/, '')}/api/mcp-context`
+  let res
+  try {
+    res = await fetchCortex(url, { headers: { Authorization: `Bearer ${token}` } })
+  } catch (e) {
+    return { ok: false, status: 0, diagnosis: { kind: 'network', retriable: true, message: e.message } }
+  }
+  const requestId = res.headers.get('x-vercel-id') ?? null
+  const contentType = res.headers.get('content-type')
+  const body = await res.text()
+  if (!res.ok) {
+    return { ok: false, status: res.status, requestId, diagnosis: classify(res.status, contentType, body, requestId) }
+  }
+  let projectCount
+  try {
+    const ctx = JSON.parse(body).context ?? ''
+    const m = ctx.match(/## Projects \((\d+)\)/)
+    if (m) projectCount = Number(m[1])
+  } catch { /* context shape changed — non-fatal for a health check */ }
+  return { ok: true, status: 200, projectCount, requestId }
+}

package/lib/doctor.mjs

@@ -0,0 +1,56 @@
+import { readFileSync, existsSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { checkToken } from './diagnose.mjs'
+
+// `npx @theronap/cortex-mcp doctor` — a live, one-command health check.
+//
+// This is the "is it ACTUALLY working?" tool that was missing: it reads your token, calls the
+// real Cortex API, and prints a clear PASS/FAIL with the actual cause. No Claude Code restart
+// needed — so onboarding can confirm the connection independently of "did the server load."
+
+// Token resolution: env first, then the Claude config the setup command wrote (so `doctor`
+// works the moment after `setup`, before any restart). Returns { token, source }.
+function resolveToken() {
+  if (process.env.CORTEX_TOKEN) return { token: process.env.CORTEX_TOKEN, source: 'CORTEX_TOKEN env' }
+  const claudeJson = join(homedir(), '.claude.json')
+  if (existsSync(claudeJson)) {
+    try {
+      const cfg = JSON.parse(readFileSync(claudeJson, 'utf8'))
+      const t = cfg?.mcpServers?.cortex?.env?.CORTEX_TOKEN
+      if (t) return { token: t, source: `${claudeJson} (mcpServers.cortex)` }
+    } catch { /* malformed config — fall through to "not found" */ }
+  }
+  return { token: null, source: null }
+}
+
+export async function runDoctor() {
+  const base = (process.env.CORTEX_URL ?? 'https://cortex-console.vercel.app').replace(/\/$/, '')
+  const out = (m) => process.stdout.write(m + '\n')
+
+  out('')
+  out('Cortex doctor — checking your connection…')
+  const { token, source } = resolveToken()
+  out(`  token source: ${source ?? 'NONE FOUND'}`)
+  out(`  endpoint:     ${base}`)
+  out('')
+
+  const r = await checkToken(token, base)
+
+  if (r.ok) {
+    out('  ✓ PASS — your token authenticates and Cortex returned your context.')
+    if (typeof r.projectCount === 'number') out(`    You can currently see ${r.projectCount} project(s).`)
+    if (r.requestId) out(`    (request id: ${r.requestId})`)
+    out('')
+    out('  If your AI still does not see Cortex, the server just is not loaded yet —')
+    out('  fully quit and reopen Claude Code (the MCP server starts on launch).')
+    out('')
+    return 0
+  }
+
+  out(`  ✗ FAIL — ${r.diagnosis?.kind ?? 'error'}${r.status ? ` (HTTP ${r.status})` : ''}`)
+  out(`    ${r.diagnosis?.message ?? 'unknown error'}`)
+  if (r.diagnosis?.retriable) out('    This looks transient — running `doctor` again shortly may succeed.')
+  out('')
+  return 1
+}

package/lib/server.mjs

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod'
+import { fetchCortex, classify } from './diagnose.mjs'
 
 // The Cortex MCP server (stdio). Serves the signed-in employee's scoped org
 // context to their AI assistant. CORTEX_TOKEN identifies the user + org.
@@ -19,11 +20,12 @@ export async function runServer(version) {
   async function fetchContext() {
     const now = Date.now()
     if (cache && now - cache.ts < 5 * 60 * 1000) return cache.text
-    const res = await fetch(`${BASE}/api/mcp-context`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+    // fetchCortex retries transient infra/5xx; classify turns a failure into an honest message
+    // (token vs infra-block vs network) instead of a bare "Cortex API 403: unknown".
+    const res = await fetchCortex(`${BASE}/api/mcp-context`, { headers: { Authorization: `Bearer ${TOKEN}` } })
     if (!res.ok) {
-      let detail = 'unknown'
-      try { detail = (await res.json()).error ?? detail } catch { /* ignore */ }
-      throw new Error(`Cortex API ${res.status}: ${detail}`)
+      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 { context } = await res.json()
     cache = { text: context, ts: now }
@@ -71,5 +73,64 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'story',
+    {
+      title: 'Story of a topic',
+      description: 'Ask "what\'s the story of X?" — assembles a chronological narrative of what happened with a project, topic, or piece of work, from across all your activity (commits, sessions, discussions). Scoped to what you can see.',
+      inputSchema: { question: z.string().describe('the topic/project/thing to get the story of, e.g. "the auth work" or "checkout-v2"') },
+    },
+    async ({ question }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/story`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ question }),
+        })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not assemble story: ${e.message}` }] }
+      }
+      if (!res.ok) {
+        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+        return { content: [{ type: 'text', text: `Could not assemble story: ${d.message}` }] }
+      }
+      const { answer, sourceCount, sources } = await res.json()
+      const srcList = (sources ?? []).map((s) => `  - [${s.id}] ${s.title} (${s.source})`).join('\n')
+      const tail = srcList ? `\n\nSources (pass an id to set_record_privacy to reclassify a record you own):\n${srcList}` : ''
+      return { content: [{ type: 'text', text: `${answer}\n\n(assembled from ${sourceCount} record${sourceCount === 1 ? '' : 's'})${tail}` }] }
+    },
+  )
+
+  server.registerTool(
+    'set_record_privacy',
+    {
+      title: 'Set a record\'s privacy tier',
+      description: 'Reclassify the access tier of one of YOUR OWN records: "accessible" (anyone in the org), "scoped" (you + your management chain), or "confidential" (you + people you explicitly grant access). Get record_id from a `story` result\'s Sources list. Only affects records you own — others return an error.',
+      inputSchema: {
+        record_id: z.string().describe('the record id (uuid), taken from a story result source'),
+        privacy: z.enum(['accessible', 'scoped', 'confidential']).describe('the new access tier'),
+      },
+    },
+    async ({ record_id, privacy }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/records/${record_id}`, {
+          method: 'PATCH',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ privacy }),
+        })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not set privacy: ${e.message}` }] }
+      }
+      if (!res.ok) {
+        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+        return { content: [{ type: 'text', text: `Could not set privacy: ${d.message}` }] }
+      }
+      const out = await res.json()
+      return { content: [{ type: 'text', text: `Done — record ${out.id} is now "${out.privacy}".` }] }
+    },
+  )
+
   await server.connect(new StdioServerTransport())
 }

package/lib/setup.mjs

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from 'fs'
 import { homedir } from 'os'
 import { join, dirname } from 'path'
+import { checkToken } from './diagnose.mjs'
 
 // One-command employee onboarding. Wires both:
 //   1. ~/.claude.json        → the cortex MCP server (context-serving)
@@ -31,7 +32,7 @@ function ensureDir(path) {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
 }
 
-export function runSetup(argv) {
+export async function runSetup(argv) {
   const token = argv[0]
   if (!token || token.startsWith('-')) {
     process.stderr.write(
@@ -104,9 +105,24 @@ export function runSetup(argv) {
     process.exit(1)
   }
 
+  // ── 3. Self-verify — writing config proves "files written", NOT "connection works".
+  // Actually call the API so a bad/expired token is caught HERE, not 40 minutes into debugging.
   log('')
-  log('Done. Restart Claude Code, then your AI will see your Cortex context')
-  log('and your sessions will flow into the org automatically.')
-  log(`Console: ${base}`)
+  log('Verifying your token against Cortex…')
+  const health = await checkToken(token, base)
+  if (health.ok) {
+    const n = health.projectCount
+    log(`  ✓ Verified — your token works${typeof n === 'number' ? ` (you can see ${n} project${n === 1 ? '' : 's'})` : ''}.`)
+  } else {
+    log('  ⚠ Config written, but the live check did NOT pass:')
+    log(`     ${health.diagnosis?.message ?? 'unknown error'}`)
+    log('     The files are in place; fix the above, then re-check with `doctor`.')
+  }
+
+  log('')
+  log('⟳ IMPORTANT: fully quit and reopen Claude Code to load the Cortex server.')
+  log('   Then your AI sees your Cortex context and your sessions flow into the org.')
+  log('   Re-check anytime:  npx -y @theronap/cortex-mcp doctor')
+  log(`   Console: ${base}`)
   log('')
 }

package/package.json

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