@bloklabs/server 2.0.0 → 2.1.0

package/README.md

@@ -59,6 +59,46 @@ The switch covers all of Kestrel's HTTP/1 parsing. The request line and the head
 
 The Go and Rust hosts refuse bare LF line ends as well.
 
+### An MCP endpoint in your app
+
+`Blok.Server.Mcp` serves Blok's MCP tools from your own app, like `blok-mcp --http`:
+
+```csharp
+using Blok.Server.Mcp;
+
+builder.Services.AddBlokMcp(options =>
+{
+  options.FilesDirectory = "./documents";
+  options.Authorize = (request, _) => ValueTask.FromResult(CanOpen(request.Principal, request.DocumentId, request.Write));
+});
+
+var app = builder.Build();
+
+app.MapBlokMcp("/mcp");
+app.Run();
+```
+
+It needs a per-document check, as `blok-mcp --http` needs `--authorize`:
+
+- Set `Authorize`, or register `IBlokAuthorization`.
+- With neither, `MapBlokMcp` throws at startup. OAuth alone is not enough: it says who calls, not which documents they may open.
+- `AllowEveryCallerEveryDocument = true` turns the check off. Use it only where nothing untrusted can reach the endpoint.
+
+Browsers and DNS rebinding:
+
+- A request with a foreign `Origin` gets 403. By default only loopback pages (`http://localhost`, `127.0.0.1`, `[::1]`) may call. List your own in `AllowedOrigins`.
+- `AllowedHosts` limits the `Host` header to the names you list. Without it, set ASP.NET Core's own `AllowedHosts` host filtering.
+- Without OAuth, a caller your own auth did not sign in is the default `Principal`. So only this machine may call: a request from a non-loopback address gets 403, whatever its `Host` header says. Set `TrustRemoteCallers` when a proxy or the network already decides who may connect.
+
+The other options follow `createBlokMcpServer` in `@bloklabs/mcp`: `PageTitles`, `Manifest`, `Overrides`, `SyncUrl` with `TicketSecret` or `TicketUrl`, `AgentActor`, `Uploads` and the rest. They are checked at startup with the same rules. Two of Node's options are not here:
+
+- `uploads.root` reads local files, and Node allows it over stdio only.
+- The stdio form: run the `blok-mcp` tool for that.
+
+When the `Uploads` uploader throws, the agent sees only "The upload failed." and the full exception goes to the app's log. To show the agent a message, throw `BlokMcpUploadException("…")`. Write that message for the agent: no paths, hosts or secrets.
+
+With `TicketUrl` and no document source, the host's ticket route decides who may open what, so no `Authorize` is needed.
+
 ## Convert documents
 
 `Blok.Server` embeds Blok's own serializer as a JavaScript bundle and runs it in this process. A document therefore converts through the editor's implementation, not a port of it. A port has to be taught every block Blok gains, and it silently drops the ones nobody remembered.
@@ -757,12 +797,23 @@ go test -p 2 ./...
 The release workflow ships the Go server in two forms. No release has shipped them yet.
 
 - **Module.** `yarn release X.Y.Z` also tags `packages/server/go/vX.Y.Z` on the release commit. Go reads a module in a subdirectory only from tags with that prefix. The module path is `github.com/JackUait/blok/packages/server/go/v2`. Import `blokserver` for the routes and `blokdocs` for the converter. Your own operation store and activity observer go in `Options.CollabOperationStore` and `Options.CollabActivityObserver`. Their types are in `blokserver/collabstore`. To put your own auth in front of the routes, use `Server.HandlerWithAuth(prefix, auth)`. It works like `RequireAuthorization()` on the C# group: health and CORS preflights stay open.
+- **MCP server.** Import `blokmcp` to run blok-mcp inside your own Go program. `Server.Handler()` serves it on a listener you own, so `New` cannot check that the listener is loopback. Without `Transport.Public`, the handler answers only callers whose address is loopback, and 403 to everyone else. Behind a reverse proxy every caller looks loopback, so set `Transport.Public` and `Auth.Kind: "oauth"` there.
 - **Archives.** The GitHub release gets `blok-server-go_<os>_<arch>` for macOS, Linux and Windows, on amd64 and arm64, with `checksums-go.txt`. They are built with cgo off, so they are static. The release starts the Linux amd64 one on Alpine before it uploads.
 
 The binary reports its release version on `/health`. A local `go build` reports `dev`.
 
 These names never overlap the C# archives or `checksums.txt`. The npm wrapper downloads only the C# archives, and a test fails if it ever names a Go one.
 
+## MCP server
+
+Blok's MCP server lets an MCP client read and edit Blok documents. Besides the Node package, `@bloklabs/mcp`, it comes in three builds next to the servers here. No release has shipped them yet. All four take the same flags, and one shared suite checks each of them against Node: `node scripts/test-mcp-conformance.mjs --target node|csharp|go|rust`.
+
+- **C#.** Two NuGet packages. `Blok.Mcp` is a .NET tool: `dotnet tool install -g Blok.Mcp`, or `dnx Blok.Mcp`. `Blok.Server.Mcp` adds it to an ASP.NET Core app with `builder.Services.AddBlokMcp(...)` and `app.MapBlokMcp("/mcp")`. See `dotnet/Blok.Mcp/README.md` and `dotnet/Blok.Server.Mcp/README.md`.
+- **Go.** `go install github.com/JackUait/blok/packages/server/go/v2/cmd/blok-mcp@latest`, or embed it with `blokmcp.New`. The release also ships `blok-mcp-go_<os>_<arch>` archives beside the Go server's. See `go/blokmcp/README.md`.
+- **Rust.** `cargo build --release -p blok-mcp` in `rust/`. Like the Rust server, it ships nothing yet. See `rust/crates/mcp/README.md`.
+
+The release packs both NuGets with the release version, and writes that version into `Blok.Mcp`'s `.mcp/server.json`.
+
 ## Docs
 
 Full configuration and deployment guidance: [https://blokeditor.com/docs](https://blokeditor.com/docs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/server",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Blok server delivery for ASP.NET Core, npm, and Docker — shared C# routes for file uploads and link previews.",
   "license": "Apache-2.0",
   "author": "JackUait",