@theronap/cortex-mcp 0.9.10 → 0.9.12

package/bin/cortex-mcp.mjs

@@ -90,11 +90,23 @@ if (cmd === 'setup') {
   await runCapture()
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'resolve') {
+  // Entity identity dedup: judge the server-flagged fuzzy duplicate pairs locally via `claude -p`.
+  const { runResolve } = await import('../lib/resolve.mjs')
+  await runResolve()
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
 } else if (cmd === 'ingest-folder') {
   const { runIngestFolder } = await import('../lib/ingest_folder.mjs')
   await runIngestFolder(rest)
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'grep') {
+  // Literal substring search over the viewer's visible brain wiki (thin client of /api/grep).
+  const { runGrep } = await import('../lib/grep_cli.mjs')
+  process.exitCode = await runGrep(rest)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
 } else if (cmd === 'snapshot-context') {
   const { runSnapshotContext } = await import('../lib/context_log.mjs')
   process.exitCode = await runSnapshotContext()

package/lib/grep_cli.mjs

@@ -0,0 +1,71 @@
+import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
+
+// `cortex grep` CLI + shared formatting for the MCP grep tool (Lane B / T6). Thin client of
+// GET /api/grep — the server runs the RLS-INVOKER RPC AS the viewer, so no DB credentials live here.
+// Output is ASCII-only (outbound-message convention).
+
+// Pure: parse argv after `grep` → { query, mode, max }.
+//   cortex grep <terms...> [--mode fts | --fts] [--max N]
+export function parseGrepArgs(argv = []) {
+  const out = { query: '', mode: 'substring', max: undefined }
+  const terms = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--mode') {
+      out.mode = argv[++i] === 'fts' ? 'fts' : 'substring'
+    } else if (a === '--fts') {
+      out.mode = 'fts'
+    } else if (a === '--max') {
+      const n = Number(argv[++i])
+      if (Number.isFinite(n)) out.max = Math.trunc(n)
+    } else {
+      terms.push(a)
+    }
+  }
+  out.query = terms.join(' ').trim()
+  return out
+}
+
+// Pure: render a /api/grep payload to readable ASCII text.
+export function formatGrepHits(payload, query) {
+  const hits = (payload && payload.hits) || []
+  if (!hits.length) return `No matches for "${query}".`
+  const lines = [`${hits.length} match${hits.length === 1 ? '' : 'es'} for "${query}":`, '']
+  for (const h of hits) {
+    const head = h.heading ? ` > ${h.heading}` : ''
+    lines.push(`- ${h.title}${head} [${h.tier}]`)
+    if (h.snippet) lines.push(`    ${String(h.snippet).replace(/\s+/g, ' ').trim()}`)
+    if (h.links && h.links.length) lines.push(`    -> ${h.links.map((l) => `[[${l}]]`).join(' ')}`)
+  }
+  return lines.join('\n')
+}
+
+// Effectful: run the CLI subcommand. Returns an exit code.
+export async function runGrep(rest = []) {
+  const TOKEN = process.env.CORTEX_TOKEN
+  const BASE = resolveBase(process.env.CORTEX_URL)
+  if (!TOKEN) {
+    process.stderr.write('cortex grep: CORTEX_TOKEN is required (get yours from the Cortex console).\n')
+    return 1
+  }
+  const { query, mode, max } = parseGrepArgs(rest)
+  if (!query) {
+    process.stderr.write('usage: cortex grep <query> [--mode fts] [--max N]\n')
+    return 1
+  }
+  const qs = new URLSearchParams({ q: query, mode })
+  if (max) qs.set('max', String(max))
+  const res = await fetchCortex(`${BASE}/api/grep?${qs.toString()}`, {
+    headers: { Authorization: `Bearer ${TOKEN}` },
+  })
+  if (!res.ok) {
+    const body = await res.text()
+    process.stderr.write(
+      classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message + '\n',
+    )
+    return 1
+  }
+  const payload = await res.json()
+  process.stdout.write(formatGrepHits(payload, query) + '\n')
+  return 0
+}

