@theronap/cortex-mcp 0.4.6 → 0.7.0

package/bin/cortex-mcp.mjs

@@ -16,7 +16,7 @@
  * Get your token from the Cortex console → Connect your AI.
  */
 
-const VERSION = '0.4.6'
+const VERSION = '0.6.0'
 const cmd = process.argv[2]
 const rest = process.argv.slice(3)
 
@@ -36,6 +36,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  setup <token>   wire MCP server + capture hook into ~/.claude config\n` +
     `  doctor          live health check — confirm your token works (no restart needed)\n` +
     `  status          one-line connected/not-connected check (used by the SessionStart hook)\n` +
+    `  skills          install/repair the managed Cortex skills (also wired by setup)\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`,
@@ -71,6 +72,10 @@ if (cmd === 'setup') {
   await runCapture()
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'skills') {
+  // Install / repair the managed Cortex skills repository. No network — exits naturally.
+  const { runSkills } = await import('../lib/skills.mjs')
+  process.exitCode = await runSkills(rest)
 } else {
   // Default: run the MCP server (stays alive; never exits).
   const { runServer } = await import('../lib/server.mjs')

package/lib/server.mjs

@@ -1,6 +1,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod'
+import { writeFileSync, mkdirSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
 import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 
 // The Cortex MCP server (stdio). Serves the signed-in employee's scoped org
@@ -49,13 +52,32 @@ export async function runServer(version) {
     {
       title: 'Search the org',
       description: 'Search your visible work activity and projects by keyword.',
-      inputSchema: { query: z.string().describe('keyword to search for') },
+      inputSchema: { query: z.string().describe('keyword to search for — people or work activity') },
     },
     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}".` }] }
+      // Real search via /api/search: records (RLS-scoped retrieve) + graph entities (people),
+      // instead of substring-grepping the cached context. People were previously invisible to search.
+      const res = await fetchCortex(`${BASE}/api/search?q=${encodeURIComponent(query)}`, { 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 { people = [], records = [] } = await res.json()
+      if (!people.length && !records.length) return { content: [{ type: 'text', text: `No visible results for "${query}".` }] }
+      const lines = []
+      if (people.length) {
+        lines.push('People:')
+        for (const p of people) {
+          const meta = [p.title, p.company].filter(Boolean).join(', ')
+          lines.push(`- ${p.name}${meta ? ` (${meta})` : ''} — mentioned in ${p.mentions} record${p.mentions === 1 ? '' : 's'}`)
+        }
+      }
+      if (records.length) {
+        if (lines.length) lines.push('')
+        lines.push('Activity:')
+        for (const r of records) lines.push(`- [${r.source}] ${r.title}${r.project ? ` (${r.project})` : ''}`)
+      }
+      return { content: [{ type: 'text', text: `Results for "${query}":\n${lines.join('\n')}` }] }
     },
   )
 
@@ -160,5 +182,101 @@ export async function runServer(version) {
     },
   )
 
