@theronap/cortex-mcp 0.9.63 → 0.9.65

package/lib/server.mjs

@@ -921,6 +921,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',
     {
@@ -1581,7 +1742,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.',
+        '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.',
       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"'),
@@ -1594,9 +1755,10 @@ export async function runServer(version) {
         base_version: z.string().optional().describe('the `version` hash shown when you read this page (read_page) — REQUIRED when updating an existing page, so a concurrent edit is caught instead of clobbered. Omit only for a brand-new node. If the save returns "stale" or "read first", read_page again and retry with the fresh version.'),
         reason: z.string().describe('WHY you are making this edit, in one short phrase — recorded permanently in page_history so a later reader can tell a routine addition from a correction. Say what CHANGED and what prompted it ("Ben pilot abandoned per Theron 07-17", "corrected: 0069 already widened the CHECK"), not what you did ("updated page"). This is the field that makes staleness auditable.'),
         change_kind: z.enum(['add', 'correct', 'supersede', 'expand', 'retire']).optional().describe('what KIND of edit: "add" (new information), "correct" (the page said something FALSE — the currency-critical one), "supersede" (was true, now outdated by events), "expand" (elaborates, no claim changed), "retire" (putting the page or a section to rest). Be honest with "correct" — a page whose history shows repeated corrections is a page whose claims need checking, and that signal is the point.'),
+        brain: z.string().optional().describe('which brain a genuinely NEW page is created in — a brain name or its org id. Choose by RELEVANCE to what you are writing (`my_brains` shows what each brain holds), not by the active pointer. Has top precedence, so it also disambiguates a page name you hold in several brains. Unnecessary when the brain is resolvable from the write itself (base_version, or an existing page of this name) and unnecessary when you only have one brain.'),
       },
     },
-    async ({ kind, name, summary, sections, tier, base_version, reason, change_kind }) => {
+    async ({ kind, name, summary, sections, tier, base_version, reason, change_kind, brain }) => {
       // No client-side tier default — the server computes the per-kind safe default (page-privacy
       // T4/D10) so version-pinned installs can't bake a stale policy.
       const pages = [{ ...(tier ? { tier } : {}), summary, base_version, sections: Array.isArray(sections) ? sections : [] }]
@@ -1605,7 +1767,10 @@ export async function runServer(version) {
         res = await fetchCortex(`${BASE}/api/brain/author`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ kind, name, pages, reason, change_kind }),
+          // `brain` is forwarded only when the caller named one. The server's resolveAuthorBrain gives
+          // an explicit brain top precedence and 409s on an unknown one rather than falling back to
+          // the pointer, so sending an empty value would turn "I did not choose" into "I chose wrong".
+          body: JSON.stringify({ kind, name, pages, reason, change_kind, ...(brain ? { brain } : {}) }),
         })
       } catch (e) {
         return toolError(`Could not author "${name}": ${e.message}`)

package/package.json

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