@theronap/cortex-mcp 0.9.45 → 0.9.47

package/bin/cortex-mcp.mjs

@@ -50,6 +50,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  skills          install/repair the managed Cortex skills — bundled + org-published (also wired by setup)\n` +
     `  skills push <file>     publish a SKILL.md to your org (owner/manager/admin)\n` +
     `  docs-scan       detect new/changed local docs pending Cortex authoring (used by /cortex-author-docs)\n` +
+    `  graphify-sync [path]  rebuild the local code graph (graphify) + log an evidence-tier timeline event\n` +
     `  snapshot-context save the exact startup context Cortex served to a local snapshot\n` +
     `  capture         Stop-hook capturer (invoked by Claude Code)\n` +
     `  ingest-folder <path>   ingest a local markdown folder as your authored records\n` +
@@ -128,6 +129,13 @@ if (cmd === 'setup') {
   process.exitCode = await runGrep(rest)
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'graphify-sync') {
+  // Local producer: `graphify update` + log an evidence-tier timeline event. Run from a cron/
+  // launchd job per repo, not a git hook (shared-checkout hazard — see reference memory).
+  const { runGraphifySync } = await import('../lib/graphify_sync.mjs')
+  process.exitCode = await runGraphifySync(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/code_graph_cli.mjs

@@ -0,0 +1,59 @@
+import { spawnSync } from 'child_process'
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+// Thin local wrapper around the `graphify` CLI's read-only query subcommands. Deliberately NOT a
+// fetchCortex client like grep/read_page: this is LOCAL-MACHINE data (a tree-sitter AST graph of
+// whatever repo the session's cwd happens to be in), not org-shared Cortex content, and it never
+// becomes the wiki graph — see cortex-wiki-primary-spec (structural/extracted data is evidence,
+// never auto-promoted into authored pages). No LLM, no network call; graphify already built the
+// graph on disk, this just queries it.
+
+function graphPath(cwd) {
+  return join(cwd, 'graphify-out', 'graph.json')
+}
+
+function hasGraphifyBinary() {
+  const r = spawnSync('graphify', ['--version'], { encoding: 'utf8', timeout: 10_000 })
+  return !r.error && r.status === 0
+}
+
+// Pure-ish: build the argv for a given action, or return an error string if params are missing.
+export function buildArgs({ action, question, from, to, node }) {
+  if (action === 'path') {
+    if (!from || !to) return { error: 'action:"path" requires both "from" and "to".' }
+    return { args: ['path', from, to] }
+  }
+  if (action === 'explain') {
+    if (!node) return { error: 'action:"explain" requires "node".' }
+    return { args: ['explain', node] }
+  }
+  if (!question) return { error: 'action:"query" requires "question".' }
+  return { args: ['query', question] }
+}
+
+// Effectful: run one of graphify's query/path/explain subcommands against the graph already built
+// for `cwd`. Returns { ok, text } — never throws, always something readable to hand back to the model.
+export function runCodeGraphQuery({ action, question, from, to, node }, cwd = process.cwd()) {
+  if (!existsSync(graphPath(cwd))) {
+    return {
+      ok: false,
+      text: `No code graph found at ${graphPath(cwd)}. Run the graphify skill (\`/graphify .\`) in this repo first to build one.`,
+    }
+  }
+  if (!hasGraphifyBinary()) {
+    return {
+      ok: false,
+      text: 'graphify CLI not found on PATH. Install it with `uv tool install graphifyy` (or `pipx install graphifyy`), then run the graphify skill to build a graph.',
+    }
+  }
+  const built = buildArgs({ action, question, from, to, node })
+  if (built.error) return { ok: false, text: built.error }
+
+  const r = spawnSync('graphify', built.args, { cwd, encoding: 'utf8', timeout: 60_000, maxBuffer: 4 * 1024 * 1024 })
+  if (r.error) return { ok: false, text: `graphify failed to run: ${r.error.message}` }
+  const out = (r.stdout || '').trim()
+  const err = (r.stderr || '').trim()
+  if (r.status !== 0) return { ok: false, text: err || out || `graphify exited with status ${r.status}` }
+  return { ok: true, text: out || '(no results)' }
+}

package/lib/graphify_sync.mjs