+  // ── File requests: ask the owner for a record's FULL original (lives on their machine) ──
+  const fail = (verb, res) => async () =>
+    ({ content: [{ type: 'text', text: `Could not ${verb}: ${classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id')).message}` }] })
+
+  server.registerTool(
+    'request_file',
+    {
+      title: 'Request the full original of a record',
+      description: 'You have a record\'s SUMMARY but want the full original file (it lives on the owner\'s machine). This asks the owner to share it; once they approve, fetch it with get_file. Get record_id from a story Sources list or the "id:" on a my_context activity line.',
+      inputSchema: { record_id: z.string().describe('the record id (uuid)') },
+    },
+    async ({ record_id }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/file-requests`, {
+          method: 'POST', headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ recordId: record_id }),
+        })
+      } catch (e) { return { content: [{ type: 'text', text: `Could not request: ${e.message}` }] } }
+      if (res.status === 409) {
+        const j = await res.json().catch(() => ({}))
+        if (j.error === 'you_own_it') return { content: [{ type: 'text', text: `You own this record — open the original directly:\n${j.uri}` }] }
+        if (j.error === 'no_original') return { content: [{ type: 'text', text: 'This record has no retrievable original.' }] }
+      }
+      if (!res.ok) return (await fail('request the file', res))()
+      const { request } = await res.json()
+      return { content: [{ type: 'text', text: `Requested. The owner will be asked to approve. Check status with file_requests; once approved + fulfilled, run get_file ${request.id}.` }] }
+    },
+  )
+
+  server.registerTool(
+    'file_requests',
+    {
+      title: 'My file requests + approval inbox',
+      description: 'Lists file requests you made (with status) and requests from others awaiting YOUR approval. Approve/deny with decide_file_request; fetch an approved+fulfilled file with get_file.',
+      inputSchema: {},
+    },
+    async () => {
+      let res
+      try { res = await fetchCortex(`${BASE}/api/file-requests`, { headers: { Authorization: `Bearer ${TOKEN}` } }) }
+      catch (e) { return { content: [{ type: 'text', text: `Could not load file requests: ${e.message}` }] } }
+      if (!res.ok) return (await fail('load file requests', res))()
+      const { mine, inbox } = await res.json()
+      const parts = []
+      if (inbox?.length) parts.push('Awaiting YOUR approval:\n' + inbox.map((r) => `  - [${r.id}] ${r.requester} wants "${r.title}" (${r.source}) → decide_file_request ${r.id}`).join('\n'))
+      if (mine?.length) parts.push('Your requests:\n' + mine.map((r) => `  - [${r.id}] "${r.title}" — ${r.status}${r.status === 'fulfilled' ? ` → get_file ${r.id}` : ''}`).join('\n'))
+      return { content: [{ type: 'text', text: parts.length ? parts.join('\n\n') : 'No file requests.' }] }
+    },
+  )
+
+  server.registerTool(
+    'decide_file_request',
+    {
+      title: 'Approve or deny a file request',
+      description: 'As the OWNER of a record, approve or deny someone\'s request for its full original. On approve, your Cortex desktop app fetches + shares the file. Get request_id from file_requests.',
+      inputSchema: { request_id: z.string(), decision: z.enum(['approve', 'deny']) },
+    },
+    async ({ request_id, decision }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/file-requests/${request_id}/decide`, {
+          method: 'POST', headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ action: decision }),
+        })
+      } catch (e) { return { content: [{ type: 'text', text: `Could not decide: ${e.message}` }] } }
+      if (!res.ok) return (await fail('decide', res))()
+      return { content: [{ type: 'text', text: `Request ${decision === 'approve' ? 'approved' : 'denied'}.` }] }
+    },
+  )
+
+  server.registerTool(
+    'get_file',
+    {
+      title: 'Download an approved file',
+      description: 'Download the full original for a request the owner approved + fulfilled. Saves it under ~/Downloads/cortex/ and returns the local path.',
+      inputSchema: { request_id: z.string() },
+    },
+    async ({ request_id }) => {
+      let res
+      try { res = await fetchCortex(`${BASE}/api/file-requests/${request_id}/download`, { headers: { Authorization: `Bearer ${TOKEN}` } }) }
+      catch (e) { return { content: [{ type: 'text', text: `Could not download: ${e.message}` }] } }
+      if (res.status === 409) return { content: [{ type: 'text', text: 'Not ready — the owner hasn\'t fulfilled this yet. Try again after they approve.' }] }
+      if (res.status === 410) return { content: [{ type: 'text', text: 'This file has expired (downloads are available for 7 days). Request it again.' }] }
+      if (!res.ok) return (await fail('download', res))()
+      const buf = Buffer.from(await res.arrayBuffer())
+      const cd = res.headers.get('content-disposition') ?? ''
+      const m = /filename="([^"]+)"/.exec(cd)
+      const name = (m ? m[1] : `cortex-file-${request_id}`).replace(/[^\w.\- ]/g, '_')
+      const dir = join(homedir(), 'Downloads', 'cortex')
+      mkdirSync(dir, { recursive: true })
+      const path = join(dir, name)
+      writeFileSync(path, buf)
+      return { content: [{ type: 'text', text: `Saved the full original to ${path} (${buf.length} bytes).` }] }
+    },
+  )
+
   await server.connect(new StdioServerTransport())
 }

package/lib/setup.mjs

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from
 import { homedir } from 'os'
 import { join, dirname } from 'path'
 import { checkToken, resolveBase } from './diagnose.mjs'
+import { installSkills } from './skills.mjs'
 
 // One-command employee onboarding. Wires both:
 //   1. ~/.claude.json        → the cortex MCP server (context-serving)
