@theronap/cortex-mcp 0.9.45 → 0.9.46

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/server.mjs

@@ -8,6 +8,7 @@ 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'
 
 // 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 +285,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',
     {

package/package.json

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