@theronap/cortex-mcp 0.9.66 → 0.9.67

package/lib/server.mjs

@@ -59,7 +59,7 @@ export async function runServer(version) {
   // PGL-21 fix: "one MCP process = one AI session" is an assumption, not a guarantee — the HOST
   // (Claude Code) can restart this stdio process mid-conversation (reconnects, tool-loading events),
   // and a fresh randomUUID() on every restart silently orphaned the PRIOR process's session-scoped
-  // write-pointer row (session_write_pointers): an explicit set_active_brain(scope:'session') would
+  // ADR-0022 deleted the write pointer, so a session no longer carries a brain of its own.
   // stop taking effect one restart later, falling back to the account pointer with no visible cause
   // — reproduced live 2026-07-27. Claude Code sets CLAUDE_CODE_SESSION_ID for the lifetime of one
   // logical conversation across any number of subprocess restarts, so prefer it as the session key;
@@ -1126,50 +1126,11 @@ export async function runServer(version) {
     },
   )
 
-  server.registerTool(
-    'set_active_brain',
-    {
-      title: 'Set the default brain for NEW pages',
-      description: "RARELY NEEDED — do not reach for this reflexively. Editing an EXISTING page routes itself: author/set_page_validity/rollback resolve the brain from the page (via base_version, ref, or name), so switching first is unnecessary and switching WRONG is now impossible to cause. This only sets the default for creating a page that exists in NO brain yet, and for log_session/capture. If you find yourself about to call this so an edit lands correctly, don't — just author; it will find the page. Pass org_id = null to clear. SCOPE: 'session' (default) changes ONLY this session; 'account' changes the person-wide pointer and redirects every other open session that has not set its own.",
-      inputSchema: {
-        org_id: z.string().nullable().describe('the org id of the brain to write to (from my_brains), or null to clear the pointer'),
-        scope: z.enum(['session', 'account']).optional()
-          .describe("'session' (default) = this window only; 'account' = person-wide, affects your other open sessions too"),
-      },
-    },
-    async ({ org_id, scope }) => {
-      let res
-      try {
-        res = await fetchCortex(`${BASE}/api/brains`, {
-          method: 'PUT',
-          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ orgId: org_id ?? null, scope: scope ?? 'session' }),
-        })
-      } catch (e) {
-        return toolError(`Could not set active brain: ${e.message}`)
-      }
-      if (!res.ok) {
-        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return toolError(`Could not set active brain: ${d.message}`)
-      }
-      const r = await res.json()
-      // Always say WHICH scope changed. The default is session-only, so a caller expecting the old
-      // person-wide stickiness must be able to see that it did NOT change their other windows.
-      const where = r.scope === 'session' ? 'this session only' : 'ALL your sessions (person-wide)'
-      if (!r.activeOrgId) {
-        return { content: [{ type: 'text', text: r.scope === 'session'
-          ? 'Cleared this session\'s brain override — writes fall back to your account pointer.'
-          : 'Cleared your account-wide active-brain pointer (writes fall back to your default brain).' }] }
-      }
-      return { content: [{ type: 'text', text: `Writes now land in brain ${r.activeOrgId} — ${where}.` }] }
-    },
-  )
-
   server.registerTool(
     'create_brain',
     {
       title: 'Create a new brain under your existing account',
-      description: 'Create a brand-new brain (org/workspace) — a fully independent knowledge graph — under your EXISTING account. No new login, no new email/password: this adds a second membership to the account you are already using. Reads never cross brains; new pages default to your active brain, so use set_active_brain if you want NEW pages to land in this one; edits to existing pages always route to whichever brain holds them.',
+      description: 'Create a brand-new brain (org/workspace) — a fully independent knowledge graph — under your EXISTING account. No new login, no new email/password: this adds a second membership to the account you are already using. Reads never cross brains; new pages default to your active brain, so use pass `brain` when an operation needs one named',
       inputSchema: { name: z.string().describe('display name for the new brain, e.g. "Cortex Codebase"') },
     },
     async ({ name }) => {
@@ -1188,7 +1149,7 @@ export async function runServer(version) {
         return toolError(`Could not create brain: ${d.message}`)
       }
       const r = await res.json()
-      return { content: [{ type: 'text', text: `Created brain "${name}" [${r.orgId}]. Reads already span it. Edits to pages in it route themselves; set_active_brain only if you want NEW pages to default here.` }] }
+      return { content: [{ type: 'text', text: `Created brain "${name}" [${r.orgId}]. Reads already span it. Edits to pages in it route themselves from the page, so nothing needs pointing at it; pass brain="${name}" on an operation that creates something new here.` }] }
     },
   )
 