@@ -115,6 +116,16 @@ export async function runSetup(argv, version) {
     sgrp.hooks = sgrp.hooks ?? []
     sgrp.hooks.push({ type: 'command', command: statusCmd })
 
+    // Skills self-heal: every session start, restore any drifted managed Cortex skill (quiet — only
+    // speaks up if it actually changed something). This is what makes the core skills "inalterable".
+    const skillsCmd = `npx -y ${spec} skills --repair --quiet`
+    for (const sg of s.hooks.SessionStart) {
+      if (Array.isArray(sg.hooks)) {
+        sg.hooks = sg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? skills/.test(h.command ?? ''))
+      }
+    }
+    sgrp.hooks.push({ type: 'command', command: skillsCmd })
+
     ensureDir(settingsJson)
     writeFileSync(settingsJson, JSON.stringify(s, null, 2))
     log(`  ✓ Capture hook + status line → ${settingsJson}${bak ? ' (backup saved)' : ''}`)
@@ -123,7 +134,15 @@ export async function runSetup(argv, version) {
     process.exit(1)
   }
 
-  // ── 3. Self-verify — writing config proves "files written", NOT "connection works".
+  // ── 3. Managed skills repository (~/.claude/skills/cortex/) ──────────────
+  try {
+    installSkills({ quiet: false })
+  } catch (e) {
+    // Non-fatal: a skills hiccup must never block the core connection. Repair runs each session.
+    log(`  ⚠ skills install skipped: ${e.message} (will retry on next session)`)
+  }
+
+  // ── 4. 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…')

package/lib/skills.mjs

