@theronap/cortex-mcp 0.1.0 → 0.4.0

package/bin/cortex-mcp.mjs

@@ -2,103 +2,63 @@
 /**
  * cortex-mcp — connect your AI assistant to Cortex.
  *
- * Zero-install usage. Add to your Claude Code config (~/.claude.json mcpServers):
+ * 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
  *
- *   "cortex": {
- *     "command": "npx",
- *     "args": ["-y", "cortex-mcp"],
- *     "env": { "CORTEX_TOKEN": "<your-personal-token>" }
- *   }
+ * Zero-install onboarding:
+ *   npx -y @theronap/cortex-mcp setup <your-token>
  *
- * Get your CORTEX_TOKEN from the Cortex console → Connect your AI.
- *
- * Env:
- *   CORTEX_TOKEN  (required) your personal token — identifies you + your org
- *   CORTEX_URL    (optional) defaults to https://cortex-console.vercel.app
+ * Get your token from the Cortex console → Connect your AI.
  */
 
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { z } from 'zod'
+const VERSION = '0.4.0'
+const cmd = process.argv[2]
+const rest = process.argv.slice(3)
+
+if (cmd === '--version' || cmd === '-v') {
+  process.stdout.write(`cortex-mcp ${VERSION}\n`)
+  process.exit(0)
+}
 
-const VERSION = '0.1.0'
-const arg = process.argv[2]
-if (arg === '--version' || arg === '-v') { process.stdout.write(`cortex-mcp ${VERSION}\n`); process.exit(0) }
-if (arg === '--help' || arg === '-h') {
+if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
   process.stdout.write(
     `cortex-mcp ${VERSION} — connect your AI assistant to Cortex\n\n` +
-    `Set CORTEX_TOKEN (from the Cortex console → Connect your AI) and run via your\n` +
-    `MCP client. Optional CORTEX_URL overrides the API base.\n\n` +
-    `Claude Code config:\n` +
-    `  "cortex": { "command": "npx", "args": ["-y", "cortex-mcp"],\n` +
-    `              "env": { "CORTEX_TOKEN": "..." } }\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` +
+    `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`,
   )
   process.exit(0)
 }
 
