feat(mcp): read_file and create_upload_link read and attach a record's files

.changeset/30892-mcp-read-file-upload-link.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/mcp': patch
+'@objectstack/runtime': patch
+'@objectstack/service-storage': patch
+---
+
+feat(mcp): an agent can read a record's files and attach a file to a record — `read_file` and `create_upload_link` over `/api/v1/mcp`, and the single-use upload link they hand out (#30892)
+
+Clause-②: yes (widening) — two MCP tools join the HTTP surface where the storage service is installed (`read_file` under `data:read`, `create_upload_link` under `data:write`), and two signed-in routes join the storage family: `GET` and `PUT /api/v1/storage/upload-links/:token`. Nothing that answered before answers differently.
+Metadata-protocol: none
+
+- **`read_file`** takes `objectName`, `recordId` and a file field (with `fileId` when the field holds several files) or an `attachmentId`. With neither, it lists the record's files. It answers the file's facts (id, name, type, size, the read cap that applies), a short-lived download link, and the content: a PDF's or Word document's text (extracted on the server, capped in pages and characters), an image as an MCP image block, a text file as text. A file over the cap (10 MiB) answers its facts and the download link, without content. Access follows the record: a record the caller cannot read answers `404 RECORD_NOT_FOUND`, as `get_record` does, and a file the download door would refuse answers that door's `403`.
+- **`create_upload_link`** takes a record the caller may edit plus a file field or `attachments: true`. It answers a link that accepts exactly one upload for ten minutes, bound to that record and that field (or the record's attachments), and usable only by the same user, signed in: a request without a session answers `401 AUTH_REQUIRED`, like every other storage door. The upload lands as the caller would land it: the file field is written through the record's own update door, so the field's `accept` and `maxSize`, the record's edit access and the upload size limit (`storage.max_upload_mb`, `413` before the link is spent) all apply. It writes the same `sys_file` row, size recorded, and the same `storage.upload` as any other upload, so whatever a host counts toward quota counts it. A used, expired or unknown link, or one made for another user, answers the same `404`.
+- **`@objectstack/mcp`** loads `unpdf` (pinned 1.9.1) by dynamic import on the first PDF read, with pdf.js eval off; a Word document is read with `node:zlib` under a bounded inflate.

content/docs/ai/connect-mcp.mdx

@@ -245,7 +245,8 @@ decision.
 
 ## What the agent gets
 
-Twelve tools, generated from your metadata:
+Twelve tools, generated from your metadata, and two more for files where the
+storage service is installed:
 
 | Tool | What it does |
 |:---|:---|
@@ -256,6 +257,40 @@ Twelve tools, generated from your metadata:
 | `create_record` / `update_record` / `delete_record` | Write data |
 | `list_actions` / `run_action` | Discover and invoke your business actions by name |
 | `resume_run` | Finish a flow action that paused on a screen, by submitting the screen's values |
+| `read_file` | Read a file a record carries: its text (text files, PDF, Word `.docx`) or the image itself, with its size, the byte cap and a short-lived download link |
+| `create_upload_link` | Hand the user a single-use link that uploads one file onto a record's file field or its attachments |
+
+### Files: `read_file` and `create_upload_link`
+
+Both tools are registered only where the storage service is installed (they
+read and write through it), `read_file` with the `data:read` scope and
+`create_upload_link` with `data:write`. Neither judges access on its own: the
+record is read first, exactly as `get_record` reads it, so **no access to the
+record means no file**, refused with the same `RECORD_NOT_FOUND`.
+
+- **`read_file({ objectName, recordId, field?, fileId?, attachmentId? })`**
+  reads one file: the one a file field holds (`field`, plus `fileId` when the
+  field holds several), or one attachment (`attachmentId`). Send neither to
+  list the record's files with their ids. The file is then judged by the same
+  rule as a download from the Console. The answer carries the file's name,
+  type and size, the byte cap `read_file` reads (10 MiB), a download link that
+  expires after five minutes, and the content: the text of a text file, a PDF
+  or a Word document (cut at 100,000 characters or 200 PDF pages), or the image
+  itself for PNG, JPEG, GIF and WebP up to 5 MiB. A larger file answers its
+  facts and the link only; a damaged PDF or Word file answers a sentence
+  saying so.
+- **`create_upload_link({ objectName, recordId, field? | attachments: true })`**
+  needs a record the caller may edit (and, for a field, a field they may
+  write). It answers a link and its expiry (ten minutes). The user opens the
+  link in a browser where they are signed in to this deployment, picks one
+  file, and it lands on exactly that record and field, or as an attachment of
+  that record. On a phone, they sign in there first. The link works only for
+  the user it was made for, and only once: without a session it answers
+  `401`, and a second use, an expired link, an unknown link and another user's
+  link all get the same `404`. The upload is stored as that user, with their
+  access checked again when the file arrives, and it meets the storage
+  service's maximum upload size before the link is spent. Sending a file's
+  bytes through the MCP protocol itself is not supported yet.
 
 The tools are a fixed ~10-tool **spine** with the object name as a *parameter*
 (`query_records(objectName, …)`), not one tool per object — so the list stays
@@ -411,7 +446,7 @@ call '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":
 # → {"result":{"serverInfo":{"name":"objectstack",...},"capabilities":{"tools":{...},"prompts":{}}},...}
 
 call '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | grep -o '"name":"[a-z_]*"'
-# → the twelve tools, list_objects … resume_run
+# → the twelve tools, list_objects … resume_run (fourteen with read_file and create_upload_link where storage is installed)
 
 call '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"query_records","arguments":{"objectName":"crm_opportunity","limit":3}}}'
 # → {"result":{"content":[{"type":"text","text":"{ \"object\": \"crm_opportunity\", \"records\": [ ... ], \"total\": 23, \"hasMore\": true }"}]}}

content/docs/api/plugin-endpoints.mdx

@@ -161,6 +161,8 @@ other adapter.
 | GET | `/storage/upload/chunked/:uploadId/progress` | `storage.resumeUpload` | Read session progress (first step of a resume) |
 | GET | `/storage/files/:fileId/url` | `storage.getDownloadUrl` | Resolve a short-lived signed download URL |
 | GET | `/storage/files/:fileId` | — | Stable browser URL; 302s to the same signed URL (what file fields carry) |
+| GET | `/storage/upload-links/:token` | — | The page a single-use upload link opens (minted by the MCP `create_upload_link` tool) for the signed-in user it was made for: a file picker |
+| PUT | `/storage/upload-links/:token` | — | Spend the link on the request body, as that signed-in user; the file lands on the record and field the link is bound to |
 
 `storage.upload(file)` runs steps 1–3 for you, including the direct-to-storage
 `PUT` in step 2. Step 1 refuses an empty `mimeType` with `400 INVALID_REQUEST`,

content/docs/permissions/system-context.mdx

@@ -186,7 +186,7 @@ One of the largest consumers of the flag;
 | 47b | The inbound-mail ingest seam: `ingest` admits the system context ALONE, and `rematch` admits it without the organization, owner or `manage_mailboxes` check | service-mailbox | Get: a mail source hands a mailbox its messages, and server code re-matches any mailbox. Lose: nothing a user held — every other caller of `ingest` is refused (`PERMISSION_DENIED`), because an ingested message is shown on every record its correspondents' addresses match and a user who could hand the seam a message could write one in a correspondent's name; every other caller of `rematch` must be in the mailbox's organization and own the mailbox or hold `manage_mailboxes` | `ingest`, `authorizeRematch` |
 | 47c | The inbound-mail IMAP sync: `syncMailbox` and `syncAll` admit the system context ALONE | service-mailbox | Get: the sync job reads every mailbox row (its organization, address and IMAP cursor), writes the cursor back, and hands each fetched message to `ingest` under the system context. Lose: nothing a user held — every other caller is refused (`PERMISSION_DENIED`), because a sync stores a mailbox's mail and moves its cursor | `syncMailbox`, `syncAll` |
 | 47d | The print service REFUSES the system context: `printRecordToFile` admits a human user acting for themselves alone | service-print | Get: nothing — a system caller is refused (`PERMISSION_DENIED`) before any page is read, session minted or browser started. Lose: nothing a user held — the PDF is rendered as the requesting user and never as the system, so a record is archived only by someone who could read it | `refuseUnlessHumanCaller` |
-| 47e | The caller-scoped attach verbs REFUSE the system context: `attachFileAs` and `assertMayAttach` admit a signed-in user alone | service-storage | Get: nothing — a system caller is refused (`PERMISSION_DENIED`); the system attaches through `attachFile`, whose rows name no user. Lose: nothing a user held — the caller-scoped verbs insert the attachment under the caller's context so every insert gate judges that user and both rows name them | `requireUserContext` |
+| 47e | The caller-scoped attach verbs REFUSE the system context: `attachFileAs` and `assertMayAttach` admit a signed-in user alone, and so do the caller-scoped record-file verbs the MCP `read_file` and `create_upload_link` tools call (`listRecordFilesAs`, `readRecordFileAs`, `createUploadLinkAs`) | service-storage | Get: nothing — a system caller is refused (`PERMISSION_DENIED`); the system attaches through `attachFile`, whose rows name no user. Lose: nothing a user held — the caller-scoped verbs insert the attachment under the caller's context so every insert gate judges that user and both rows name them, and the record-file verbs read the record and judge the file as that user, and bind an upload link to them | `packages/services/service-storage/src/file-attachment-service.ts#requireUserContext`, `packages/services/service-storage/src/record-file-access.ts#requireUserContext` |
 | 47f | The file-reference claim path asks no read verdict of a system write: a record write claims or copies a referenced file only as its caller may read it (the download door's verdict), and a system write carries no caller to ask | service-storage | Get: a system write claims or copies any file the organization-scoped lookup reaches, as before #25692; a deliberate server-side copy between records runs this way. Lose: nothing a user held — a user write is judged by the download door's verdict, and a context-less programmatic write is not asked either | `referencingCallerOf` |
 | 47g | The `sys_file` storage-owned columns guard returns early on create: a system insert keeps the `key`, `mime_type`, `size`, `status` and `etag` it writes | service-storage | Get: the storage service's own inserts (the upload doors, the field-file copy and backfill) write those five columns. Lose: nothing a user held — a non-system create has them dropped and starts `pending`, and on update the same columns are `readonly`, so the UPDATE `readonly` strip keeps them for every non-system caller | `installSysFileStorageOwnedColumnsGuard` |
 
@@ -677,6 +677,7 @@ and CI refuses one that differs from what the tree produces.
 | `packages/services/service-storage/src/attachment-access-hooks.ts#installAttachmentReadVisibility` | 1 | 44 |
 | `packages/services/service-storage/src/file-attachment-service.ts#requireUserContext` | 1 | 47e |
 | `packages/services/service-storage/src/file-reference-lifecycle.ts#referencingCallerOf` | 1 | 47f |
+| `packages/services/service-storage/src/record-file-access.ts#requireUserContext` | 1 | 47e |
 | `packages/services/service-storage/src/sys-file-storage-owned-columns.ts#installSysFileStorageOwnedColumnsGuard` | 1 | 47g |
 
 {/* END GENERATED: system-context-census */}

content/docs/permissions/tenant-audit-census.mdx

@@ -93,7 +93,7 @@ what moved this page's population from 225 to 227; nothing about the two sites
 changed, only whether this instrument could see them.
 
 **The expensive failure direction is a keyword.** Sites whose receiver the author
-typed `any` have no type to read, and there are 62 of them — just over a fifth
+typed `any` have no type to read, and there are 63 of them — just over a fifth
 of the population, concentrated in exactly the seed and bootstrap paths this
 control exists for. Scoring an unreadable receiver as "not an engine" would have
 dropped every one of them silently, with a clean exit and a smaller number that
@@ -132,7 +132,7 @@ are reported as `undecidable` rather than assumed either way.
 
 The same holds twice over for the context. An options argument spelled as a
 literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
-forwarding shim cannot, and **55 of the 263 sites are spelled that way**. A
+forwarding shim cannot, and **56 of the 265 sites are spelled that way**. A
 context resolved from an inline literal or a local `const` can be tested for
 `isSystem`; one arriving from a helper call cannot.
 
@@ -160,8 +160,8 @@ now **0**: nothing on this surface threads a context that provably lacks the fla
 
 **"No tenant context" counted sites it had not read.** An options argument the
 walker could not parse was folded into the same bucket as one it had read and
-found empty. That published **63 sites "carrying no tenant context at all"**
-when 8 said so and 55 were simply unread — an over-claim in the *alarming*
+found empty. That published **64 sites "carrying no tenant context at all"**
+when 8 said so and 56 were simply unread — an over-claim in the *alarming*
 direction, on the very figure this page tells other cards to cite. `carries` is
 now three-valued, and an unreadable argument can never contribute to the
 provable count.
@@ -197,10 +197,10 @@ reproduce them. Where it disagrees, it disagrees on the page:
 
 | carried figure | where it survives | this census |
 | :--- | :--- | ---: |
-| 175 write call sites | quoted in the merged changeset | **263** |
-| 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **29** more whose options argument is unreadable |
-| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **186 of 263** decidable, **77** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 146 decidably elevated, 0 decidably not, 109 undecidable |
+| 175 write call sites | quoted in the merged changeset | **265** |
+| 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **30** more whose options argument is unreadable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **187 of 265** decidable, **78** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 146 decidably elevated, 0 decidably not, 111 undecidable |
 | 141 and 132, two independent re-derivations | the card that filed this work | — |
 
 **The differences are not reconciled, and deliberately so.** The old census's
@@ -210,21 +210,21 @@ be stated is what this instrument counts, which is written above and re-runnable
 at any commit.
 
 Two structural facts do plausibly widen this reading against any hand or regex
-one, and both are counted in the generated tables below: the 62 sites reached
+one, and both are counted in the generated tables below: the 63 sites reached
 through an erased (`any`) receiver, and the 69 that name their object through a
 `const` rather than inline. An instrument that read either the way a person does
 would report a smaller number and would not say so.
 
 The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
 figure has no surviving corroboration anywhere in the tree.** This census reads
-146 of 263 (56%) as decidably elevated, with 109 more whose elevation is a
+146 of 265 (55%) as decidably elevated, with 111 more whose elevation is a
 run-time fact — so the claim is neither confirmed nor refuted, and the honest
 answer is that a static reading cannot settle it.
 
-⇒ **Cite `2 / 263`, and say what it is**: the sites whose options argument was
+⇒ **Cite `2 / 265`, and say what it is**: the sites whose options argument was
 READ and holds no tenant context, against a decidably tenancy-enabled object.
 That is the control's provable yield surface. ⛔ Do not cite it as "the sites
-without tenant context" — **29 further sites** have an options argument this
+without tenant context" — **30 further sites** have an options argument this
 cannot read, and they are neither in nor out.
 
 {/* BEGIN GENERATED: tenant-audit-census (scripts/tenant-audit-census.mjs) — DO NOT EDIT */}
@@ -233,31 +233,31 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **263** |
-| …whose object name is statically decidable | 186 |
-| …whose object name is chosen at run time | 77 |
-| …against an object with tenancy ENABLED | 180 |
+| write call sites on the application surface | **265** |
+| …whose object name is statically decidable | 187 |
+| …whose object name is chosen at run time | 78 |
+| …against an object with tenancy ENABLED | 181 |
 | …against an object that declares tenancy off | 6 |
-| threading a tenant context | 200 |
+| threading a tenant context | 201 |
 | PROVABLY carrying none (options read, no context key) | **8** |
 | …of those, against a decidably tenancy-enabled object | **2** |
-| options argument UNREADABLE — may or may not carry one | 55 |
-| …of those, against a decidably tenancy-enabled object | 29 |
+| options argument UNREADABLE — may or may not carry one | 56 |
+| …of those, against a decidably tenancy-enabled object | 30 |
 | threading a decidably ELEVATED (`isSystem`) context | 146 |
 | threading a context that is decidably NOT elevated | 0 |
-| threading a context whose elevation is a run-time fact | 109 |
+| threading a context whose elevation is a run-time fact | 111 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
-| receiver carried a readable engine type | 201 |
-| receiver erased, placed by the object NAME | 52 |
+| receiver carried a readable engine type | 202 |
+| receiver erased, placed by the object NAME | 53 |
 | receiver erased, placed by an `object: string` PARAMETER | 5 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
 
-| object name spelled inline | 117 |
+| object name spelled inline | 118 |
 | object name spelled through a `const` | 69 |
 | object name is an `object: string` parameter | 7 |
-| object name is some other run-time expression | 70 |
+| object name is some other run-time expression | 71 |
 
 ### Subtractions the census could NOT defend — enforced
 
@@ -307,13 +307,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-11-06 at `ac688f409`.
+Measured on 2026-11-06 at `8d23d8234`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 1037 |
-| engine-shaped types recognised | 111 |
+| tracked non-test sources scanned | 1045 |
+| engine-shaped types recognised | 112 |
 | declared objects in the registry | 130 |
-| same-named calls subtracted as non-engine | 230 |
+| same-named calls subtracted as non-engine | 234 |
 
 {/* END GENERATED: tenant-audit-census */}