@theronap/cortex-mcp 0.9.64 → 0.9.66

package/lib/server.mjs

@@ -557,6 +557,12 @@ export async function runServer(version) {
         // word "today" from sections it was never meant to touch. This footer renders on EVERY
         // page read in the system, so it was the single widest surface pointing the wrong way.
         let footer = `— Follow any [[links]] above with read_page to go deeper.\n— If you hold fresher FIRST-HAND truth than this page — something you established THIS session (ran the command, made the change, hold the artifact) that a section here gets concretely wrong — fix just that passage with \`edit_page\`: quote the wrong text as old_string and pass this page's \`version\` as base_version (any node you are permitted to edit; concise; a material contradiction, not merely extra detail). If the save comes back stale the page changed under you — the conflict hands back what changed, so re-anchor from that instead of re-reading. Reading a stale page you can fix IS the trigger to fix it. Editing is pre-authorized — do NOT ask the user before updating (edits are versioned + reversible via page_history/rollback_page); update, then briefly report it. Use \`author\` only to CREATE a page or rewrite one wholesale: it re-emits every section, so untouched sections get retyped on the way through and drift.\n— Citing code? Use a SYMBOL and file (\`formConnections\` in \`web/app/api/ingest/route.ts\`), never a line number — line numbers drift with every commit above them. And cite only what you opened THIS session; re-emitting a reference you read on another page is how a stale claim gains a second source and starts looking corroborated.`
+        // ADDRESSING (2026-08-04). The server accepts `ref` on every page/node route and its ambiguity
+        // 409s hand refs back — but read_page never PRINTED one, so the only way to obtain a ref was to
+        // trigger the error first. That made ID addressing reachable in principle and unusable in
+        // practice. The ref is per-NODE (engram_ref) while `version` is per-TIER, which is why it rides
+        // on the page header rather than inside a tier block.
+        if (m.ref) footer += `\n— \`ref:\` above is this page's stable id. Pass it as \`ref\` to any page tool (set_page_privacy, page grants, node policy, author, rollback, node timeline) to address THIS page: refs are unique across brains, so two pages sharing a name in different brains cannot collide and no active-brain guess is involved. Prefer it over \`name\` whenever you already hold one.`
         // slice 4: when the page carries identifier stamps, the history projection is one flag away.
         const allBody = m.tiers.flatMap((t) => (t.sections ?? []).map((s) => s.body)).join('\n')
         const stamps = [...new Set((allBody.match(/\[\[repo:[a-z0-9][a-z0-9-]*\/[a-z0-9_.-]+\]\]/gi) ?? []).map((s) => s.toLowerCase()))]
@@ -568,7 +574,10 @@ export async function runServer(version) {
         // saw the footer, and repaired the page. A dashboard nobody opens would not have.
         if (m.backlog?.nudge) footer += `\n— ${m.backlog.nudge}`
         const brainTag = tagBrain ? `  ·  brain: ${m.brain}` : ''
-        return `# ${m.title ?? name} (full authored page${brainTag})\n\n${blocks.join('\n\n---\n\n')}\n\n${footer}`
+        // Always emitted, not only in the multi-brain case: the ref is what makes the brain question
+        // moot, so withholding it until brains collide is exactly backwards.
+        const refLine = m.ref ? `\nref: ${m.ref}` : ''
+        return `# ${m.title ?? name} (full authored page${brainTag})${refLine}\n\n${blocks.join('\n\n---\n\n')}\n\n${footer}`
       }
       if (matches.length === 1) {
         return { content: [{ type: 'text', text: renderMatch(matches[0], false) }] }
@@ -921,6 +930,167 @@ export async function runServer(version) {
     },
   )
 
+  // Stage 1 of agent-assisted member-add. It PREPARES the invite and stops — it does not perform it.
+  //
+  // WHY IT STOPS. Member-add lives on /api/invite and /api/members, which authenticate with
+  // `verifyAuthToken` (the Supabase login JWT) and reject the personal token this client holds. That
+  // split is not an oversight: `create_brain` accepts a personal token and writes a `users` row, so
+  // the line is not "membership writes need a browser" — it is "enrolling YOURSELF is self-service,
+  // granting a THIRD PARTY access to your brain is not." Stage 2 revisits that deliberately.
+  //
+  // What is worth automating is everything up to the grant. `managerId` is a `users.id` scoped to
+  // ONE brain — a multi-brain caller has a different one per membership and no way to see any of
+  // them from a chat window. That lookup is the part that actually blocks people, so this resolves
+  // it and hands back a payload the console can accept verbatim.
+  server.registerTool(
+    'add_to_brain',
+    {
+      title: 'Add someone to one of your brains',
+      description: "Add a person to one of your brains, or work out what it would take. Resolves which brain, whether you may add to it, and the manager id they are placed under. WITHOUT execute:true it only reports the plan and hands back a console link — call it that way first and show the user what you are about to do. WITH execute:true it performs the add, and then `brain` is REQUIRED: an access grant must never be aimed by a shared write pointer. Adding cannot be undone through the API. Use when asked to invite/add someone to a brain.",
+      inputSchema: {
+        email: z.string().describe("the person's email address — the login their Agnoclast account is (or will be) on"),
+        name: z.string().optional().describe('their full name; falls back to the email local-part'),
+        title: z.string().optional().describe('job title (optional)'),
+        role: z.enum(['member', 'manager', 'owner']).optional().describe("their role in this brain (default 'member'). NOTE: only owner/manager can see records scoped to people below them"),
+        brain: z.string().optional().describe('which brain, by name or org id. Optional when planning; REQUIRED with execute:true. Pass the org id when a name matches more than one of your brains'),
+        execute: z.boolean().optional().describe('default false. false = report the plan only. true = actually add them — not undoable through the API, and requires an explicit brain'),
+      },
+    },
+    async ({ email, name, title, role, brain, execute }) => {
+      const addr = (email ?? '').trim().toLowerCase()
+      if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(addr)) return toolError(`"${email}" does not look like an email address.`)
+
+      // Executing without naming a brain would let the ACCOUNT-WIDE write pointer decide who gets
+      // access to what. That pointer is shared by every session that has not set its own, so it
+      // reflects whatever unrelated work last touched it — it is not information about this grant.
+      // Planning may fall back to it (nothing happens); performing may not.
+      if (execute && !brain?.trim()) {
+        return toolError('To actually add someone you must name the brain — an access grant must not be aimed by the shared write pointer. Re-run with brain set (org id if the name is not unique).')
+      }
+
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brains`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      } catch (e) {
+        return toolError(`Could not read your brains: ${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 read your brains: ${d.message}`)
+      }
+      const { brains } = await res.json()
+      if (!brains?.length) return toolError('You have no brains, so there is nothing to add anyone to.')
+
+      // Name or org id, either way — a person says "my mom's brain", not a uuid.
+      //
+      // ⚠ BRAIN NAMES ARE NOT UNIQUE ACROSS ACCOUNTS, and the collision is the LIKELY case, not the
+      // exotic one: the default personal brain is called "Personal", so the moment you are added to
+      // someone else's you hold two. Observed 2026-08-04 within a minute of exactly that happening.
+      // A `.find()` here would silently return whichever sorted first and add the person to an
+      // arbitrary one — a wrong-brain member-add with no symptom, which is the same silent-misroute
+      // family as the write pointer. An org id always wins; an ambiguous NAME is a 409-shaped error,
+      // never a guess.
+      const wanted = brain?.trim().toLowerCase()
+      let target
+      if (wanted) {
+        const byId = brains.find((b) => b.orgId.toLowerCase() === wanted)
+        const byName = brains.filter((b) => b.name.toLowerCase() === wanted)
+        if (!byId && byName.length > 1) {
+          const rows = byName.map((b) => `  ${b.name}  (${b.role}, ${b.pageCount} pages)  [${b.orgId}]`)
+          return toolError(
+            `You belong to ${byName.length} brains called "${brain}". I will not guess which one to add someone to — pass the org id:\n${rows.join('\n')}`,
+          )
+        }
+        target = byId ?? byName[0]
+      } else {
+        target = brains.find((b) => b.isActive)
+      }
+      if (!target) {
+        const names = brains.map((b) => `${b.name} [${b.orgId}]`).join(', ')
+        return toolError(
+          wanted
+            ? `No brain called "${brain}". You belong to: ${names}.`
+            : `Could not tell which brain you mean — you belong to ${brains.length} and none is marked active. Pass one of: ${names}.`,
+        )
+      }
+
+      // Role is PER MEMBERSHIP. Being an owner elsewhere grants nothing here, and the server will
+      // enforce this again — checking now turns a later 403 into an answer.
+      if (!['owner', 'manager', 'admin'].includes(target.role)) {
+        return toolError(`You are a "${target.role}" in ${target.name}, and only owners and managers can add people. Ask an owner of ${target.name} to do it.`)
+      }
+
+      // Absent on any console deployed before userId was added to /api/brains. Say so precisely —
+      // a published MCP version is not a deployed API, and the two drift.
+      if (!target.userId) {
+        return toolError(`This Agnoclast deployment does not report your member id for ${target.name} yet, so the manager cannot be resolved. The API needs the /api/brains update that adds "userId".`)
+      }
+
+      const payload = {
+        name: name?.trim() || addr.split('@')[0],
+        email: addr,
+        ...(title?.trim() ? { title: title.trim() } : {}),
+        role: role ?? 'member',
+        managerId: target.userId,
+      }
+
+      if (execute) {
+        // `brain` is sent as the ORG ID, never the label the caller typed: the server resolves
+        // labels too, and a name that was unambiguous here could match differently there. The id is
+        // the same value on both sides.
+        let done
+        try {
+          done = await fetchCortex(`${BASE}/api/invite`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ...payload, brain: target.orgId }),
+          })
+        } catch (e) {
+          return toolError(`Could not add ${payload.email} to ${target.name}: ${e.message}`)
+        }
+        if (!done.ok) {
+          const d = classify(done.status, done.headers.get('content-type'), await done.text(), done.headers.get('x-vercel-id'))
+          return toolError(`Could not add ${payload.email} to ${target.name}: ${d.message}`)
+        }
+        const r = await done.json().catch(() => ({}))
+        if (r.alreadyMember) {
+          return { content: [{ type: 'text', text: `${payload.email} was already a member of ${target.name} — nothing changed.` }] }
+        }
+        // Two different outcomes for the human: a brand-new account has a credential that somebody
+        // must physically pass on, an existing one has none.
+        const how = r.existingAccount
+          ? 'They already had an Agnoclast account, so they keep their current login and simply gain this brain.'
+          : `A new account was created. Temporary password: ${r.password} — they must change it on first sign-in.`
+        return { content: [{ type: 'text', text: `Added ${payload.name} <${payload.email}> to ${target.name} as ${payload.role}, placed under you.\n${how}\n\nThis cannot be undone through the API — removing a membership currently needs direct database access.` }] }
+      }
+
+      const text = [
+        `Ready to add ${payload.name} <${payload.email}> to ${target.name} as ${payload.role}.`,
+        '',
+        `  brain      ${target.name}  [${target.orgId}]`,
+        `  your role  ${target.role} — you may add people here`,
+        `  manager    you  [${target.userId}]  (they are placed under you)`,
+        '',
+        'Nothing has happened yet. To go ahead, re-run with execute:true and the same brain —',
+        `or do it yourself at ${BASE}/?invite=1 with these values:`,
+        '',
+        `  Full name  ${payload.name}`,
+        `  Email      ${payload.email}`,
+        ...(payload.title ? [`  Job title  ${payload.title}`] : []),
+        `  Role       ${payload.role}`,
+        `  Manager    you`,
+        '',
+        'If they already have an Agnoclast account they keep their existing password and simply gain',
+        'this brain; if not, the console shows a temporary password to pass on. Either way the button',
+        'handles it — you do not need to know which in advance.',
+        '',
+        `payload: ${JSON.stringify(payload)}`,
+      ].join('\n')
+
+      return { content: [{ type: 'text', text }] }
+    },
+  )
+
   server.registerTool(
     'list_brain_pages',
     {
@@ -1239,20 +1409,21 @@ export async function runServer(version) {
       description: 'Re-tier a wiki page you own or may edit: "accessible" (anyone in the org), "scoped" (owner + their management chain), or "confidential" (owner only, plus explicit grants). Demoting a PROJECT page also demotes its evidence records (demote-only; each record\'s owner is notified and can revert). Promotions never touch records. If the target tier already has a page, merge your content into it via `author` FIRST, then read_page the target again to get its fresh version, then re-run this with absorb=true and target_version=<that version> — absorb will REJECT (not silently drop content) if target_version doesn\'t match what\'s actually there, so a merge that didn\'t really land can\'t destroy your source page. Org admins may demote any page, never promote.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the page kind'),
-        name: z.string().describe('the exact page name'),
+        name: z.string().optional().describe('the exact page name (or pass `ref` instead — one of the two is required)'),
+        ref: z.string().optional().describe('the page\'s stable id, printed as `ref:` by read_page. PREFER THIS over name when you have it: a ref is unique across brains, so it addresses exactly one page and never needs a brain to disambiguate it.'),
         tier: z.enum(['accessible', 'scoped', 'confidential']).describe('the new visibility tier'),
         source_tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('when the node has multiple tier variants: which one to move'),
         absorb: z.boolean().optional().describe('after merging your content into an existing target-tier page via author: true removes your now-absorbed source variant. Requires target_version.'),
         target_version: z.string().optional().describe('REQUIRED with absorb=true — the target page\'s version, read via read_page AFTER your author() merge landed. Proves the merge actually happened before your source page is deleted; a stale or guessed value is rejected, not silently accepted.'),
       },
     },
-    async ({ kind, name, tier, source_tier, absorb, target_version }) => {
+    async ({ kind, name, ref, tier, source_tier, absorb, target_version }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/brain/page-privacy`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ kind, name, tier, ...(source_tier ? { source_tier } : {}), ...(absorb ? { absorb: true } : {}), ...(target_version ? { target_version } : {}) }),
+          body: JSON.stringify({ kind, ...(name ? { name } : {}), ...(ref ? { ref } : {}), tier, ...(source_tier ? { source_tier } : {}), ...(absorb ? { absorb: true } : {}), ...(target_version ? { target_version } : {}) }),
         })
       } catch (e) {
         return toolError(`Could not set page privacy: ${e.message}`)
@@ -1284,19 +1455,20 @@ export async function runServer(version) {
       description: 'Share one of YOUR non-accessible wiki pages with a specific org member (or take that access back). A grant lets exactly that person read the page even though its tier would hide it — the escape hatch for "confidential, but Dana needs it". Owner-only. Grants survive re-tiering: revoke them when they should end.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the page kind'),
-        name: z.string().describe('the exact page name'),
-        grantee: z.string().describe('the org member\'s display name or email (must resolve uniquely — use email if ambiguous)'),
+        name: z.string().optional().describe('the exact page name (or pass `ref` instead — one of the two is required)'),
+        ref: z.string().optional().describe('the page\'s stable id, printed as `ref:` by read_page. Prefer this over name: unique across brains, so it addresses exactly one page.'),
+        grantee: z.string().describe('display name or email of a member OF THE PAGE\'S BRAIN (must resolve uniquely — use email if ambiguous)'),
         action: z.enum(['grant', 'revoke']).describe('grant or revoke'),
         tier: z.enum(['scoped', 'confidential']).optional().describe('which variant (default: the most restrictive one)'),
       },
     },
