@theronap/cortex-mcp 0.9.64 → 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',
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.64",
+  "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": {