@theronap/cortex-mcp 0.9.131 → 0.9.133

package/lib/server.mjs

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod'
-import { writeFileSync, mkdirSync } from 'fs'
+import { writeFileSync, mkdirSync, readFileSync, statSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { createHash, randomUUID } from 'crypto'
@@ -927,8 +927,13 @@ function renderNudge(payload) {
       //   attached: [...] filed under N pages
       //
       // Reporting only a count would make the first indistinguishable from the second, which is how
-      // a broken write hides inside a normal-looking result. `undefined` means the server has not
-      // shipped this field yet, so nothing is said rather than something wrong.
+      // a broken write hides inside a normal-looking result.
+      //
+      // ⚠ AND `undefined` IS A FOURTH STATE: NOT ATTEMPTED. Session-page attachment only runs for
+      // claude-code sources — a handoff, an email, a calendar event has no session to join on. The
+      // server used to send null in that case, having never tried, and this reported a FAILURE for
+      // the ordinary case (observed 2026-09-03 on the first handoff record materialised). Silence is
+      // correct here, and it also covers a server too old to send the field at all.
       const lines = []
       const sa = body?.sessionAttachments
       if (sa === null) {
@@ -943,6 +948,19 @@ function renderNudge(payload) {
           lines.push(`${sa.droppedCrossBrain} page(s) this session wrote live in another brain and were skipped — a record belongs to one brain.`)
         }
       }
+      // Containment carried from capture. Three states, and they are not interchangeable:
+      //   true            placed in the container the capture named
+      //   false           the edge already existed — a re-materialise, not a failure
+      //   null/undefined  no container was ever requested (say nothing)
+      // containerSkipped is the only one that needs a warning: it means a container WAS asked for and
+      // did not happen, which is exactly the silence this whole path exists to remove.
+      if (body?.containerSkipped) {
+        lines.push(`⚠ CONTAINER NOT APPLIED — ${body.containerSkipped}. The record exists but is not inside the event you named; place it with contain_record or leave it out.`)
+      } else if (body?.contained === true) {
+        lines.push('Placed inside the container named at capture.')
+      } else if (body?.contained === false) {
+        lines.push('Already inside the container named at capture (no change).')
+      }
       const text = lines.length
         ? `${lines.join('\n')}\n\n${JSON.stringify(body, null, 2)}`
         : JSON.stringify(body, null, 2)
@@ -2167,6 +2185,74 @@ function renderNudge(payload) {
     },
   )
 
+  server.registerTool(
+    'propose_containers',
+    {
+      title: 'Which event could this record belong to?',
+      description: "Given a record, list the events (class sessions, meetings) it could have COME FROM — candidates only, nothing is written. Candidates are generated by time overlap and filtered by whether the container's type admits that kind of record; a CLOSED container still qualifies, because closing seals a candidate set but does not stop admitting (a transcript synced days later still belongs to the meeting it came from). ⚠ OVERLAP IS NOT AN ANSWER: a coding session that overlapped a meeting may be evidence you SKIPPED it. Ranked by how TIGHT the container is, ascending — a point in a 50-minute class is specific evidence, the same point in an all-day event is nearly none. Choose, then call contain_record.",
+      inputSchema: {
+        record_id: z.string().describe('the record to place'),
+        limit: z.number().optional().describe('max candidates (default 10)'),
+      },
+    },
+    async ({ record_id, limit }) => {
+      const qs = new URLSearchParams(limit ? { limit: String(limit) } : {})
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/records/${encodeURIComponent(record_id)}/containers?${qs}`,
+          { headers: { Authorization: `Bearer ${TOKEN}` } })
+      } catch (e) {
+        return toolError(`Could not reach Agnoclast to find containers for ${record_id}: ${e.message}`)
+      }
+      const body = await res.json().catch(() => ({}))
+      if (!res.ok || !body?.ok) return toolError(`Could not propose containers: ${body?.error ?? res.status}`)
+      if (!body.proposals?.length) {
+        return { content: [{ type: 'text', text: `No container candidates for ${record_id}. Either nothing overlaps its time, or no overlapping event's type admits this kind of record.` }] }
+      }
+      const lines = [`Container candidates for ${record_id} (tightest first):`]
+      for (const p of body.proposals) {
+        lines.push(`- ${p.title ?? '(untitled)'} · ${p.containerType} · ${p.containerMinutes}min · starts ${p.startsAt}`
+          + `\n    id: ${p.containerRecordId}${p.late ? '\n    LATE — this arrived after the container closed; still a valid home' : ''}`)
+      }
+      lines.push('', 'Nothing has been written. Use contain_record with the id you choose.')
+      return { content: [{ type: 'text', text: lines.join('\n') }] }
+    },
+  )
+
+  server.registerTool(
+    'contain_record',
+    {
+      title: 'Place a record inside an event',
+      description: "Put a record INSIDE an event — the transcript that came out of a meeting, the session that filled a work block. This is a DECISION, not an inference, and it is recorded as one (designated_by: human). ⚠ It only accepts a container that propose_containers actually offered for this record: naming an arbitrary id would skip the checks that keep containment inside one brain and inside the container type's admission set. `kind` defaults to 'produced' (it came OUT of that event); use 'context' for something that was merely going on at the time. Placing a record in an event is different from attaching it to a PAGE: pages are what a record is ABOUT, containers are where it CAME FROM.",
+      inputSchema: {
+        record_id: z.string().describe('the record to place'),
+        container_record_id: z.string().describe('the event to place it in — an id from propose_containers or find_sessions'),
+        kind: z.enum(['produced', 'context']).optional().describe("'produced' (default) = it came out of that event; 'context' = it was merely happening at the same time"),
+      },
+    },
+    async ({ record_id, container_record_id, kind }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/records/${encodeURIComponent(record_id)}/containers`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ containerRecordId: container_record_id, kind }),
+        })
+      } catch (e) {
+        return toolError(`Could not reach Agnoclast to place ${record_id}: ${e.message}`)
+      }
+      const body = await res.json().catch(() => ({}))
+      if (!res.ok || !body?.ok) {
+        return toolError(`Could not place ${record_id}: ${body?.error ?? res.status}${body?.detail ? ` — ${body.detail}` : ''}`)
+      }
+      // `contained: false` means it was ALREADY in that container — a no-op, not a failure. Saying
+      // "placed" either way would hide that a second call did nothing.
+      return { content: [{ type: 'text', text: body.contained
+        ? `Placed ${record_id} inside ${container_record_id} as '${kind ?? 'produced'}'.`
+        : `${record_id} was already inside ${container_record_id} — nothing changed.` }] }
+    },
+  )
+
   server.registerTool(
     'find_sessions',
     {
@@ -2208,10 +2294,11 @@ function renderNudge(payload) {
     'capture_record',
     {
       title: 'Hand something over and get it into the brain',
-      description: "Put a document, transcript, notes or any pasted content into the brain as a real record, routed to where it belongs. USE THIS WHEN THERE IS NO CONNECTOR — a lecture recording, an export from a tool nobody has wired up, something a person just handed you. ⚠ `identifiers` IS HOW IT REACHES A PAGE: a record routes to whatever page CLAIMS an identifier it carries (series:… for a class or recurring meeting, repo:owner/name, project:slug, email:someone@example.com). WITHOUT ONE IT REACHES NO PAGE — that is not an error, but it means nobody will find it, so say so rather than reporting success. `occurred_at` is WHEN THE THING HAPPENED, not now: a transcript handed over today may belong to yesterday's class, and filing it under today puts it in the wrong interval invisibly. `container_record_id` additionally places it INSIDE a specific event (a class session, a meeting) — that is an explicit human decision and is recorded as one; overlap alone never places anything.",
+      description: "Put a document, transcript, notes or any pasted content into the brain as a real record, routed to where it belongs. USE THIS WHEN THERE IS NO CONNECTOR — a lecture recording, an export from a tool nobody has wired up, something a person just handed you. ⚠ `identifiers` IS HOW IT REACHES A PAGE: a record routes to whatever page CLAIMS an identifier it carries (series:… for a class or recurring meeting, repo:owner/name, project:slug, email:someone@example.com). WITHOUT ONE IT REACHES NO PAGE — that is not an error, but it means nobody will find it, so say so rather than reporting success. `occurred_at` is WHEN THE THING HAPPENED, not now: a transcript handed over today may belong to yesterday's class, and filing it under today puts it in the wrong interval invisibly. `container_record_id` additionally places it INSIDE a specific event (a class session, a meeting) — that is an explicit human decision and is recorded as one; overlap alone never places anything. \u26a0 PASS `content_path` FOR ANYTHING LONG: a file is read and sent verbatim, whereas retyping a transcript into `content` routes every character through a model that is not guaranteed to reproduce it exactly. Use `content` only for something short you are composing yourself.",
       inputSchema: {
         title: z.string().describe('a short name for this record'),
-        content: z.string().describe('the actual content — transcript, notes, document text. Summarized server-side.'),
+        content: z.string().optional().describe('the actual content, inline. For anything long prefer content_path — see below.'),
+        content_path: z.string().optional().describe('ABSOLUTE PATH to a file whose contents become the record, read and sent verbatim. USE THIS FOR TRANSCRIPTS AND DOCUMENTS: it is the only way the stored text is guaranteed byte-identical to the source. Exactly one of content / content_path.'),
         occurred_at: z.string().describe('when the thing HAPPENED, ISO 8601 — not when you are uploading it'),
         ends_at: z.string().optional().describe('when it ended, ISO 8601. Omit if unknown; NEVER guess one.'),
         identifiers: z.array(z.string()).optional().describe('routing identifiers — how it reaches a page. e.g. ["series:geol-100-001-f2026"]'),
@@ -2221,14 +2308,34 @@ function renderNudge(payload) {
         brain: z.string().optional().describe('which brain, by name or org id. REQUIRED if you belong to more than one — placing a record IS a disclosure decision.'),
       },
     },
-    async ({ title, content, occurred_at, ends_at, identifiers, container_record_id, summary, source, brain }) => {
+    async ({ title, content, content_path, occurred_at, ends_at, identifiers, container_record_id, summary, source, brain }) => {
+      // 🔴 A FILE IS READ HERE RATHER THAN RETYPED UPSTREAM, AND THAT IS A FIDELITY GUARANTEE,
+      // NOT A CONVENIENCE. Passing a 39,000-character lecture transcript through `content` means the
+      // caller has to emit every character of it, and a model reproducing a long document verbatim is
+      // likely-correct, never certain-correct. Measured 2026-09-03: the first real transcript captured
+      // this way had to carry a note in its own body saying it was re-entered and unverified. Reading
+      // the file makes byte-identity structural instead of a matter of care.
+      if ((content == null || content === '') === (content_path == null || content_path === '')) {
+        return toolError('Pass exactly one of content or content_path.')
+      }
+      let text = content
+      if (content_path) {
+        try {
+          const st = statSync(content_path)
+          if (!st.isFile()) return toolError(`Not a file: ${content_path}`)
+          text = readFileSync(content_path, 'utf8')
+        } catch (e) {
+          return toolError(`Could not read ${content_path}: ${e.message}`)
+        }
+        if (!text.trim()) return toolError(`${content_path} is empty — nothing to capture.`)
+      }
       let res
       try {
         res = await fetchCortex(`${BASE}/api/records/capture`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
           body: JSON.stringify({
-            title, content, occurredAt: occurred_at, endsAt: ends_at, identifiers,
+            title, content: text, occurredAt: occurred_at, endsAt: ends_at, identifiers,
             containerRecordId: container_record_id, summary, source, brain,
           }),
         })
@@ -2249,6 +2356,13 @@ function renderNudge(payload) {
         if (body.duplicate) l.push('This matched an existing unit rather than creating a new one.')
         if (body.routed_by?.length) l.push(`Carries: ${body.routed_by.join(', ')} — it will route on those once materialised.`)
         else l.push('⚠ NO IDENTIFIERS — once materialised it will reach no page.')
+        // ⚠ A CONTAINER THE CALLER ASKED FOR MUST NOT VANISH FROM THE REPORT. It cannot be applied
+        // yet — there is no record — but it IS carried in the sealed payload and applied at
+        // materialisation. Saying nothing here is what made a caller re-derive a placement they had
+        // already specified (observed 2026-09-03).
+        if (body.containerDeferred) {
+          l.push(`Container ${body.containerRecordId} is carried with it and applied when you materialise — you do not need to place it again.`)
+        }
         return { content: [{ type: 'text', text: l.join('\n') }] }
       }
       const lines = [`Captured "${title}" as record ${body.id}.`]

package/package.json

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