@theronap/agnoclast-mcp 0.9.96

package/README.md

@@ -0,0 +1,47 @@
+# cortex-mcp
+
+Connect your AI assistant to **Agnoclast** — your org's projects, recent activity, gaps, and directives, scoped to exactly what you're permitted to see.
+
+## Setup
+
+1. Get your personal token from the Agnoclast console → **Connect your AI**.
+2. Add this to your Claude Code config (`~/.claude.json`, under `mcpServers`):
+
+```json
+{
+  "mcpServers": {
+    "cortex": {
+      "command": "npx",
+      "args": ["-y", "@theronap/cortex-mcp"],
+      "env": { "CORTEX_TOKEN": "your-personal-token" }
+    }
+  }
+}
+```
+
+3. Restart Claude Code. Your AI now sees your org context automatically, the managed startup skill
+   will prefer query-centered `session_context` on substantive session opens, and each session start
+   will log the exact baseline Agnoclast context to `~/.cortex/context-snapshots/`.
+
+No clone, no path, no build step — `npx` fetches and runs it.
+
+## Tools
+
+- **my_context** — your projects, recent activity, gaps, and directives.
+- **session_context** — opening-query-centered context seeded from the most relevant node and its neighborhood.
+- **search_org** — search your visible activity and projects by keyword.
+- **project_status** — status of a specific project by key.
+
+## Startup snapshots
+
+Every Claude session start runs `snapshot-context`, which fetches the exact `my_context` payload and writes:
+- `~/.cortex/context-snapshots/latest.md`
+- `~/.cortex/context-snapshots/<timestamp>.md`
+- `~/.cortex/context-snapshots/index.jsonl`
+
+## Environment
+
+| Var | Required | Default |
+|-----|----------|---------|
+| `CORTEX_TOKEN` | yes | — |
+| `CORTEX_URL` | no | `https://cortex-console.vercel.app` |