-    async ({ kind, name, grantee, action, tier }) => {
+    async ({ kind, name, ref, grantee, action, tier }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/brain/page-grants`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ kind, name, grantee, action, ...(tier ? { tier } : {}) }),
+          body: JSON.stringify({ kind, ...(name ? { name } : {}), ...(ref ? { ref } : {}), grantee, action, ...(tier ? { tier } : {}) }),
         })
       } catch (e) {
         return toolError(`Could not ${action}: ${e.message}`)
@@ -1315,13 +1487,15 @@ export async function runServer(version) {
       description: 'Show every explicit access grant on YOUR page\'s tier variants (owner-only). Use after re-tiering a page — grants survive tier changes and keep granting until revoked.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the page kind'),
-        name: z.string().describe('the exact page name'),
+        name: z.string().optional().describe('the exact page name (or pass `ref` instead — one of the two is required)'),
+        ref: z.string().optional().describe('the page\'s stable id, printed as `ref:` by read_page. Prefer this over name: unique across brains, so it addresses exactly one page.'),
       },
     },
-    async ({ kind, name }) => {
+    async ({ kind, name, ref }) => {
       let res
+      const addr = ref ? `ref=${encodeURIComponent(ref)}` : `name=${encodeURIComponent(name ?? '')}`
       try {
-        res = await fetchCortex(`${BASE}/api/brain/page-grants?kind=${encodeURIComponent(kind)}&name=${encodeURIComponent(name)}`, {
+        res = await fetchCortex(`${BASE}/api/brain/page-grants?kind=${encodeURIComponent(kind)}&${addr}`, {
           headers: { Authorization: `Bearer ${TOKEN}` },
         })
       } catch (e) {

package/package.json

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