@@ -1755,7 +1716,7 @@ export async function runServer(version) {
     {
       title: 'Author a wiki node (live, while it is hot)',
       description:
-        'Write your CURRENT understanding of a project/person/org/you into the org wiki as a maintained page. Call `authoring_context` FIRST. Author from your own synthesis of the session — the compiled mental model, not a transcript dump: what it IS, where it stands, dated decisions, open threads, key people. Weave inline [[links]] to other nodes (canonical names from the namespace; red-links for wanted-but-absent nodes). The server re-authorizes the tier and resolves links. CREATES the node if it does not exist yet (project/person/org) — the conversation IS the evidence, so a brand-new entity that surfaced only in this session is authorable on the spot; you do NOT need prior records. Because such a node has nothing external to corroborate it, author it DELIBERATELY: only when you genuinely understand it is a real, distinct entity, and use its exact canonical name so it does not duplicate one already in the namespace (`user` nodes are never created). Use this continuously whenever your understanding of a node meaningfully advanced, and at session end (/log). Authoring is PRE-AUTHORIZED — never ask the user "should I update the page?" before calling this (every edit is versioned + reversible via page_history/rollback_page); update, then briefly report what you updated. ⚠ WHICH BRAIN A NEW PAGE GOES IN IS A CONTENT DECISION, SO MAKE IT FROM THE CONTENT. Only a page that exists in NO brain needs this — an update resolves its brain from the page itself. If you hold more than one brain, call `my_brains` (it returns each brain\'s name, page count and sample titles, which is enough to tell what each one is FOR) and pass `brain` explicitly rather than letting the write pointer decide; the pointer is stale out-of-band state that knows nothing about what you are writing. State which brain you picked and why in one short line, then proceed — do NOT ask when the answer is obvious from the content. DO ask when it is genuinely ambiguous: brains are a confidentiality boundary, so a page born in the wrong one can expose private work to a teammate, and that is not a filing error you can quietly fix later.',
+        'Write your CURRENT understanding of a project/person/org/you into the org wiki as a maintained page. Call `authoring_context` FIRST. Author from your own synthesis of the session — the compiled mental model, not a transcript dump: what it IS, where it stands, dated decisions, open threads, key people. Weave inline [[links]] to other nodes (canonical names from the namespace; red-links for wanted-but-absent nodes). The server re-authorizes the tier and resolves links. CREATES the node if it does not exist yet (project/person/org) — the conversation IS the evidence, so a brand-new entity that surfaced only in this session is authorable on the spot; you do NOT need prior records. Because such a node has nothing external to corroborate it, author it DELIBERATELY: only when you genuinely understand it is a real, distinct entity, and use its exact canonical name so it does not duplicate one already in the namespace (`user` nodes are never created). Use this continuously whenever your understanding of a node meaningfully advanced, and at session end (/log). Authoring is PRE-AUTHORIZED — never ask the user "should I update the page?" before calling this (every edit is versioned + reversible via page_history/rollback_page); update, then briefly report what you updated. ⚠ WHICH BRAIN A NEW PAGE GOES IN IS A CONTENT DECISION, SO MAKE IT FROM THE CONTENT. Only a page that exists in NO brain needs this — an update resolves its brain from the page itself. If you hold more than one brain, the server REFUSES a create it cannot attribute (409 `create_needs_brain`) rather than letting the write pointer decide — the pointer is stale out-of-band state that knows nothing about what you are writing. So call `my_brains` (it returns each brain\'s name, page count and sample titles, which is enough to tell what each one is FOR) and pass `brain` up front; that turns a refused round trip into a single call. State which brain you picked and why in one short line, then proceed — do NOT ask when the answer is obvious from the content. DO ask when it is genuinely ambiguous: brains are a confidentiality boundary, so a page born in the wrong one can expose private work to a teammate, and that is not a filing error you can quietly fix later.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the node type'),
         name: z.string().describe('the canonical node name — an EXACT existing name from the namespace to update it, or a new name to create the node (project/person/org). e.g. "Cortex" or "Theron Peterson"'),
@@ -1789,7 +1750,28 @@ export async function runServer(version) {
         return toolError(`Could not author "${name}": ${e.message}`)
       }
       if (!res.ok) {
-        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+        // Read the body ONCE — classify() consumes it as text, so parsing after it is a spent stream.
+        const raw = await res.text()
+        let err = null
+        try { err = JSON.parse(raw) } catch { /* not JSON; classify handles it below */ }
+        // BRAIN-RESOLUTION REFUSALS carry the only thing that makes them actionable: which brains, and
+        // what is in each. classify() flattens a response to a generic status message, so routing these
+        // through it would drop the payload and leave the agent to guess a brain — the exact guess the
+        // 409 exists to prevent. Page counts and sample titles matter more than the names: per
+        // brain_identity.ts a brain's NAME is actively misleading about its contents.
+        if (err?.error === 'create_needs_brain' || err?.error === 'ambiguous_brain' || err?.error === 'unknown_brain') {
+          const list = (err.brains ?? []).map((b) => {
+            const count = b.pageCount != null ? ` — ${b.pageCount} page${b.pageCount === 1 ? '' : 's'}` : ''
+            const sample = b.sampleTitles?.length ? `: ${b.sampleTitles.slice(0, 4).join(', ')}` : ''
+            return `  • ${b.name ?? b.brain} (${b.orgId})${count}${sample}`
+          }).join('\n')
+          return toolError(
+            `Could not author "${name}": ${err.message ?? err.error}` +
+            (list ? `\n\nYour brains:\n${list}` : '') +
+            `\n\nRe-run author with brain:"<name>" — choose by what each brain HOLDS, not by its name.`,
+          )
+        }
+        const d = classify(res.status, res.headers.get('content-type'), raw, res.headers.get('x-vercel-id'))
         return toolError(`Could not author "${name}": ${d.message}`)
       }
       const out = await res.json()

package/package.json

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