@silkweave/mcp 1.9.0 → 1.10.0

package/.turbo/turbo-build.log

@@ -1,13 +1,13 @@
 $ tsdown
-ℹ tsdown v0.21.8 powered by rolldown v1.0.0-rc.15
+ℹ tsdown v0.21.10 powered by rolldown v1.0.0-rc.17
 ℹ config file: /Users/atomic/projects/silkweave/silkweave/packages/mcp/tsdown.config.ts 
 ℹ entry: src/index.ts
 ℹ tsconfig: tsconfig.json
 ℹ Build start
 ℹ Cleaning 4 files
-ℹ build/index.mjs        17.31 kB │ gzip: 5.04 kB
-ℹ build/index.mjs.map    32.92 kB │ gzip: 9.07 kB
-ℹ build/index.d.mts.map   1.22 kB │ gzip: 0.55 kB
-ℹ build/index.d.mts       3.71 kB │ gzip: 1.36 kB
-ℹ 4 files, total: 55.16 kB
-✔ Build complete in 673ms
+ℹ build/index.mjs        22.50 kB │ gzip:  6.48 kB
+ℹ build/index.mjs.map    41.78 kB │ gzip: 11.23 kB
+ℹ build/index.d.mts.map   2.08 kB │ gzip:  0.80 kB
+ℹ build/index.d.mts       8.15 kB │ gzip:  2.86 kB
+ℹ 4 files, total: 74.51 kB
+✔ Build complete in 699ms

package/.turbo/turbo-check.log

@@ -1,4 +1,3 @@
 $ pnpm lint && pnpm typecheck
 $ eslint
-[ELIFECYCLE] Command failed.
-[ELIFECYCLE] Command failed.
+$ tsc --noEmit

package/.turbo/turbo-lint.log

@@ -1,5 +1,2 @@
 
-
-> @silkweave/mcp@1.7.1 lint /Users/atomic/projects/silkweave/silkweave/packages/mcp
-> eslint
-
+$ eslint

package/.turbo/turbo-prepack.log

@@ -1,24 +1,15 @@
 
-
-> @silkweave/mcp@1.8.0 prepack /Users/atomic/projects/silkweave/silkweave/packages/mcp
-> pnpm clean && pnpm build
-
-
-> @silkweave/mcp@1.8.0 clean /Users/atomic/projects/silkweave/silkweave/packages/mcp
-> rimraf build
-
-
-> @silkweave/mcp@1.8.0 build /Users/atomic/projects/silkweave/silkweave/packages/mcp
-> tsdown
-
-ℹ tsdown v0.21.8 powered by rolldown v1.0.0-rc.15
+$ pnpm clean && pnpm build
+$ rimraf build
+$ tsdown
+ℹ tsdown v0.21.10 powered by rolldown v1.0.0-rc.17
 ℹ config file: /Users/atomic/projects/silkweave/silkweave/packages/mcp/tsdown.config.ts 
 ℹ entry: src/index.ts
 ℹ tsconfig: tsconfig.json
 ℹ Build start
-ℹ build/index.mjs        16.50 kB │ gzip: 4.74 kB
-ℹ build/index.mjs.map    30.99 kB │ gzip: 8.52 kB
-ℹ build/index.d.mts.map   0.93 kB │ gzip: 0.43 kB
-ℹ build/index.d.mts       2.15 kB │ gzip: 0.80 kB
-ℹ 4 files, total: 50.57 kB
-✔ Build complete in 755ms
+ℹ build/index.mjs        22.50 kB │ gzip:  6.48 kB
+ℹ build/index.mjs.map    41.78 kB │ gzip: 11.23 kB
+ℹ build/index.d.mts.map   2.08 kB │ gzip:  0.80 kB
+ℹ build/index.d.mts       8.15 kB │ gzip:  2.86 kB
+ℹ 4 files, total: 74.51 kB
+✔ Build complete in 627ms

package/README.md

@@ -85,6 +85,37 @@ await silkweave({ name: 'my-tools', description: 'My Tools', version: '1.0.0' })
 
 Logging notifications (`logger.info()`, `logger.progress()`) are sent to the MCP client as `notifications/message` and `notifications/progress`.
 
