@bloklabs/mcp 2.0.0 → 2.1.0

package/README.md

@@ -152,7 +152,7 @@ Stored mode is refused when `--sync-url` is set. A sync service owns those docum
 - On an ASP.NET host, `IBlokAuthorization` sees the agent's actor id, not the human's. Map it back to the human for your document checks.
 - `--authorize <module|url>` decides who may open what:
   - A URL is a webhook. It gets `POST { "principal", "documentId", "write" }` and must answer `200 { "allowed": true | false }`. Any other answer means no.
-  - Anything else is a module path. Its default export is `(principal, documentId, write) => Promise<boolean>`.
+  - Anything else is a module path. Its default export is `(principal, documentId, write) => Promise<boolean>`. Node only: the C#, Go and Rust builds take only a webhook URL and refuse a module path at startup.
   - It runs before every open, and again on each later call.
   - `blok_list_documents` shows only the documents it allows the caller to read. Without it, the list is unfiltered.
 - `--page-titles page-map` lets agents rename other pages and set their icons. It shows up only if your host reads each page's title from that page document's title.
@@ -183,6 +183,8 @@ An agent can upload a file with `image.uploadFile`, `video.uploadFile`, `audio.u
 - `uploads.limits` sets `types` and `maxSize` per kind, like a media tool's own config. The defaults are the tools' defaults: `image/*`, `audio/*` and `video/*`, any type for files; 30 MiB, and 100 MiB for video.
   - The size is checked before the bytes are decoded.
 - An SVG is sent unchanged, as a person's upload sends it. Leave `image/svg+xml` out of `types` if your storage serves it on your own origin.
+- When your uploader throws, the agent sees `TOOL_ACTION_FAILED` with the message "The upload failed." Your error's own message never reaches the agent, because it may name hosts, paths or credentials. The server logs the full error to stderr.
+  - To tell the agent something, set a string `agentMessage` on the error you throw. The agent sees that text instead: `throw Object.assign(new Error('quota exceeded for tenant 42'), { agentMessage: 'The storage is full.' })`.
 - An upload runs alone in its batch. When the batch fails after the upload, `error.details.orphaned` names the stored file. Delete it yourself.
 - The server does not compress images, turn GIFs into video, read audio tags or make variants. The editor does those in the browser.
 
@@ -241,7 +243,7 @@ Pass a value as the next argument: `--auth oauth`, not `--auth=oauth`. An unknow
 | `--oauth-issuer <url>` | | none | Expected token issuer. |
 | `--oauth-audience <url>` | | none | This server's resource id. |
 | `--oauth-jwks <url>` | | none | Issuer's JWKS URL. |
-| `--authorize <module\|url>` | | none | Per-document access hook. |
+| `--authorize <module\|url>` | | none | Per-document access hook. A module path works in Node only. |
 | `--principal <name>` | | `local` | Who the caller is over stdio. |
 | `--manifest <file>` | | none | Custom block and inline tools. |
 | `--manifest-overrides <file>` | | none | Tool and action overrides. |
@@ -252,6 +254,26 @@ Pass a value as the next argument: `--auth oauth`, not `--auth=oauth`. An unknow
 | `--max-handles <n>` | | `8` | Open handles per principal. |
 | `--no-comments` | | comments on | Turn off the database comment commands. A host that keeps comments in its own system (a `comments` hook) must pass it, or agent comments stay invisible to people. `--comments` is accepted and changes nothing. |
 
+## Other builds: C#, Go and Rust
+
+The same server is also written in C#, Go and Rust. They take the same flags and environment variables, and one shared conformance suite checks each against this package. No release has shipped them yet.
+
+| Build | Install | In your app | README |
+|---|---|---|---|
+| C# | `dotnet tool install -g Blok.Mcp`, or `dnx Blok.Mcp` | `builder.Services.AddBlokMcp(...)` and `app.MapBlokMcp("/mcp")`, from the `Blok.Server.Mcp` NuGet package | `packages/server/dotnet/Blok.Mcp`, `packages/server/dotnet/Blok.Server.Mcp` |
+| Go | `go install github.com/JackUait/blok/packages/server/go/v2/cmd/blok-mcp@latest` | `blokmcp.New(blokmcp.Options{...})`, then `Handler()` or `ServeStdio` | `packages/server/go/blokmcp` |
+| Rust | Build from source: `cargo build --release -p blok-mcp` in `packages/server/rust` | `blok_mcp::Embedded::new(...)` | `packages/server/rust/crates/mcp` |
+
+Each library's options change faster than this page. Its README lists them.
+
+Where they differ from this package, on purpose:
+
+- `--authorize` takes only an http(s) webhook URL. A module path is JavaScript, so they refuse it at startup.
+- Uploads work only through the library API, as here: give the library your uploader. There is no flag for them.
+- Each call runs in an embedded JavaScript engine, with a 60 second limit per call. Node has no such limit.
+- Each engine also has a memory budget. C# counts 2 GiB of allocations per call, Go stops a call whose heap grows by about 1 GiB, and Rust lets one call hold 256 MiB.
+- The C# library opens live handles only on the rooms of its own app (`LiveRooms`), in the same process, with no socket and no ticket. The `Blok.Mcp` tool joins a remote sync service with `--sync-url`, as here.
+
 ## Limits
 
 - Uploads need an embedded server with `uploads` (see Uploads). The CLI adds media by URL only.