@@ -0,0 +1,89 @@
+import { spawnSync } from 'child_process'
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
+
+// `cortex-mcp graphify-sync [path]` — local producer: incrementally rebuild a repo's structural
+// code graph (graphify — tree-sitter AST, no LLM) and log an evidence-tier timeline event via
+// POST /api/timeline/graphify. LLM-free, idempotent (server dedupes on repo+commit), additive —
+// never touches the wiki graph (cortex-wiki-primary-spec: extracted/structural data is evidence,
+// never auto-promoted into an authored page).
+//
+// Meant to run from a periodic cron/launchd job per repo you want graphed — NOT a git post-commit
+// hook. A hook fires synchronously inside `git commit`/`git push` and can race another session's
+// git operations in a shared checkout (see reference-cortex-shared-checkout-hazards); a timer-based
+// job just reads whatever the tree looks like at that moment, no hook into git operations at all.
+
+function run(cmd, args, cwd) {
+  const r = spawnSync(cmd, args, { cwd, encoding: 'utf8', timeout: 120_000 })
+  return r.status === 0 ? (r.stdout || '').trim() : null
+}
+
+function repoFullNameFromRemote(cwd) {
+  const url = run('git', ['remote', 'get-url', 'origin'], cwd)
+  if (!url) return null
+  const m = /github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/i.exec(url)
+  return m ? `${m[1]}/${m[2]}` : null
+}
+
+export async function runGraphifySync(argv = []) {
+  const cwd = argv[0] && !argv[0].startsWith('-') ? argv[0] : process.cwd()
+  const TOKEN = process.env.CORTEX_TOKEN
+  const BASE = resolveBase(process.env.CORTEX_URL)
+  if (!TOKEN) {
+    process.stderr.write('cortex-mcp graphify-sync: CORTEX_TOKEN is required.\n')
+    return 1
+  }
+  const graphFile = join(cwd, 'graphify-out', 'graph.json')
+  if (!existsSync(graphFile)) {
+    process.stderr.write(`cortex-mcp graphify-sync: no graph at ${graphFile} — run the graphify skill (\`/graphify .\`) in this repo first.\n`)
+    return 1
+  }
+  if (!run('graphify', ['--version'], cwd)) {
+    process.stderr.write('cortex-mcp graphify-sync: graphify CLI not on PATH (`uv tool install graphifyy`).\n')
+    return 1
+  }
+
+  const update = spawnSync('graphify', ['update', '.'], { cwd, encoding: 'utf8', timeout: 300_000, maxBuffer: 8 * 1024 * 1024 })
+  if (update.status !== 0) {
+    process.stderr.write(`cortex-mcp graphify-sync: \`graphify update\` failed:\n${(update.stderr || update.stdout || '').trim()}\n`)
+    return 1
+  }
+  if (update.stdout) process.stdout.write(update.stdout.trim() + '\n')
+
+  let graph
+  try {
+    graph = JSON.parse(readFileSync(graphFile, 'utf8'))
+  } catch (e) {
+    process.stderr.write(`cortex-mcp graphify-sync: could not read ${graphFile}: ${e.message}\n`)
+    return 1
+  }
+  const nodes = Array.isArray(graph.nodes) ? graph.nodes : []
+  const nodeCount = nodes.length
+  const edgeCount = Array.isArray(graph.links) ? graph.links.length : 0
+  const communityCount = new Set(nodes.map((n) => n.community).filter((c) => c !== undefined)).size
+  const commitSha = typeof graph.built_at_commit === 'string' ? graph.built_at_commit : null
+
+  const repo = repoFullNameFromRemote(cwd)
+  if (!commitSha || !repo) {
+    process.stdout.write('cortex-mcp graphify-sync: graph updated locally; skipping timeline log (no git commit / no github.com origin found).\n')
+    return 0
+  }
+
+  const res = await fetchCortex(`${BASE}/api/timeline/graphify`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ repo, commitSha, nodeCount, edgeCount, communityCount }),
+  })
+  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(
+    `Logged to Cortex timeline: ${repo}@${commitSha.slice(0, 7)} (${nodeCount} nodes, ${edgeCount} edges, ${communityCount} communities)` +
+      `${payload.inserted ? '' : ' (already logged)'}\n`,
+  )
+  return 0
+}

