@theronap/cortex-mcp 0.9.132 → 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)
@@ -2276,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"]'),
@@ -2289,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,
           }),
         })
@@ -2317,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.132",
+  "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": {