@@ -0,0 +1,121 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync } from 'fs'
+import { homedir } from 'os'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+// Managed Cortex skills repository.
+//
+// Cortex owns a namespace under the user's Claude skills dir: ~/.claude/skills/cortex/
+//   cortex/
+//     README.md                  ← explains the namespace is Cortex-managed
+//     .cortex-manifest.json       ← what's managed + content hashes (machine-readable)
+//     core/<name>/SKILL.md        ← MANDATORY, self-healing skills shipped in this package
+//     (org/ and shared/ are reserved for server-synced skills — not yet populated)
+//
+// "Inalterable" in practice: the bundled core skills are the source of truth. On every install AND
+// on every session start (the SessionStart --repair hook), any core skill whose on-disk content
+// drifted from the bundled source is RESTORED — the user's version is backed up to <file>.user-bak
+// first, so nothing is lost, but the canonical skill always wins. Idempotent: identical content is a
+// no-op (no backup, no write, no churn).
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const BUNDLED = join(HERE, '..', 'skills') // packages/cortex-mcp/skills/<name>/SKILL.md
+
+// djb2 — tiny, dependency-free content fingerprint for the manifest (drift detection, not security).
+function hash(s) {
+  let h = 5381
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) >>> 0
+  return h.toString(16)
+}
+
+function ensureDir(path) {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true })
+}
+
+// Discover bundled core skills: each subdir of skills/ that contains a SKILL.md.
+function bundledSkills() {
+  if (!existsSync(BUNDLED)) return []
+  return readdirSync(BUNDLED, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(join(BUNDLED, d.name, 'SKILL.md')))
+    .map((d) => ({ name: d.name, src: join(BUNDLED, d.name, 'SKILL.md') }))
+}
+
+const README = `# Cortex-managed skills
+
+This folder is owned by Cortex (\`@theronap/cortex-mcp\`). Skills under \`core/\` are **mandatory and
+self-healing**: if you edit or delete one, Cortex restores it on your next Claude session (your edited
+copy is saved as \`SKILL.md.user-bak\` first). To change a core skill, change it upstream in Cortex.
+
+- \`core/\`   — required Cortex skills, shipped and repaired by this package
+- \`org/\`    — your organization's skills (reserved; synced from Cortex)
+- \`shared/\` — skills shared across the org (reserved; synced from Cortex)
+
+Managed by: \`npx -y @theronap/cortex-mcp skills\`  ·  repaired automatically each session.
+`
+
+/**
+ * Install / repair the managed Cortex skills.
+ * @param {{ quiet?: boolean }} opts  quiet → only emit on actual change (for the SessionStart hook)
+ * @returns {{ installed: string[], repaired: string[], unchanged: string[] }}
+ */
+export function installSkills(opts = {}) {
+  const quiet = !!opts.quiet
+  const root = join(homedir(), '.claude', 'skills', 'cortex')
+  const coreDir = join(root, 'core')
+  const log = (m) => { if (!quiet) process.stdout.write(m + '\n') }
+
+  const skills = bundledSkills()
+  const result = { installed: [], repaired: [], unchanged: [] }
+  if (!skills.length) return result // nothing bundled (shouldn't happen) — never error
+
+  ensureDir(coreDir)
+  // Reserved namespaces so the structure is discoverable even before server sync exists.
+  ensureDir(join(root, 'org'))
+  ensureDir(join(root, 'shared'))
+  writeFileSync(join(root, 'README.md'), README)
+
+  const manifest = { managed: [], updated_by: 'cortex-mcp', skills: {} }
+
+  for (const sk of skills) {
+    const source = readFileSync(sk.src, 'utf8')
+    const dest = join(coreDir, sk.name, 'SKILL.md')
+    manifest.managed.push(`core/${sk.name}/SKILL.md`)
+    manifest.skills[sk.name] = hash(source)
+
+    if (!existsSync(dest)) {
+      ensureDir(dirname(dest))
+      writeFileSync(dest, source)
+      result.installed.push(sk.name)
+      continue
+    }
+    const current = readFileSync(dest, 'utf8')
+    if (current === source) { result.unchanged.push(sk.name); continue }
+
+    // Drift: preserve the user's version, then restore canonical.
+    try { copyFileSync(dest, `${dest}.user-bak`) } catch { /* best-effort backup */ }
+    writeFileSync(dest, source)
+    result.repaired.push(sk.name)
+  }
+
+  writeFileSync(join(root, '.cortex-manifest.json'), JSON.stringify(manifest, null, 2))
+
+  if (result.installed.length) log(`  ✓ Cortex skills installed: ${result.installed.join(', ')} → ${coreDir}`)
+  if (result.repaired.length) log(`  ✓ Cortex skills restored (backed up your copy): ${result.repaired.join(', ')}`)
+  if (quiet && (result.installed.length || result.repaired.length)) {
+    // SessionStart surfaces one line in Claude Code so a silent self-heal isn't invisible.
+    process.stdout.write(`Cortex: synced ${result.installed.length + result.repaired.length} managed skill(s).\n`)
+  }
+  return result
+}
+
+// CLI entry: `cortex-mcp skills [--repair] [--quiet]`. (--repair and plain install are the same
+// idempotent operation; --repair is just the name the SessionStart hook uses for intent.)
+export async function runSkills(argv = []) {
+  const quiet = argv.includes('--quiet')
+  if (!quiet) process.stdout.write('\nCortex skills — installing managed repository…\n')
+  const r = installSkills({ quiet })
+  if (!quiet && !r.installed.length && !r.repaired.length) {
+    process.stdout.write(`  ✓ Up to date (${r.unchanged.join(', ') || 'none'}).\n`)
+  }
+  return 0
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.4.6",
+  "version": "0.7.0",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "bin",
-    "lib"
+    "lib",
+    "skills"
   ],
   "engines": {
     "node": ">=18"

package/skills/log/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: cortex-log
+description: Close out a work session into Cortex — summarize what happened, confirm it reached the org, and surface anything teammates should know. Run at or near the end of any working session.
+---
+
+> **Cortex-managed skill.** This file is installed and kept up to date by Cortex. Local edits are
+> restored on the next session (a backup of your version is saved alongside). Don't rely on changes here.
+
+## When to use
+
+At the end of a Claude Code session, or after finishing a meaningful phase of work. Cortex already
+captures your sessions automatically in the background — this skill is the *deliberate* close-out: it
+produces a clean, structured summary and confirms the org received it.
+
+## Inputs
+
+No arguments. Read the conversation context.
+
+## Steps
+
+1. **Summarize the session** — what was worked on, what was decided, what changed. Be concrete: name
+   the projects, files, and people involved.
+2. **Surface org-relevant signal** — blockers, decisions, handoffs, and anyone you coordinated with.
+   These are the things a teammate or manager would want to know without reading the whole transcript.
+3. **Confirm capture** — check the Cortex MCP is connected (`my_context` returns your context). Your
+   session flows to the org automatically at session end via the capture hook; if `my_context` errors,
+   tell the user their session may not be captured and to run `npx -y @theronap/cortex-mcp doctor`.
+4. **Flag privacy** — if any record from this session should be confidential, note it so the user can
+   mark it (`set_record_privacy`). Default is org-visible under access rules.
+
+## Output
+
+A short structured summary:
+
+```markdown
+## Session summary
+
+**Worked on:** brief description
+**Decisions:** decision 1; decision 2
+**Open / blocked:** anything unresolved or waiting on someone
+**Coordinated with:** people involved
+**Capture:** ✅ flowing to Cortex  (or ⚠ not connected — run doctor)
+```
+
+## Safety rules
+
+- This skill only summarizes and reports. It never sends external messages, never deletes anything,
+  and never changes access on a record without the user explicitly asking.
+- Raw session text stays on this machine — only the summary-grade record reaches the org, scoped by
+  access rules.