package/lib/grep_cli.test.mjs

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'bun:test'
+import { parseGrepArgs, formatGrepHits } from './grep_cli.mjs'
+
+describe('parseGrepArgs', () => {
+  it('joins free terms into the query, defaults substring', () => {
+    expect(parseGrepArgs(['hello', 'world'])).toEqual({ query: 'hello world', mode: 'substring', max: undefined })
+  })
+  it('honors --mode fts and --fts', () => {
+    expect(parseGrepArgs(['q', '--mode', 'fts']).mode).toBe('fts')
+    expect(parseGrepArgs(['--fts', 'q']).mode).toBe('fts')
+    expect(parseGrepArgs(['q', '--mode', 'bogus']).mode).toBe('substring')
+  })
+  it('parses --max as an integer, ignores non-numeric', () => {
+    expect(parseGrepArgs(['q', '--max', '25']).max).toBe(25)
+    expect(parseGrepArgs(['q', '--max', 'abc']).max).toBeUndefined()
+  })
+  it('keeps the query when flags are interleaved', () => {
+    expect(parseGrepArgs(['foo', '--max', '5', 'bar']).query).toBe('foo bar')
+  })
+})
+
+describe('formatGrepHits', () => {
+  it('reports no matches', () => {
+    expect(formatGrepHits({ hits: [] }, 'xyz')).toBe('No matches for "xyz".')
+    expect(formatGrepHits({}, 'xyz')).toBe('No matches for "xyz".')
+  })
+  it('renders ASCII hit lines with heading, tier, snippet, links', () => {
+    const out = formatGrepHits(
+      { hits: [{ title: 'Acme', heading: 'Current state', tier: 'accessible', snippet: 'big   deal', links: ['Bob', 'Q3'] }] },
+      'deal',
+    )
+    expect(out).toContain('1 match for "deal":')
+    expect(out).toContain('- Acme > Current state [accessible]')
+    expect(out).toContain('    big deal')
+    expect(out).toContain('    -> [[Bob]] [[Q3]]')
+  })
+  it('is ASCII-only', () => {
+    const out = formatGrepHits({ hits: [{ title: 'X', heading: 'H', tier: 'scoped', snippet: 's', links: ['L'] }] }, 'q')
+    // eslint-disable-next-line no-control-regex
+    expect(/^[\x00-\x7F]*$/.test(out)).toBe(true)
+  })
+})

package/lib/resolve.mjs

