@theronap/cortex-mcp 0.9.42 → 0.9.44

package/bin/cortex-mcp.mjs

@@ -115,7 +115,7 @@ if (cmd === 'setup') {
   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).
+  // Ranked keyword (fts) search by default; --substring/--literal for exact lookups. 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')

package/lib/grep_cli.mjs

@@ -5,16 +5,20 @@ import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 // Output is ASCII-only (outbound-message convention).
 
 // Pure: parse argv after `grep` → { query, mode, max }.
-//   cortex grep <terms...> [--mode fts | --fts] [--max N]
+//   cortex grep <terms...> [--substring | --literal] [--max N]
+// Default mode is 'fts' (ranked keyword — multi-word queries work); pass --substring/--literal for
+// an exact literal match (identifiers, [[links]], code). (#220)
 export function parseGrepArgs(argv = []) {
-  const out = { query: '', mode: 'substring', max: undefined }
+  const out = { query: '', mode: 'fts', 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'
+      out.mode = argv[++i] === 'substring' ? 'substring' : 'fts'
     } else if (a === '--fts') {
       out.mode = 'fts'
+    } else if (a === '--substring' || a === '--literal') {
+      out.mode = 'substring'
     } else if (a === '--max') {
       const n = Number(argv[++i])
       if (Number.isFinite(n)) out.max = Math.trunc(n)
@@ -50,7 +54,7 @@ export async function runGrep(rest = []) {
   }
   const { query, mode, max } = parseGrepArgs(rest)
   if (!query) {
-    process.stderr.write('usage: cortex grep <query> [--mode fts] [--max N]\n')
+    process.stderr.write('usage: cortex grep <query> [--substring|--literal] [--max N]\n')
     return 1
   }
   const qs = new URLSearchParams({ q: query, mode })

package/lib/grep_cli.test.mjs

@@ -2,13 +2,17 @@ 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 })
+  // #220: default is 'fts' (ranked keyword); --substring/--literal opts back into exact matching.
+  it('joins free terms into the query, defaults fts', () => {
+    expect(parseGrepArgs(['hello', 'world'])).toEqual({ query: 'hello world', mode: 'fts', max: undefined })
   })
-  it('honors --mode fts and --fts', () => {
+  it('honors --substring/--literal to force exact matching, else fts', () => {
+    expect(parseGrepArgs(['q', '--substring']).mode).toBe('substring')
+    expect(parseGrepArgs(['q', '--literal']).mode).toBe('substring')
+    expect(parseGrepArgs(['q', '--mode', 'substring']).mode).toBe('substring')
     expect(parseGrepArgs(['q', '--mode', 'fts']).mode).toBe('fts')
     expect(parseGrepArgs(['--fts', 'q']).mode).toBe('fts')
-    expect(parseGrepArgs(['q', '--mode', 'bogus']).mode).toBe('substring')
+    expect(parseGrepArgs(['q', '--mode', 'bogus']).mode).toBe('fts')
   })
   it('parses --max as an integer, ignores non-numeric', () => {
     expect(parseGrepArgs(['q', '--max', '25']).max).toBe(25)

package/lib/server.mjs

@@ -190,11 +190,17 @@ export async function runServer(version) {
     'timeline_pull',
     {
       title: 'Pull unattributed messaging threads to triage',
-      description: "Surface messaging threads captured in the org (email, etc.) that AREN'T yet attributed to a project — the backlog awaiting your judgment. Call it as you work; when you recognize which KNOWN project a surfaced thread is about, attribute it with attribute_thread. Threads you don't recognize: leave them (they self-heal as the graph fills). Returns participants + subject + recency per thread — enough to recognize, not the message bodies.",
-      inputSchema: { limit: z.number().optional().describe('max threads to return (default 20)') },
+      description: "Surface messaging threads captured in the org (email, etc.) that AREN'T yet attributed to a project — the backlog awaiting your judgment. Call it as you work; when you recognize which KNOWN project a surfaced thread is about, attribute it with attribute_thread. Threads you don't recognize: leave them (they self-heal as the graph fills). Pass a `project` you're working on to RANK the backlog by relevance (threads sharing participants with that project come first, marked ★). Returns participants + subject + recency per thread — enough to recognize, not the message bodies.",
+      inputSchema: {
+        limit: z.number().optional().describe('max threads to return (default 20)'),
+        project: z.string().optional().describe('optional KNOWN project slug to rank the backlog by relevance to what you are working on; omit for the whole backlog newest-first'),
+      },
     },
-    async ({ limit }) => {
-      const qs = typeof limit === 'number' ? `?limit=${limit}` : ''
+    async ({ limit, project }) => {
+      const params = new URLSearchParams()
+      if (typeof limit === 'number') params.set('limit', String(limit))
+      if (typeof project === 'string' && project) params.set('project', project)
+      const qs = params.toString() ? `?${params}` : ''
       const res = await fetchCortex(`${BASE}/api/timeline/pull${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       if (!res.ok) {
         const body = await res.text()
@@ -205,9 +211,13 @@ export async function runServer(version) {
       const lines = threads.map((t) => {
         const who = (t.participants ?? []).map((p) => String(p).replace(/^email:/, '')).join(', ')
         const when = t.lastAt ? String(t.lastAt).slice(0, 10) : '—'
-        return `- ${t.threadKey} — ${t.subject ?? '(no subject)'} · ${who || 'unknown participants'} · ${t.eventCount} msg · ${when}`
+        const rel = t.relevance && t.relevance.score > 0 ? ` · ★${t.relevance.score} ${t.relevance.reason}` : ''
+        return `- ${t.threadKey} — ${t.subject ?? '(no subject)'} · ${who || 'unknown participants'} · ${t.eventCount} msg · ${when}${rel}`
       })
-      return { content: [{ type: 'text', text: `Unattributed threads (${threads.length}) — attribute recognized ones with attribute_thread(threadKey, project):\n${lines.join('\n')}` }] }
+      const header = project
+        ? `Unattributed threads (${threads.length}), ranked for project:${project} (★ = shares participants)`
+        : `Unattributed threads (${threads.length})`
+      return { content: [{ type: 'text', text: `${header} — attribute recognized ones with attribute_thread(threadKey, project):\n${lines.join('\n')}` }] }
     },
   )
 
@@ -256,14 +266,14 @@ export async function runServer(version) {
     {
       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]].',
+        'Ranked keyword search across your visible brain wiki pages. Multi-word natural-language queries work (results are ranked by relevance). Pass mode:"substring" for an exact literal match of symbols, identifiers, or [[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)"),
+        query: z.string().describe('search terms (natural language is fine)'),
+        mode: z.enum(['substring', 'fts']).optional().describe("'fts' (default, ranked keyword) or 'substring' (exact literal — for identifiers / [[links]] / code)"),
       },
     },
     async ({ query, mode }) => {
-      const qs = new URLSearchParams({ q: query, mode: mode === 'fts' ? 'fts' : 'substring' })
+      const qs = new URLSearchParams({ q: query, mode: mode === 'substring' ? 'substring' : 'fts' })
       const res = await fetchCortex(`${BASE}/api/grep?${qs.toString()}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       if (!res.ok) {
         const body = await res.text()

package/package.json

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