package/lib/grep_cli.mjs

@@ -33,7 +33,14 @@ export function parseGrepArgs(argv = []) {
 // 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}".`
+  if (!hits.length) {
+    // Reactive red-link hint — ONLY when the query looks like a page NAME (short, no code/operators), so
+    // code and typo searches don't get nagged. read_page carries the full triage (node / new / alias).
+    const nameish = /^[\w .'-]{2,40}$/.test(query) && query.split(/\s+/).length <= 5
+    return nameish
+      ? `No matches for "${query}". If you expected a page here, it may be an unauthored red-link — \`read_page "${query}"\` to triage it (author it, or alias it to an existing page).`
+      : `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}` : ''

package/lib/server.mjs

@@ -8,6 +8,30 @@ import { createHash, randomUUID } from 'crypto'
 import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 import { runSendImessage } from './imessage_send.mjs'
 import { formatGrepHits } from './grep_cli.mjs'
+import { runCodeGraphQuery } from './code_graph_cli.mjs'
+
+// Reactive red-link triage (Mechanism 2). On a read_page miss, ask the server whether the name is a
+// tracked wanted page and whether a bare node exists for it, and turn that into an actionable 3-way
+// prompt (author-for-node / author-new / alias). Returns '' on any error so a miss never gets worse.
+async function redLinkTriage(BASE, TOKEN, name) {
+  try {
+    const r = await fetchCortex(`${BASE}/api/brain/red-link?name=${encodeURIComponent(name)}`, {
+      headers: { Authorization: `Bearer ${TOKEN}` },
+    })
+    if (!r.ok) return ''
+    const t = await r.json()
+    const refs = t.tracked
+      ? ` It's referenced by ${t.refCount} page${t.refCount === 1 ? '' : 's'}${t.isSteward ? ' and is routed to YOU as its most-likely steward' : ''}.`
+      : ''
+    const aliasHint = `if it's really an existing page under another title, \`grep "${name}"\` to find it, then \`alias_page name="${name}" target_name="<that page>"\``
+    if (t.category === 'node') {
+      return `\n\n[[${name}]] is a wanted page — a ${t.isPerson ? 'person' : 'node'} exists but has no page yet.${refs} Either author it now with \`author\`, or ${aliasHint}.`
+    }
+    return `\n\n"${name}" isn't authored anywhere yet.${refs} Either author a new page with \`author\`, or ${aliasHint}.`
+  } catch {
+    return ''
+  }
+}
 
 // The Cortex MCP server (stdio). Serves the signed-in employee's scoped org
 // context to their AI assistant. CORTEX_TOKEN identifies the user + org.
@@ -284,6 +308,26 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'code_graph_query',
+    {
+      title: 'Query the local code structure graph (graphify)',
+      description:
+        'Query a structural code graph for the repo at the CURRENT working directory, built locally by graphify (tree-sitter AST — deterministic, no LLM, no server round-trip; this is LOCAL MACHINE data, not org-shared Cortex content, and reflects a snapshot of one commit, not live files). Use for MULTI-HOP questions a single grep cannot answer: what calls/imports/depends on X, how A structurally reaches B, or a repo-wide overview (hub/community files). Do NOT use for single-hop lookups (does file X import Y) — grep is faster and always current. Structure only — it knows what imports/calls what, never WHY; read the actual files or authored Cortex pages for intent.',
+      inputSchema: {
+        action: z.enum(['query', 'path', 'explain']).describe('"query" = open-ended natural-language question (graph traversal); "path" = shortest structural path between two named nodes; "explain" = describe one node and list its direct connections'),
+        question: z.string().optional().describe('required for action:"query" — the natural-language question'),
+        from: z.string().optional().describe('required for action:"path" — the starting node name'),
+        to: z.string().optional().describe('required for action:"path" — the target node name'),
+        node: z.string().optional().describe('required for action:"explain" — the node name to describe'),
+      },
+    },
+    async ({ action, question, from, to, node }) => {
+      const result = runCodeGraphQuery({ action, question, from, to, node })
+      return { content: [{ type: 'text', text: result.text }] }
+    },
+  )
+
   server.registerTool(
     'project_status',
     {
@@ -423,7 +467,7 @@ export async function runServer(version) {
         return { content: [{ type: 'text', text: `Could not read "${name}": ${e.message}` }] }
       }
       if (res.status === 404) {
-        return { content: [{ type: 'text', text: `No ${k} page named "${name}". If it's a person or team, pass kind (person/org). Otherwise \`grep "${name}"\` to locate it — it may be a red-link (a wanted page that isn't authored yet).` }] }
+        return { content: [{ type: 'text', text: `No ${k} page named "${name}". If it's a person or team, pass kind (person/org).${await redLinkTriage(BASE, TOKEN, name)}` }] }
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
@@ -440,7 +484,7 @@ export async function runServer(version) {
         matches = [{ brain: null, authored: true, ref: page.ref, title: page.title, tiers: page.tiers }]
       }
       if (!matches.length) {
-        return { content: [{ type: 'text', text: `No authored ${k} page named "${name}" in any of your brains. If it's a person or team, pass kind (person/org). Otherwise \`grep "${name}"\` to locate it — it may be a red-link (a wanted page that isn't authored yet).` }] }
+        return { content: [{ type: 'text', text: `No authored ${k} page named "${name}" in any of your brains. If it's a person or team, pass kind (person/org).${await redLinkTriage(BASE, TOKEN, name)}` }] }
       }
       const day = (d) => (d ? String(d).slice(0, 10) : '')
       const renderMatch = (m, tagBrain) => {
@@ -791,6 +835,63 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'alias_page',
+    {
+      title: 'Point a wanted name at an existing page',
+      description: 'Record that a red-link — a [[Name]] referenced in the wiki but never authored — actually MEANS an existing authored page under a different title. After this, read_page and [[links]] for that name resolve to the target page, and the name leaves the org\'s wanted-page backlog. Use this when read_page says a name is a wanted page but you recognize it as an existing page (e.g. [[tto]] -> "BYU TTO — Technology Transfer Office"). To CREATE a genuinely new page instead, use `author`.',
+      inputSchema: {
+        name: z.string().describe('the wanted [[Name]] to redirect (the red-link)'),
+        target_name: z.string().describe('the exact title of the existing authored page it should resolve to'),
+        target_kind: z.enum(['project', 'person', 'org', 'user']).optional().describe('disambiguate the target if two pages share a title'),
+      },
+    },
+    async ({ name, target_name, target_kind }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/alias`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ name, target_name, ...(target_kind ? { target_kind } : {}) }),
+        })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not alias: ${e.message}` }] }
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return { content: [{ type: 'text', text: `Could not alias "${name}": ${out?.error ?? res.status}` }] }
+      if (!out) return { content: [{ type: 'text', text: `Aliased "${name}", but the server returned no body — re-read the page to confirm.` }] }
+      return { content: [{ type: 'text', text: `Done — [[${out.alias}]] now resolves to "${out.target}" (${out.target_kind}). It's out of the wanted-page backlog.` }] }
+    },
+  )
+
+  server.registerTool(
+    'snooze_red_link',
+    {
+      title: 'Defer a wanted page routed to you',
+      description: 'Stop a wanted page (a red-link the org routed to you as its most-likely steward) from surfacing in your context for a while. Use when you can\'t author it right now but it is genuinely yours to write. It comes back after the snooze passes. To dismiss it permanently, author it (`author`) or alias it to an existing page (`alias_page`).',
+      inputSchema: {
+        name: z.string().describe('the wanted page name to snooze (as shown in "Pages the org needs you to author")'),
+        days: z.number().int().positive().optional().describe('how many days to defer (default 7)'),
+      },
+    },
+    async ({ name, days }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/red-link/snooze`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ name, ...(days ? { days } : {}) }),
+        })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not snooze: ${e.message}` }] }
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return { content: [{ type: 'text', text: `Could not snooze "${name}": ${out?.error ?? res.status}` }] }
+      if (!out) return { content: [{ type: 'text', text: `Snoozed "${name}", but the server returned no body.` }] }
+      return { content: [{ type: 'text', text: `Snoozed "${out.name}" for ${out.days} day${out.days === 1 ? '' : 's'} — it won't surface until then.` }] }
+    },
+  )
+
   server.registerTool(
     'set_page_privacy',
     {

package/package.json

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