@@ -0,0 +1,103 @@
+import { spawnSync } from 'child_process'
+import { fetchCortex, resolveBase, classify } from './diagnose.mjs'
+import { edgeSafeEnv } from './edge_extract.mjs'
+
+// `cortex-mcp resolve` — the JUDGE half of entity identity dedup (Grey harvest). The server FLAGS the
+// fuzzy band of near-duplicate non-person entities (GET /api/resolve-candidates); this command judges
+// each pair LOCALLY via `claude -p` (the engine preference — the server never calls the metered API)
+// and pushes decisions back (POST /api/resolve-apply): confident-same → entity_merges, else → rejected
+// so the pair never re-flags. Conservative by construction. Always exits cleanly.
+
+export async function runResolve() {
+  // recursion guard (we spawn `claude --print`; if its Stop hook fires capture, that no-ops on this flag)
+  if (process.env.CORTEX_SUMMARIZING) { process.stderr.write('cortex: summarizer subprocess, skipping\n'); return }
+  const token = process.env.CORTEX_TOKEN
+  if (!token) { process.stderr.write('cortex: CORTEX_TOKEN not set, skipping\n'); return }
+  const base = resolveBase(process.env.CORTEX_URL)
+
+  // 1. pull the flagged candidate pairs
+  let candidates = []
+  try {
+    const res = await fetchCortex(`${base}/api/resolve-candidates`, { headers: { Authorization: `Bearer ${token}` } })
+    if (!res.ok) {
+      const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+      process.stderr.write(`cortex: resolve-candidates failed — ${d.message}\n`); return
+    }
+    const j = await res.json().catch(() => ({}))
+    candidates = Array.isArray(j.candidates) ? j.candidates : []
+  } catch (e) { process.stderr.write(`cortex: resolve fetch failed — ${e.message}\n`); return }
+
+  if (!candidates.length) { process.stderr.write('cortex: no duplicate candidates to judge\n'); return }
+  process.stderr.write(`cortex: judging ${candidates.length} candidate pair(s) locally…\n`)
+
+  // 2. judge locally on the subscription
+  const decisions = judgeCandidates(candidates)
+  if (decisions === null) { process.stderr.write('cortex: judge unavailable (is `claude` on PATH?) — skipping\n'); return }
+
+  // 3. apply judged decisions
+  try {
+    const res = await fetchCortex(`${base}/api/resolve-apply`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ decisions }),
+    })
+    if (res.ok) {
+      const j = await res.json().catch(() => ({}))
+      process.stderr.write(`cortex: dedup — merged ${j.merged ?? 0}, rejected ${j.rejected ?? 0}, skipped ${j.skipped ?? 0}\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: resolve-apply failed — ${d.message}\n`)
+    }
+  } catch (e) { process.stderr.write(`cortex: resolve-apply failed — ${e.message}\n`) }
+}
+
+// ONE `claude --print` call judges every pair. Returns DedupDecision[] for the apply endpoint, or null
+// if the CLI is unavailable. Every judged pair (merge AND non-merge) is returned so non-merges get
+// recorded as rejected and never re-flag.
+function judgeCandidates(candidates) {
+  const list = candidates.map((c, i) =>
+    `[${i}] kind=${c.kind}\n` +
+    `  A: "${c.aName}" (e.g. record: ${c.aSample ?? 'n/a'}; ${c.aMentions} mentions)\n` +
+    `  B: "${c.bName}" (e.g. record: ${c.bSample ?? 'n/a'}; ${c.bMentions} mentions)\n` +
+    `  shared records: ${c.sharedRecords}; name similarity: ${Number(c.sim).toFixed(2)}`,
+  ).join('\n')
+  const prompt =
+    'You are deduplicating an organization knowledge graph. For each candidate pair below, decide ' +
+    'whether A and B are the SAME real-world entity (a spelling/abbreviation/variant of ONE thing) or ' +
+    'DIFFERENT things that merely have similar names. Be CONSERVATIVE: only merge when confident; when ' +
+    'in doubt, do NOT merge. Same kind only.\n' +
+    'Return ONLY a minified JSON array — one object per pair: ' +
+    '{"i":<index>,"merge":<true|false>,"confidence":<0..1>,"reason":"<short>"}.\n\n' + list
+  try {
+    const r = spawnSync(
+      'claude',
+      ['--print', '--model', process.env.CORTEX_SUMMARY_MODEL ?? 'claude-haiku-4-5', prompt],
+      { env: edgeSafeEnv(process.env, { CORTEX_SUMMARIZING: '1' }), encoding: 'utf8', timeout: 120_000, maxBuffer: 4 * 1024 * 1024 },
+    )
+    if (r.status !== 0 || !r.stdout) return null
+    return parseDecisions(r.stdout, candidates)
+  } catch {
+    return null
+  }
+}
+
+function parseDecisions(out, candidates) {
+  const start = out.indexOf('[')
+  const end = out.lastIndexOf(']')
+  if (start < 0 || end <= start) return []
+  let arr
+  try { arr = JSON.parse(out.slice(start, end + 1)) } catch { return [] }
+  if (!Array.isArray(arr)) return []
+  const decisions = []
+  for (const d of arr) {
+    const c = candidates[Number(d?.i)]
+    if (!c) continue
+    decisions.push({
+      aId: c.aId, bId: c.bId, kind: c.kind,
+      merge: !!d.merge,
+      confidence: Number(d.confidence) || 0,
+      reason: typeof d.reason === 'string' ? d.reason.slice(0, 200) : undefined,
+    })
+  }
+  return decisions
+}

package/lib/server.mjs

@@ -7,6 +7,7 @@ import { join } from 'path'
 import { createHash, randomUUID } from 'crypto'
 import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 import { runSendImessage } from './imessage_send.mjs'
+import { formatGrepHits } from './grep_cli.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.
@@ -185,6 +186,29 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'grep',
+    {
+      title: 'Grep the brain wiki',
+      description:
+        'Literal substring search across your visible brain wiki pages (matches symbols, identifiers, [[links]]). Returns matching sections with a context snippet and their outbound [[links]].',
+      inputSchema: {
+        query: z.string().describe('literal substring to find'),
+        mode: z.enum(['substring', 'fts']).optional().describe("'substring' (default, grep-like) or 'fts' (ranked keyword)"),
+      },
+    },
+    async ({ query, mode }) => {
+      const qs = new URLSearchParams({ q: query, mode: mode === 'fts' ? 'fts' : 'substring' })
+      const res = await fetchCortex(`${BASE}/api/grep?${qs.toString()}`, { 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 payload = await res.json()
+      return { content: [{ type: 'text', text: formatGrepHits(payload, query) }] }
+    },
+  )
+
   server.registerTool(
     'project_status',
     {

package/package.json

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