-const TOKEN = process.env.CORTEX_TOKEN
-const BASE = (process.env.CORTEX_URL ?? 'https://cortex-console.vercel.app').replace(/\/$/, '')
-
-if (!TOKEN) {
-  process.stderr.write('cortex-mcp: CORTEX_TOKEN is required. Get yours from the Cortex console → Connect your AI.\n')
-  process.exit(1)
+if (cmd === 'setup') {
+  const { runSetup } = await import('../lib/setup.mjs')
+  await runSetup(rest)
+  process.exit(0)
 }
 
-// Cache context for 5 minutes so repeated tool calls don't re-fetch.
-let cache = null
-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}` } })
-  if (!res.ok) {
-    let detail = 'unknown'
-    try { detail = (await res.json()).error ?? detail } catch { /* ignore */ }
-    throw new Error(`Cortex API ${res.status}: ${detail}`)
-  }
-  const { context } = await res.json()
-  cache = { text: context, ts: now }
-  return context
+if (cmd === 'doctor') {
+  const { runDoctor } = await import('../lib/doctor.mjs')
+  process.exit(await runDoctor())
 }
 
-const server = new McpServer({ name: 'cortex', version: VERSION })
-
-server.registerTool(
-  'my_context',
-  {
-    title: 'My Cortex context',
-    description: 'Your current work context from the org — your projects, recent activity, gaps, and any directives from leadership. Scoped to what you are permitted to see.',
-    inputSchema: {},
-  },
-  async () => ({ content: [{ type: 'text', text: await fetchContext() }] }),
-)
-
-server.registerTool(
-  'search_org',
-  {
-    title: 'Search the org',
-    description: 'Search your visible work activity and projects by keyword.',
-    inputSchema: { query: z.string().describe('keyword to search for') },
-  },
-  async ({ query }) => {
-    const text = await fetchContext()
-    const q = query.toLowerCase()
-    const lines = text.split('\n').filter((l) => l.toLowerCase().includes(q))
-    return { content: [{ type: 'text', text: lines.length ? `Matches for "${query}":\n${lines.join('\n')}` : `No visible results for "${query}".` }] }
-  },
-)
-
-server.registerTool(
-  'project_status',
-  {
-    title: 'Project status',
-    description: 'Status of a specific project by key (e.g. checkout-v2). Returns only what you can see.',
-    inputSchema: { key: z.string().describe('project key, e.g. checkout-v2') },
-  },
-  async ({ key }) => {
-    const text = await fetchContext()
-    const line = text.split('\n').find((l) => l.includes(`**${key}**`) || l.includes(key))
-    return { content: [{ type: 'text', text: line ? `Project ${key}:\n${line.trim()}` : `No visible project "${key}".` }] }
-  },
-)
+if (cmd === 'capture') {
+  const { runCapture } = await import('../lib/capture.mjs')
+  await runCapture()
+  process.exit(0)
+}
 
-await server.connect(new StdioServerTransport())
+// Default: run the MCP server.
+const { runServer } = await import('../lib/server.mjs')
+await runServer(VERSION)

package/lib/capture.mjs

@@ -0,0 +1,71 @@
+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
+// (no bun, no repo clone). Always exits 0 — capture must never break a session.
+
+function readStdin() {
+  try { return readFileSync(0, 'utf8') } catch { return '' }
+}
+
+// Claude transcripts are JSONL; pull human-readable text from the tail so the
+// server has real content to summarize (not raw tool JSON).
+function transcriptTail(path) {
+  let raw = ''
+  try { raw = readFileSync(path, 'utf8') } catch { return '' }
+  const lines = raw.split('\n').filter(Boolean).slice(-60)
+  const texts = []
+  for (const line of lines) {
+    try {
+      const obj = JSON.parse(line)
+      const content = obj?.message?.content ?? obj?.content
+      if (typeof content === 'string') texts.push(content)
+      else if (Array.isArray(content)) {
+        for (const c of content) if (c?.type === 'text' && c.text) texts.push(c.text)
+      }
+    } catch { /* skip non-JSON */ }
+  }
+  return texts.join('\n').slice(-6000)
+}
+
+export async function runCapture() {
+  const token = process.env.CORTEX_TOKEN
+  if (!token) { process.stderr.write('cortex: CORTEX_TOKEN not set, skipping\n'); return }
+  const base = (process.env.CORTEX_URL ?? 'https://cortex-console.vercel.app').replace(/\/$/, '')
+
+  let hook = {}
+  try { hook = JSON.parse(readStdin()) } catch { /* no/invalid stdin */ }
+  const repo = hook.cwd?.split('/').filter(Boolean).pop() ?? 'general'
+  const transcript = hook.transcript_path ? transcriptTail(hook.transcript_path) : ''
+
+  if (!transcript && !hook.session_id) { process.stderr.write('cortex: empty session, skipping\n'); return }
+
+  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 {
+    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

@@ -0,0 +1,136 @@
+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.
+
+export async function runServer(version) {
+  const TOKEN = process.env.CORTEX_TOKEN
+  const BASE = (process.env.CORTEX_URL ?? 'https://cortex-console.vercel.app').replace(/\/$/, '')
+
+  if (!TOKEN) {
+    process.stderr.write('cortex-mcp: CORTEX_TOKEN is required. Get yours from the Cortex console → Connect your AI.\n')
+    process.exit(1)
+  }
+
+  // Cache context for 5 minutes so repeated tool calls don't re-fetch.
+  let cache = null
+  async function fetchContext() {
+    const now = Date.now()
+    if (cache && now - cache.ts < 5 * 60 * 1000) return cache.text
+    // 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) {
+      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 }
+    return context
+  }
+
+  const server = new McpServer({ name: 'cortex', version })
+
+  server.registerTool(
+    'my_context',
+    {
+      title: 'My Cortex context',
+      description: 'Your current work context from the org — your projects, recent activity, gaps, and any directives from leadership. Scoped to what you are permitted to see.',
+      inputSchema: {},
+    },
+    async () => ({ content: [{ type: 'text', text: await fetchContext() }] }),
+  )
+
+  server.registerTool(
+    'search_org',
+    {
+      title: 'Search the org',
+      description: 'Search your visible work activity and projects by keyword.',
+      inputSchema: { query: z.string().describe('keyword to search for') },
+    },
+    async ({ query }) => {
+      const text = await fetchContext()
+      const q = query.toLowerCase()
+      const lines = text.split('\n').filter((l) => l.toLowerCase().includes(q))
+      return { content: [{ type: 'text', text: lines.length ? `Matches for "${query}":\n${lines.join('\n')}` : `No visible results for "${query}".` }] }
+    },
+  )
+
+  server.registerTool(
+    'project_status',
+    {
+      title: 'Project status',
+      description: 'Status of a specific project by key (e.g. checkout-v2). Returns only what you can see.',
+      inputSchema: { key: z.string().describe('project key, e.g. checkout-v2') },
+    },
+    async ({ key }) => {
+      const text = await fetchContext()
+      const line = text.split('\n').find((l) => l.includes(`**${key}**`) || l.includes(key))
+      return { content: [{ type: 'text', text: line ? `Project ${key}:\n${line.trim()}` : `No visible project "${key}".` }] }
+    },
+  )
+
+  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

@@ -0,0 +1,128 @@
+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)
+//   2. ~/.claude/settings.json → the capture Stop hook (activity ingest)
+//
+// Safe by construction: backs up each file before touching it, validates JSON,
+// merges into existing structures (never clobbers other MCP servers / hooks),
+// and is idempotent (re-running just updates the cortex entries in place).
+
+const PKG = '@theronap/cortex-mcp'
+
+function readJson(path) {
+  if (!existsSync(path)) return {}
+  const raw = readFileSync(path, 'utf8').trim()
+  if (!raw) return {}
+  return JSON.parse(raw) // throws on malformed — caller handles
+}
+
+function backup(path) {
+  if (!existsSync(path)) return null
+  const bak = `${path}.cortex-bak`
+  copyFileSync(path, bak)
+  return bak
+}
+
+function ensureDir(path) {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+}
+
+export async function runSetup(argv) {
+  const token = argv[0]
+  if (!token || token.startsWith('-')) {
+    process.stderr.write(
+      'Usage: npx @theronap/cortex-mcp setup <CORTEX_TOKEN>\n\n' +
+      'Get your token from the Cortex console → Connect your AI.\n'
+    )
+    process.exit(1)
+  }
+  const base = process.env.CORTEX_URL ?? 'https://cortex-console.vercel.app'
+  const home = homedir()
+  const claudeJson = join(home, '.claude.json')
+  const settingsJson = join(home, '.claude', 'settings.json')
+
+  const log = (m) => process.stdout.write(m + '\n')
+  log('')
+  log('Cortex setup — wiring your AI assistant…')
+
+  // ── 1. MCP server in ~/.claude.json ──────────────────────────────────────
+  try {
+    let cfg
+    try { cfg = readJson(claudeJson) } catch (e) {
+      process.stderr.write(`\n✗ ${claudeJson} is not valid JSON — fix or remove it, then re-run.\n`)
+      process.exit(1)
+    }
+    const bak = backup(claudeJson)
+    cfg.mcpServers = cfg.mcpServers ?? {}
+    cfg.mcpServers.cortex = {
+      type: 'stdio',
+      command: 'npx',
+      args: ['-y', PKG],
+      env: { CORTEX_TOKEN: token },
+    }
+    ensureDir(claudeJson)
+    writeFileSync(claudeJson, JSON.stringify(cfg, null, 2))
+    log(`  ✓ MCP server → ${claudeJson}${bak ? ' (backup saved)' : ''}`)
+  } catch (e) {
+    process.stderr.write(`  ✗ failed to update ${claudeJson}: ${e.message}\n`)
+    process.exit(1)
+  }
+
+  // ── 2. Capture Stop hook in ~/.claude/settings.json ──────────────────────
+  try {
+    let s
+    try { s = readJson(settingsJson) } catch (e) {
+      process.stderr.write(`\n✗ ${settingsJson} is not valid JSON — fix or remove it, then re-run.\n`)
+      process.exit(1)
+    }
+    const bak = backup(settingsJson)
+    s.hooks = s.hooks ?? {}
+    s.hooks.Stop = Array.isArray(s.hooks.Stop) ? s.hooks.Stop : []
+
+    const captureCmd = `CORTEX_TOKEN=${token} npx -y ${PKG} capture`
+    // Remove any prior cortex capture hook (idempotent: drop old token / old path forms).
+    for (const grp of s.hooks.Stop) {
+      if (Array.isArray(grp.hooks)) {
+        grp.hooks = grp.hooks.filter((h) => !/cortex-mcp.*capture|capture-session-cloud/.test(h.command ?? ''))
+      }
+    }
+    // Find or create a matcher:"" group and append.
+    let grp = s.hooks.Stop.find((g) => (g.matcher ?? '') === '')
+    if (!grp) { grp = { matcher: '', hooks: [] }; s.hooks.Stop.push(grp) }
+    grp.hooks = grp.hooks ?? []
+    grp.hooks.push({ type: 'command', command: captureCmd })
+
+    ensureDir(settingsJson)
+    writeFileSync(settingsJson, JSON.stringify(s, null, 2))
+    log(`  ✓ Capture hook → ${settingsJson}${bak ? ' (backup saved)' : ''}`)
+  } catch (e) {
+    process.stderr.write(`  ✗ failed to update ${settingsJson}: ${e.message}\n`)
+    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('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,13 +1,14 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.1.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": {
     "cortex-mcp": "bin/cortex-mcp.mjs"
   },
   "files": [
-    "bin"
+    "bin",
+    "lib"
   ],
   "engines": {
     "node": ">=18"