package/bin/cortex-mcp.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * cortex-mcp — connect your AI assistant to Agnoclast.
+ *
+ * Subcommands:
+ *   (none)            run the MCP server (stdio) — used by your Claude config
+ *   setup <TOKEN>     wire BOTH the MCP server + capture hook into your Claude config
+ *   doctor            live health check — is the token actually working? (no restart needed)
+ *   capture           the Stop-hook capturer (invoked by Claude Code, not by hand)
+ *   ingest-folder <path>  ingest a local markdown folder as your authored records
+ *   snapshot-context  save the exact startup context served by Agnoclast to a local log file
+ *   --version | -v
+ *   --help | -h
+ *
+ * Zero-install onboarding:
+ *   npx -y @theronap/cortex-mcp setup <your-token>
+ *
+ * Get your token from the Agnoclast console → Connect your AI.
+ */
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+// VERSION = package.json, the single source of truth. NEVER hardcode it: a stale constant here is
+// exactly what shipped 0.9.6 as "0.9.5", so `setup` pinned the wrong version into every config and
+// no amount of cache-clearing/@version could fix an install. Derive it so it can never drift again.
+const VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')).version
+const cmd = process.argv[2]
+const rest = process.argv.slice(3)
+
+if (cmd === '--version' || cmd === '-v') {
+  process.stdout.write(`cortex-mcp ${VERSION}\n`)
+  process.exit(0)
+}
+
+if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
+  process.stdout.write(
+    `cortex-mcp ${VERSION} — connect your AI assistant to Agnoclast\n\n` +
+    `Onboard (one command, no token to copy):\n` +
+    `  npx -y @theronap/cortex-mcp login\n\n` +
+    `This opens your browser, you click Approve, and it wires everything up. Restart\n` +
+    `Claude Code after, and your AI sees your Agnoclast context while your sessions flow\n` +
+    `into the org automatically.\n\n` +
+    `Subcommands:\n` +
+    `  login [--label <name>]  browser-approved sign-in — gets a token for you, then runs setup\n` +
+    `  setup <token>   wire MCP server + capture hook into ~/.claude config (single editor)\n` +
+    `  install [<token>] [--editor auto|all|<id,...>]  wire Agnoclast into EVERY detected editor + write the capability manifest\n` +
+    `  repair          re-run setup at the latest version using your existing token (no token needed)\n` +
+    `  uninstall       remove ALL Agnoclast wiring (MCP, hooks, skills, launchd, cron). --dry-run to preview, --purge to also wipe ~/.cortex + npx cache\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` +
+    `  use-brain [<brain>]    where your session captures are saved — no arg shows the current setting\n` +
+    `  skills          install/repair the managed Agnoclast 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 Agnoclast authoring (used by /cortex-author-docs)\n` +
+    `  graphify-sync [path] [--brain <name-or-id>]  rebuild the local code graph + log a timeline event\n` +
+    `  snapshot-context save the exact startup context Agnoclast served to a local snapshot\n` +
+    `  hydrate         UserPromptSubmit hook — inject query-centered context on the first substantive turn\n` +
+    `  migrate-key [--dry-run]  move the MCP config key to its new name, allow rules first\n` +
+    `  with-token -- <cmd>    run <cmd> with your token in its environment (for cron/launchd wrappers)\n` +
+    `  statusline      ambient presence line for the Claude Code statusline (local read only)\n` +
+    `  capture         Stop-hook capturer (invoked by Claude Code)\n` +
+    `  ingest-folder <path>   ingest a local markdown folder as your authored records\n` +
+    `  (no args)       run the MCP server (used by your Claude config)\n\n` +
+    `Get your token from the Agnoclast console → Connect your AI.\n`,
+  )
+  process.exit(0)
+}
+
+// The network-using subcommands do their work, release the global fetch (undici) sockets, then
+// let the process exit NATURALLY — no process.exit(). Forcing exit on Windows tears libuv down
+// abruptly and, if a threadpool/pipe handle is mid-flight (DNS, the stdout flush), trips an
+// assertion (`!(handle->flags & UV_HANDLE_CLOSING)`, src\win\async.c) AFTER the real output.
+// A graceful drain lets libuv finish those handles first, so the assertion never fires. The MCP
+// server (default branch) runs forever and never reaches an exit path. if/else so the CLI
+// commands don't fall through into the server.
+if (cmd === 'login') {
+  // Browser-approved sign-in: no token to copy. Ends by calling runSetup with the token it
+  // collected, so there is still exactly ONE code path that writes a credential to disk.
+  const { runLogin } = await import('../lib/login.mjs')
+  await runLogin(rest, VERSION)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'setup') {
+  const { runSetup } = await import('../lib/setup.mjs')
+  await runSetup(rest, VERSION)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'install') {
+  // The cross-editor hub installer: wire Agnoclast into every detected editor via the adapter
+  // registry, then write the capability manifest (~/.cortex/editors.json). Superset of `setup`.
+  const { runInstall } = await import('../lib/install.mjs')
+  await runInstall(rest, VERSION)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'uninstall' || cmd === 'remove') {
+  // Full reverse of setup: strip every Agnoclast touch-point (MCP entries, hooks, skills, launchd, cron).
+  // --dry-run prints the plan and changes nothing; --purge also removes ~/.cortex, the npx cache, and
+  // backups. No network — safe to run even when the token is dead or the server is unreachable.
+  const { runUninstall } = await import('../lib/uninstall.mjs')
+  runUninstall(rest)
+} else if (cmd === 'repair' || cmd === 'update') {
+  // Re-run setup at THIS version using the already-wired token (no token arg needed). Fixes a
+  // machine set up with an older version: re-pins MCP + hooks, reinstalls skills to the flat path.
+  const { runRepair } = await import('../lib/setup.mjs')
+  await runRepair(VERSION)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'doctor') {
+  const { runDoctor } = await import('../lib/doctor.mjs')
+  process.exitCode = await runDoctor()
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'status') {
+  // One-line SessionStart health signal (wired by setup). Always exit 0.
+  const { runStatus } = await import('../lib/doctor.mjs')
+  await runStatus()
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'capture') {
+  const { runCapture } = await import('../lib/capture.mjs')
+  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(rest)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'materialize') {
+  // EXCISED 2026-07-02 (legacy-materializer incident): the digest pipeline deleted live-authored
+  // pages. Pages come from live authoring now; this stub keeps old hook invocations harmless.
+  process.stderr.write('cortex-mcp: `materialize` was removed — pages come from live authoring (the `author` tool + /log). Nothing to do.\n')
+} 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') {
+  // 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')
+  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()
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'hydrate') {
+  // UserPromptSubmit hook (① discovery): hydrate the model with query-centered Agnoclast context on the
+  // FIRST substantive turn, before it answers — then never again this session (topic-shift refresh stays
+  // the cortex-context skill's job). Synchronous by necessity, but once-per-session + 8s + fail-open.
+  const { runHydrate } = await import('../lib/hydrate.mjs')
+  process.exitCode = await runHydrate()
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'migrate-key') {
+  // ADR-0033 §5 C2. Guarded: adds the new namespace's allow rules and VERIFIES them from disk
+  // before flipping mcpServers.cortex -> .agnoclast, so a seat that never received C1 cannot end up
+  // with renamed tools and no permissions. Idempotent; --dry-run reports the plan and changes
+  // nothing. NOT wired into any hook yet — activating it is the C2 release itself.
+  const { runKeyMigration } = await import('../lib/migrate_key.mjs')
+  const res = runKeyMigration({ dryRun: rest.includes('--dry-run') })
+  process.stdout.write(JSON.stringify(res, null, 2) + '\n')
+  process.exitCode = res.status === 'aborted' ? 1 : 0
+} else if (cmd === 'with-token') {
+  // Run a command with the resolved token in its environment. Exists so generated helper scripts
+  // (launchd/cron wrappers) never inline their own config parse — those files are frozen on disk and
+  // a config change strands them silently. See lib/with_token.mjs.
+  const { runWithToken } = await import('../lib/with_token.mjs')
+  process.exitCode = runWithToken(rest)
+} else if (cmd === 'statusline') {
+  // Ambient presence: read one local breadcrumb and print a line. No network, no auth — it redraws
+  // constantly, so anything more expensive than a file read does not belong here.
+  const { runStatusline } = await import('../lib/statusline.mjs')
+  process.exitCode = runStatusline()
+} else if (cmd === 'skills') {
+  // Install / repair the managed Agnoclast skills — bundled + org-published (`skills push` publishes).
+  // Org sync is network-fail-soft so the SessionStart hook stays safe offline.
+  const { runSkills } = await import('../lib/skills.mjs')
+  process.exitCode = await runSkills(rest)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'docs-scan') {
+  // Documentation ingestion, detection half: hash-diff registered doc roots for new/changed *.md.
+  // The cortex-author-docs skill authors the pending docs into wiki pages. No network.
+  const { runDocsScan } = await import('../lib/docs_scan.mjs')
+  process.exitCode = await runDocsScan(rest)
+} else if (cmd === 'use-brain') {
+  // Set (or show) which brain this machine's unattended session captures land in. Registered here,
+  // BEFORE the default branch — an unrecognised subcommand falls through to "start the MCP server",
+  // which is how `connect-calendar` once silently became the file-watching daemon on a pilot user's
+  // machine and reported that daemon's errors instead of its own.
+  const { runUseBrain } = await import('../lib/use_brain.mjs')
+  process.exitCode = await runUseBrain(rest)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'precompact') {
+  // RETIRED — deliberately kept as a silent no-op, do not delete yet.
+  //
+  // The reminder it used to print never reached a model: PreCompact takes a blocking `decision` and has
+  // no additionalContext channel, so its stdout went nowhere (verified 2026-08-10 against 7,232 local
+  // transcripts — see the PreCompact block in lib/editors/claude.mjs for the measurement and control).
+  //
+  // Why this branch survives the removal: seats installed before this release still have
+  // `PreCompact: npx -y @theronap/cortex-mcp@latest precompact` in ~/.claude/settings.json, and @latest
+  // resolves to THIS build. Deleting the branch would turn a harmless no-op into an unknown-command
+  // error on every compaction for anyone who has not re-run install. mergeClaudeSettings unwires them
+  // on their next install/repair; drop this branch a release after that has had time to propagate.
+} else {
+  // Default: run the MCP server (stays alive; never exits).
+  const { runServer } = await import('../lib/server.mjs')
+  await runServer(VERSION)
+}