@theronap/cortex-mcp 0.1.0 → 0.2.0

package/bin/cortex-mcp.mjs

@@ -2,103 +2,56 @@
 /**
  * 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
+ *   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.2.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` +
+    `  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')
+  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 === 'capture') {
+  const { runCapture } = await import('../lib/capture.mjs')
+  await runCapture()
+  process.exit(0)
 }
 
-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}".` }] }
-  },
-)
-
-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,62 @@
+import { readFileSync } from 'fs'
+
+// 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 }
+
+  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) {
+    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`)
+  }
+}

package/lib/server.mjs

@@ -0,0 +1,75 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+
+// 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
+    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
+  }
+
+  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}".` }] }
+    },
+  )
+
+  await server.connect(new StdioServerTransport())
+}

package/lib/setup.mjs

@@ -0,0 +1,112 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from 'fs'
+import { homedir } from 'os'
+import { join, dirname } from 'path'
+
+// 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 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)
+  }
+
+  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('')
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.1.0",
+  "version": "0.2.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"