+## Streaming Actions
+
+Actions that declare a `chunk` schema and an `async function*` `run` (see [`@silkweave/core`](https://www.npmjs.com/package/@silkweave/core) for the action definition) stream over MCP using `notifications/progress`:
+
+- The client opts in by sending `_meta.progressToken` with the tool call. The MCP TypeScript SDK does this automatically when the host registers a progress listener.
+- For each yielded chunk, the adapter sends a `notifications/progress` with the same `progressToken`, a 1-based `progress` counter, and the JSON-stringified chunk in the `message` field. The send is awaited so transport backpressure flows back to your generator.
+- The tool call resolves with the full buffered chunk array as the `CallToolResult`. Clients that did not opt in (no `progressToken`) receive only this final result.
+
+```typescript
+import { createAction } from '@silkweave/core'
+import z from 'zod/v4'
+
+createAction({
+  name: 'generate-messages',
+  description: 'Stream messages about a topic',
+  input: z.object({ topic: z.string(), count: z.number().int().min(1).max(50) }),
+  chunk: z.object({ index: z.number().int(), text: z.string() }),
+  run: async function* ({ topic, count }) {
+    for (let i = 0; i < count; i += 1) {
+      yield { index: i, text: `Message ${i + 1} about ${topic}` }
+    }
+  }
+})
+```
+
+### What this means for AI hosts
+
+MCP `notifications/progress` is part of the standard protocol - chunks reach the wire correctly. But **what the host client does with them is up to the host**. Most LLM-driven MCP hosts today (Claude Code, Cursor, generic chat UIs) consume progress notifications for **UI rendering** (spinners, status text, progress bars) and **not** as incremental data fed into the model's context. From the model's perspective, an MCP tool call is still atomic - the model sees the final buffered result when the call returns, not the chunks in flight.
+
+This is a host-side rendering choice, not a protocol limitation. If you need per-chunk model visibility today, expose the action via [`@silkweave/fastify`](https://www.npmjs.com/package/@silkweave/fastify) (SSE/NDJSON) or [`@silkweave/trpc`](https://www.npmjs.com/package/@silkweave/trpc) (subscriptions) and have your consumer iterate chunks directly.
+
 ## Smart Tool Results
 
 By default, all MCP adapters use `smartToolResult()` to format action return values:

package/build/index.d.mts

@@ -1,9 +1,11 @@
 import { CallToolResult, ContentBlock, EmbeddedResource } from "@modelcontextprotocol/sdk/types.js";
 import { Action, AdapterFactory, SilkweaveContext, SilkweaveError, SilkweaveOptions } from "@silkweave/core";
 import { CreateMcpExpressAppOptions } from "@modelcontextprotocol/sdk/server/express.js";
-import { AuthConfig } from "@silkweave/auth";
+import { Express, RequestHandler } from "express";
+import { AuthConfig, AuthInfo } from "@silkweave/auth";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { CorsOptions, CorsOptions as CorsOptions$1 } from "cors";
-import { Express } from "express";
+import { Server } from "http";
 
 //#region src/adapter/cliProxy.d.ts
 type CLIFormatterFn = (message: ContentBlock, index: number, messages: ContentBlock[]) => string | undefined;
@@ -13,43 +15,137 @@ interface CliProxyOptions {
 }
 declare const cliProxy: AdapterFactory<CliProxyOptions>;
 //#endregion
-//#region src/lib/handler.d.ts
-/** Headers required by the MCP protocol that must always be exposed when CORS is in use. */
-declare const MCP_REQUIRED_HEADERS: string[];
-interface CreateMcpExpressHandlerOptions extends CreateMcpExpressAppOptions {
-  /** Bearer-token / OAuth auth configuration. Omit to disable auth entirely. */
+//#region src/adapter/http.d.ts
+interface StartMcpHttpOptions extends CreateMcpExpressAppOptions {
+  host: string;
+  port: number;
   auth?: AuthConfig;
-  /** CORS configuration. `false` to disable, `true`/`undefined` for permissive defaults, or a CorsOptions object. */
+  /** CORS configuration. `false` to disable, omitted/`true` for permissive defaults, or a `CorsOptions` object. */
   cors?: CorsOptions$1 | boolean;
-  /** Hostname for the underlying express app (used by some MCP SDK checks). Default `'0.0.0.0'`. */
-  host?: string;
-  /** Mount the `/resource/:id` sideload route on the returned app. Default `true`. */
+  /** Mount the `/resource/:id` sideload route. Default `true`. */
   sideloadResources?: boolean;
+  /** Directory the sideload route reads from. Default `'resources'`. */
+  resourceDir?: string;
 }
 /**
- * Build an Express sub-app exposing the MCP Streamable HTTP transport, OAuth
- * routes (if configured), and bearer-token auth middleware. The returned app
- * can be listened on directly OR mounted onto an existing server via
- * `parentApp.use(basePath, app)` / Nest's `httpAdapter.use(basePath, app)`.
+ * Build a fully-wired Express app that exposes the MCP Streamable HTTP
+ * transport (plus OAuth / sideload / well-known routes when configured).
  *
- * Used by `@silkweave/mcp`'s `http()` adapter (server-owning) and
- * `@silkweave/nestjs`'s `mcp()` adapter (mounts on Nest's HTTP server).
+ * Pass the resulting `app` to `app.listen(port, host)` yourself, or use the
+ * top-level `startMcpServer()` / `http()` adapter conveniences.
  */
-declare function createMcpExpressHandler(silkweaveOptions: SilkweaveOptions, context: SilkweaveContext, actions: Action[], options?: CreateMcpExpressHandlerOptions): Express;
-//#endregion
-//#region src/adapter/http.d.ts
-interface HttpAdapterOptions extends Omit<CreateMcpExpressHandlerOptions, 'auth' | 'cors'> {
-  host: string;
-  port: number;
-  auth?: AuthConfig;
-  /** CORS configuration. `false` to disable, `true`/`undefined` for permissive defaults, or a CorsOptions object. */
-  cors?: CorsOptions$1 | boolean;
-}
-declare const http: AdapterFactory<HttpAdapterOptions>;
+declare function buildMcpExpressApp(silkweaveOptions: SilkweaveOptions, context: SilkweaveContext, actions: Action[], options: StartMcpHttpOptions): Express;
+/**
+ * Spin up a standalone MCP Streamable HTTP server on `host:port` for the
+ * given `actions`. Returns the underlying `Server` so callers can close it.
+ *
+ * Convenience for use cases that don't go through the `silkweave()` builder.
+ */
+declare function startMcpServer(silkweaveOptions: SilkweaveOptions, actions: Action[], options: StartMcpHttpOptions, context?: SilkweaveContext): Promise<Server>;
+/**
+ * Silkweave adapter that owns its own HTTP server. Composes the MCP handler
+ * primitives into a fully-wired Express app and listens on `host:port`.
+ */
+declare const http: AdapterFactory<StartMcpHttpOptions>;
 //#endregion
 //#region src/adapter/stdio.d.ts
 declare const stdio: AdapterFactory;
 //#endregion
+//#region src/handlers/auth.d.ts
+/**
+ * Per-request bearer-token storage used by tool handlers to read the resolved
+ * `AuthInfo` for the currently-handled MCP call.
+ */
+declare const authStorage: AsyncLocalStorage<AuthInfo>;
+/**
+ * Express middleware that validates the `Authorization: Bearer …` header via
+ * the supplied `AuthConfig`. On success the resolved `AuthInfo` is placed in
+ * `authStorage` for the duration of the downstream handler - `mcpTransport`'s
+ * tool callbacks pick it up to populate the silkweave context's `auth` key.
+ *
+ * The middleware should NOT be applied to OAuth-discovery / token routes -
+ * compose it only on the routes that require an authenticated caller (the MCP
+ * transport itself, sideload, etc.).
+ */
+declare function authMiddleware(auth: AuthConfig, context: SilkweaveContext): RequestHandler;
+//#endregion
+//#region src/handlers/cors.d.ts
+/** Headers required by the MCP protocol that must always be exposed when CORS is in use. */
+declare const MCP_REQUIRED_HEADERS: string[];
+/**
+ * CORS middleware preconfigured to expose the headers MCP clients need
+ * (`Mcp-Session-Id`, `Last-Event-Id`, `Mcp-Protocol-Version`, `WWW-Authenticate`)
+ * on top of any user-supplied options.
+ *
+ * Pass `false` to disable, omit / pass `true` for permissive defaults, or pass
+ * a `CorsOptions` object to override.
+ */
+declare function mcpCors(corsConfig?: CorsOptions$1 | boolean): RequestHandler | null;
+//#endregion
+//#region src/handlers/metadata.d.ts
+/**
+ * Handler for `GET /.well-known/oauth-protected-resource` (RFC 9728). Returns
+ * the resource server's metadata pointing at the configured authorization
+ * servers. Requires `auth.resourceUrl` and a non-empty `auth.authorizationServers`.
+ */
+declare function protectedResourceMetadata(auth: AuthConfig): RequestHandler;
+//#endregion
+//#region src/handlers/oauth.d.ts
+interface OAuthRouteHandlers {
+  /** `GET /.well-known/oauth-authorization-server` - RFC 8414 discovery. */
+  wellKnownAuthServer: RequestHandler;
+  /** `GET /authorize` - start the OAuth flow. */
+  authorize: RequestHandler;
+  /** `GET {callbackPath}` - provider callback. */
+  callback: RequestHandler;
+  /** Path the provider should redirect to (defaults to `/auth/callback`). */
+  callbackPath: string;
+  /** `POST /token` - exchange code / refresh token. Includes urlencoded body parser. */
+  token: RequestHandler[];
+  /** `POST /register` - dynamic client registration. Includes JSON body parser. */
+  register: RequestHandler[];
+}
+/**
+ * Build the OAuth 2.1 proxy route handlers (authorize, callback, token,
+ * register, well-known) backed by the configured `auth.provider`. Returns the
+ * handlers as individual `RequestHandler`s so callers can register them
+ * wherever they like - under `/mcp`, at the server root, etc.
+ *
+ * `token` and `register` are returned as middleware arrays because the
+ * appropriate body parser must run before the handler. Apply with
+ * `app.post(path, ...token)`.
+ */
+declare function oauthRoutes(auth: AuthConfig): OAuthRouteHandlers;
+//#endregion
+//#region src/handlers/sideload.d.ts
+interface SideloadResourceOptions {
+  /** Directory to read sideload resources from. Defaults to `resources/` (cwd-relative). */
+  resourceDir?: string;
+}
+/**
+ * Handler for `GET /resource/:id` - serves a large MCP response that was
+ * sideloaded to disk as a `{id}` payload with a `{id}.json` metadata sidecar.
+ *
+ * The route param `id` is provided by the host framework (Express, Nest, etc.).
+ */
+declare function sideloadResource(options?: SideloadResourceOptions): RequestHandler;
+//#endregion
+//#region src/handlers/transport.d.ts
+interface McpTransportHandlers {
+  /** `POST /mcp` - initialize session or dispatch request to an existing one. */
+  post: RequestHandler;
+  /** `GET /mcp` and `DELETE /mcp` - long-poll session stream / session termination. Also covers `GET /mcp/resource/:id`. */
+  stream: RequestHandler;
+}
+/**
+ * Build the MCP Streamable HTTP transport route handlers.
+ *
+ * Sessions are kept in a per-call closure (one map per `mcpTransport()` call),
+ * so the same handler object should be registered for all three transport
+ * routes - `POST /mcp`, `GET /mcp`, `DELETE /mcp` - to share session state.
+ */
+declare function mcpTransport(silkweaveOptions: SilkweaveOptions, context: SilkweaveContext, actions: Action[]): McpTransportHandlers;
+//#endregion
 //#region src/util/result.d.ts
 declare function smartToolResult(data: string | object | object[]): CallToolResult;
 declare function jsonToolResult(data: object, isError?: boolean): CallToolResult;
@@ -75,5 +171,5 @@ declare function createSideloadResource(buffer: Buffer, {
   contentType
 }: Pick<SideloadResource, 'name' | 'contentType'>): Promise<SideloadResource>;
 //#endregion
-export { CLIFormatterFn, CliProxyOptions, type CorsOptions, CreateMcpExpressHandlerOptions, HttpAdapterOptions, MCP_REQUIRED_HEADERS, SideloadResource, cliProxy, createMcpExpressHandler, createSideloadResource, errorToolResult, handleToolError, http, jsonToolResult, parseResourceMessage, smartToolResult, stdio };
+export { CLIFormatterFn, CliProxyOptions, type CorsOptions, MCP_REQUIRED_HEADERS, McpTransportHandlers, OAuthRouteHandlers, SideloadResource, SideloadResourceOptions, StartMcpHttpOptions, authMiddleware, authStorage, buildMcpExpressApp, cliProxy, createSideloadResource, errorToolResult, handleToolError, http, jsonToolResult, mcpCors, mcpTransport, oauthRoutes, parseResourceMessage, protectedResourceMetadata, sideloadResource, smartToolResult, startMcpServer, stdio };
 //# sourceMappingURL=index.d.mts.map

package/build/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/adapter/cliProxy.ts","../src/lib/handler.ts","../src/adapter/http.ts","../src/adapter/stdio.ts","../src/util/result.ts","../src/util/sideload.ts"],"mappings":";;;;;;;;KAaY,cAAA,IAAkB,OAAA,EAAS,YAAA,EAAc,KAAA,UAAe,QAAA,EAAU,YAAA;AAAA,UAE7D,eAAA;EACf,GAAA,EAAK,GAAA;EACL,SAAA,GAAY,cAAA;AAAA;AAAA,cAgCD,QAAA,EAAU,cAAA,CAAe,eAAA;;;;cC7BzB,oBAAA;AAAA,UAEI,8BAAA,SAAuC,0BAAA;EDT5C;ECWV,IAAA,GAAO,UAAA;;EAEP,IAAA,GAAO,aAAA;EDb8B;ECerC,IAAA;EDfmD;ECiBnD,iBAAA;AAAA;;;ADfF;;;;;;;iBCqNgB,uBAAA,CACd,gBAAA,EAAkB,gBAAA,EAClB,OAAA,EAAS,gBAAA,EACT,OAAA,EAAS,MAAA,IACT,OAAA,GAAS,8BAAA,GACR,OAAA;;;UClOc,kBAAA,SAA2B,IAAA,CAAK,8BAAA;EAC/C,IAAA;EACA,IAAA;EACA,IAAA,GAAO,UAAA;EFGG;EEDV,IAAA,GAAO,aAAA;AAAA;AAAA,cAGI,IAAA,EAAM,cAAA,CAAe,kBAAA;;;cCoBrB,KAAA,EAAO,cAAA;;;iBC/BJ,eAAA,CAAgB,IAAA,+BAAmC,cAAA;AAAA,iBAqBnD,cAAA,CAAe,IAAA,UAAc,OAAA,aAAkB,cAAA;AAAA,iBAM/C,eAAA,CAAA;EAAkB,IAAA;EAAM,IAAA;EAAM;AAAA,GAAW,cAAA,GAAiB,cAAA;AAAA,iBAU1D,eAAA,CAAgB,KAAA,YAAiB,cAAA;AAAA,iBAUjC,oBAAA,CAAA;EAAuB;AAAA,GAAY,gBAAA;;;UChDlC,gBAAA;EACf,EAAA;EACA,IAAA;EACA,WAAA;EACA,IAAA;AAAA;AAAA,iBAGoB,sBAAA,CAAuB,MAAA,EAAQ,MAAA;EAAU,IAAA;EAAM;AAAA,GAAe,IAAA,CAAK,gBAAA,4BAAyC,OAAA,CAAA,gBAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/adapter/cliProxy.ts","../src/adapter/http.ts","../src/adapter/stdio.ts","../src/handlers/auth.ts","../src/handlers/cors.ts","../src/handlers/metadata.ts","../src/handlers/oauth.ts","../src/handlers/sideload.ts","../src/handlers/transport.ts","../src/util/result.ts","../src/util/sideload.ts"],"mappings":";;;;;;;;;;KAWY,cAAA,IAAkB,OAAA,EAAS,YAAA,EAAc,KAAA,UAAe,QAAA,EAAU,YAAA;AAAA,UAE7D,eAAA;EACf,GAAA,EAAK,GAAA;EACL,SAAA,GAAY,cAAA;AAAA;AAAA,cA4DD,QAAA,EAAU,cAAA,CAAe,eAAA;;;UC9DrB,mBAAA,SAA4B,0BAAA;EAC3C,IAAA;EACA,IAAA;EACA,IAAA,GAAO,UAAA;EDLG;ECOV,IAAA,GAAO,aAAA;;EAEP,iBAAA;EDTqC;ECWrC,WAAA;AAAA;;;;;ADTF;;;iBCmBgB,kBAAA,CACd,gBAAA,EAAkB,gBAAA,EAClB,OAAA,EAAS,gBAAA,EACT,OAAA,EAAS,MAAA,IACT,OAAA,EAAS,mBAAA,GACR,OAAA;;;;;;;iBAiDmB,cAAA,CACpB,gBAAA,EAAkB,gBAAA,EAClB,OAAA,EAAS,MAAA,IACT,OAAA,EAAS,mBAAA,EACT,OAAA,GAAU,gBAAA,GACT,OAAA,CAAQ,MAAA;;;;;cAgBE,IAAA,EAAM,cAAA,CAAe,mBAAA;;;cCxDrB,KAAA,EAAO,cAAA;;;;;;;cC1CP,WAAA,EAAW,iBAAA,CAAA,QAAA;;AHExB;;;;;;;;;iBGUgB,cAAA,CAAe,IAAA,EAAM,UAAA,EAAY,OAAA,EAAS,gBAAA,GAAmB,cAAA;;;;cCjBhE,oBAAA;;;;;;;AJOb;;iBIGgB,OAAA,CAAQ,UAAA,GAAY,aAAA,aAA+B,cAAA;;;;;;;;iBCNnD,yBAAA,CAA0B,IAAA,EAAM,UAAA,GAAa,cAAA;;;UCa5C,kBAAA;;EAEf,mBAAA,EAAqB,cAAA;;EAErB,SAAA,EAAW,cAAA;;EAEX,QAAA,EAAU,cAAA;;EAEV,YAAA;ENlBwB;EMoBxB,KAAA,EAAO,cAAA;ENpBiF;EMsBxF,QAAA,EAAU,cAAA;AAAA;;;;;;ANpBZ;;;;;iBMiCgB,WAAA,CAAY,IAAA,EAAM,UAAA,GAAa,kBAAA;;;UC1C9B,uBAAA;;EAEf,WAAA;AAAA;;;;;;APKF;iBOIgB,gBAAA,CAAiB,OAAA,GAAS,uBAAA,GAA+B,cAAA;;;UC6ExD,oBAAA;;EAEf,IAAA,EAAM,cAAA;;EAEN,MAAA,EAAQ,cAAA;AAAA;;;ARrFV;;;;;iBQ+FgB,YAAA,CACd,gBAAA,EAAkB,gBAAA,EAClB,OAAA,EAAS,gBAAA,EACT,OAAA,EAAS,MAAA,KACR,oBAAA;;;iBC1Ga,eAAA,CAAgB,IAAA,+BAAmC,cAAA;AAAA,iBAqBnD,cAAA,CAAe,IAAA,UAAc,OAAA,aAAkB,cAAA;AAAA,iBAM/C,eAAA,CAAA;EAAkB,IAAA;EAAM,IAAA;EAAM;AAAA,GAAW,cAAA,GAAiB,cAAA;AAAA,iBAU1D,eAAA,CAAgB,KAAA,YAAiB,cAAA;AAAA,iBAUjC,oBAAA,CAAA;EAAuB;AAAA,GAAY,gBAAA;;;UChDlC,gBAAA;EACf,EAAA;EACA,IAAA;EACA,WAAA;EACA,IAAA;AAAA;AAAA,iBAGoB,sBAAA,CAAuB,MAAA,EAAQ,MAAA;EAAU,IAAA;EAAM;AAAA,GAAe,IAAA,CAAK,gBAAA,4BAAyC,OAAA,CAAA,gBAAA"}