silkweave 1.3.1 → 1.4.0

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> silkweave@1.3.0 build /Users/atomic/projects/ai/silkweave/packages/silkweave
+> silkweave@1.3.2 build /Users/atomic/projects/ai/silkweave/packages/silkweave
 > tsup
 
 CLI Building entry: src/auth.ts, src/cli.ts, src/core.ts, src/fastify.ts, src/logger.ts, src/mcp.ts, src/vercel.ts
@@ -11,22 +11,22 @@
 CLI Cleaning output folder
 ESM Build start
 ESM build/cli.js         77.00 B
+ESM build/fastify.js     89.00 B
 ESM build/core.js        80.00 B
-ESM build/vercel.js      86.00 B
+ESM build/logger.js      86.00 B
 ESM build/mcp.js         77.00 B
 ESM build/auth.js        80.00 B
-ESM build/fastify.js     89.00 B
-ESM build/logger.js      86.00 B
+ESM build/vercel.js      86.00 B
 ESM build/cli.js.map     131.00 B
-ESM build/core.js.map    133.00 B
-ESM build/mcp.js.map     131.00 B
-ESM build/vercel.js.map  137.00 B
 ESM build/fastify.js.map 139.00 B
-ESM build/auth.js.map    133.00 B
 ESM build/logger.js.map  137.00 B
+ESM build/core.js.map    133.00 B
+ESM build/auth.js.map    133.00 B
+ESM build/vercel.js.map  137.00 B
+ESM build/mcp.js.map     131.00 B
 ESM ⚡️ Build success in 6ms
 DTS Build start
-DTS ⚡️ Build success in 592ms
+DTS ⚡️ Build success in 643ms
 DTS build/auth.d.ts    194.00 B
 DTS build/cli.d.ts     32.00 B
 DTS build/core.d.ts    33.00 B

package/.turbo/turbo-check.log

@@ -0,0 +1,12 @@
+
+> silkweave@1.3.2 check /Users/atomic/projects/ai/silkweave/packages/silkweave
+> pnpm lint && pnpm typecheck
+
+
+> silkweave@1.3.2 lint /Users/atomic/projects/ai/silkweave/packages/silkweave
+> eslint
+
+
+> silkweave@1.3.2 typecheck /Users/atomic/projects/ai/silkweave/packages/silkweave
+> tsc --noEmit
+

package/.turbo/turbo-lint.log

@@ -0,0 +1,5 @@
+
+
+> silkweave@1.3.2 lint /Users/atomic/projects/ai/silkweave/packages/silkweave
+> eslint
+

package/.turbo/turbo-prepack.log

@@ -1,14 +1,14 @@
 
 
-> silkweave@1.3.0 prepack /Users/atomic/projects/ai/silkweave/packages/silkweave
+> silkweave@1.4.0 prepack /Users/atomic/projects/ai/silkweave/packages/silkweave
 > pnpm clean && pnpm build
 
 
-> silkweave@1.3.0 clean /Users/atomic/projects/ai/silkweave/packages/silkweave
+> silkweave@1.4.0 clean /Users/atomic/projects/ai/silkweave/packages/silkweave
 > rimraf build
 
 
-> silkweave@1.3.0 build /Users/atomic/projects/ai/silkweave/packages/silkweave
+> silkweave@1.4.0 build /Users/atomic/projects/ai/silkweave/packages/silkweave
 > tsup
 
 CLI Building entry: src/auth.ts, src/cli.ts, src/core.ts, src/fastify.ts, src/logger.ts, src/mcp.ts, src/vercel.ts
@@ -19,22 +19,22 @@
 CLI Cleaning output folder
 ESM Build start
 ESM build/core.js        80.00 B
-ESM build/fastify.js     89.00 B
-ESM build/logger.js      86.00 B
 ESM build/auth.js        80.00 B
-ESM build/vercel.js      86.00 B
-ESM build/cli.js         77.00 B
 ESM build/mcp.js         77.00 B
-ESM build/fastify.js.map 139.00 B
-ESM build/logger.js.map  137.00 B
+ESM build/cli.js         77.00 B
+ESM build/vercel.js      86.00 B
+ESM build/fastify.js     89.00 B
+ESM build/logger.js      86.00 B
 ESM build/core.js.map    133.00 B
-ESM build/cli.js.map     131.00 B
 ESM build/auth.js.map    133.00 B
 ESM build/mcp.js.map     131.00 B
+ESM build/fastify.js.map 139.00 B
+ESM build/cli.js.map     131.00 B
 ESM build/vercel.js.map  137.00 B
-ESM ⚡️ Build success in 7ms
+ESM build/logger.js.map  137.00 B
+ESM ⚡️ Build success in 6ms
 DTS Build start
-DTS ⚡️ Build success in 598ms
+DTS ⚡️ Build success in 676ms
 DTS build/auth.d.ts    194.00 B
 DTS build/cli.d.ts     32.00 B
 DTS build/core.d.ts    33.00 B

package/README.md

@@ -2,7 +2,7 @@
 
 **Write your logic once. Run it everywhere.**
 
-Silkweave is a TypeScript toolkit that lets you define application logic as portable **Actions** and instantly expose them through any combination of transports — MCP servers (stdio and HTTP), REST APIs with auto-generated OpenAPI docs, and fully-featured CLIs. No glue code required.
+Silkweave is a TypeScript toolkit that lets you define application logic as portable **Actions** and instantly expose them through any combination of transports - MCP servers (stdio and HTTP), REST APIs with auto-generated OpenAPI docs, and fully-featured CLIs. No glue code required.
 
 ```
                      ┌─────────────────────┐
@@ -39,6 +39,7 @@ Silkweave is a TypeScript toolkit that lets you define application logic as port
   - [CLI](#cli)
   - [Vercel Serverless](#vercel-serverless)
 - [Logging and Progress](#logging-and-progress)
+- [Smart Tool Results](#smart-tool-results)
 - [Advanced Patterns](#advanced-patterns)
   - [Multiple Adapters Simultaneously](#multiple-adapters-simultaneously)
   - [CLI Arguments vs Options](#cli-arguments-vs-options)
@@ -51,9 +52,9 @@ Silkweave is a TypeScript toolkit that lets you define application logic as port
 
 ## Why Silkweave
 
-Building an MCP server usually means wiring up transports, registering tools, serializing responses, and handling errors — for every single tool. If you also want a CLI or REST API for the same logic, you're writing it all again.
+Building an MCP server usually means wiring up transports, registering tools, serializing responses, and handling errors - for every single tool. If you also want a CLI or REST API for the same logic, you're writing it all again.
 
-Silkweave eliminates this duplication. You define an **Action** — a name, a Zod schema, and an async function — and Silkweave handles the rest:
+Silkweave eliminates this duplication. You define an **Action** - a name, a Zod schema, and an async function - and Silkweave handles the rest:
 
 - **MCP adapters** register your actions as MCP tools with proper notifications, progress reporting, and error handling
 - **Fastify adapter** generates a REST API with full OpenAPI/Swagger documentation derived from your Zod schemas
@@ -69,12 +70,12 @@ Silkweave is organized as a monorepo with modular packages. Install only what yo
 
 | Package | npm | Description |
 |---------|-----|-------------|
-| `@silkweave/core` | [![npm](https://img.shields.io/npm/v/@silkweave/core)](https://www.npmjs.com/package/@silkweave/core) | Core library — actions, adapters, builder, context, logger, utilities |
-| `@silkweave/mcp` | [![npm](https://img.shields.io/npm/v/@silkweave/mcp)](https://www.npmjs.com/package/@silkweave/mcp) | MCP adapters — stdio, streamable HTTP, CLI proxy |
-| `@silkweave/cli` | [![npm](https://img.shields.io/npm/v/@silkweave/cli)](https://www.npmjs.com/package/@silkweave/cli) | CLI adapter — commander + clack terminal UI |
-| `@silkweave/fastify` | [![npm](https://img.shields.io/npm/v/@silkweave/fastify)](https://www.npmjs.com/package/@silkweave/fastify) | Fastify REST adapter — auto-generated OpenAPI/Swagger docs |
-| `@silkweave/vercel` | [![npm](https://img.shields.io/npm/v/@silkweave/vercel)](https://www.npmjs.com/package/@silkweave/vercel) | Vercel serverless adapter — stateless MCP over Streamable HTTP |
-| `@silkweave/logger` | [![npm](https://img.shields.io/npm/v/@silkweave/logger)](https://www.npmjs.com/package/@silkweave/logger) | Logging utilities — pino, clack, and MCP notification support |
+| `@silkweave/core` | [![npm](https://img.shields.io/npm/v/@silkweave/core)](https://www.npmjs.com/package/@silkweave/core) | Core library - actions, adapters, builder, context, logger, utilities |
+| `@silkweave/mcp` | [![npm](https://img.shields.io/npm/v/@silkweave/mcp)](https://www.npmjs.com/package/@silkweave/mcp) | MCP adapters - stdio, streamable HTTP, CLI proxy |
+| `@silkweave/cli` | [![npm](https://img.shields.io/npm/v/@silkweave/cli)](https://www.npmjs.com/package/@silkweave/cli) | CLI adapter - commander + clack terminal UI |
+| `@silkweave/fastify` | [![npm](https://img.shields.io/npm/v/@silkweave/fastify)](https://www.npmjs.com/package/@silkweave/fastify) | Fastify REST adapter - auto-generated OpenAPI/Swagger docs |
+| `@silkweave/vercel` | [![npm](https://img.shields.io/npm/v/@silkweave/vercel)](https://www.npmjs.com/package/@silkweave/vercel) | Vercel serverless adapter - stateless MCP over Streamable HTTP |
+| `@silkweave/logger` | [![npm](https://img.shields.io/npm/v/@silkweave/logger)](https://www.npmjs.com/package/@silkweave/logger) | Logging utilities - pino, clack, and MCP notification support |
 
 **`@silkweave/core`** is always required. Then add the adapter packages for the transports you need:
 
@@ -178,7 +179,8 @@ export const SearchAction = createAction({
 | `description` | `string` | Human-readable description. Shown in MCP tool listings, CLI help, and Swagger docs. |
 | `input` | `z.ZodObject` | A Zod object schema defining the input. `.describe()` on each field provides per-field documentation across all adapters. |
 | `args` | `(keyof I)[]` | *(Optional)* Fields to expose as positional CLI arguments instead of `--options`. Only relevant for the CLI adapter. |
-| `run` | `(input, context) => Promise<O>` | The implementation. Receives validated input and an `SilkweaveContext` with a `logger`. Returns any object — adapters handle serialization. |
+| `run` | `(input, context) => Promise<O>` | The implementation. Receives validated input and an `SilkweaveContext` with a `logger`. Returns any object - adapters handle serialization. |
+| `toolResult` | `(response, context) => CallToolResult \| undefined` | *(Optional)* Custom MCP result formatting. Return `undefined` to fall through to the default `smartToolResult` behavior. See [Smart Tool Results](#smart-tool-results). |
 
 ### Adapters
 
@@ -204,10 +206,10 @@ cli()
 
 The adapter lifecycle:
 
-1. **Factory** — `stdio()` / `http({ ... })` / etc. captures configuration
-2. **Generator** — Silkweave calls the factory result with `{ name, description, version }` to produce an `Adapter`
-3. **Start** — `adapter.start(actions)` registers all actions and begins listening
-4. **Stop** — `adapter.stop()` tears down gracefully
+1. **Factory** - `stdio()` / `http({ ... })` / etc. captures configuration
+2. **Generator** - Silkweave calls the factory result with `{ name, description, version }` to produce an `Adapter`
+3. **Start** - `adapter.start(actions)` registers all actions and begins listening
+4. **Stop** - `adapter.stop()` tears down gracefully
 
 ### The Silkweave Builder
 
@@ -225,7 +227,7 @@ const app = silkweave({
 
 app
   .adapter(stdio())              // Add an adapter
-  .adapter(http({ ... }))        // Add another — they run in parallel
+  .adapter(http({ ... }))        // Add another - they run in parallel
   .action(SearchAction)          // Mount an action
   .action(GreetAction)           // Mount another
 
@@ -259,10 +261,12 @@ await silkweave({ name: 'my-tools', description: 'My Tools', version: '1.0.0' })
 | `name: 'searchDocs'` | Tool name: `SearchDocs` (PascalCase) |
 | `description` | Tool description |
 | `input` (Zod schema) | `inputSchema` (JSON Schema via Zod) |
-| Return value | `TextContent` JSON response |
-| Thrown errors | Structured error response with name, message, and stack |
+| Return value | `CallToolResult` via `smartToolResult` or custom `toolResult` hook |
+| Thrown errors | Structured error response via `handleToolError` |
 
-MCP logging notifications are wired automatically — `logger.info("message")` in your action sends a `notifications/message` to the MCP client. Progress reporting works via `logger.progress()` when the client provides a progress token.
+By default, MCP adapters use `smartToolResult()` to format return values — responses ≤ 4096 chars are returned as inline JSON, while larger payloads are automatically split into a text summary + base64 embedded resource to reduce LLM context bloat. Actions can override this with a custom [`toolResult` hook](#smart-tool-results).
+
+MCP logging notifications are wired automatically - `logger.info("message")` in your action sends a `notifications/message` to the MCP client. Progress reporting works via `logger.progress()` when the client provides a progress token.
 
 **Claude Desktop / Claude Code configuration:**
 
@@ -303,7 +307,7 @@ await silkweave({ name: 'my-tools', description: 'My Tools', version: '1.0.0' })
 | `GET` | `/mcp` | Establish SSE stream for a session |
 | `DELETE` | `/mcp` | Terminate a session |
 
-The adapter manages session lifecycle automatically — each new `initialize` request creates a new `StreamableHTTPServerTransport` with a UUID session ID. Sessions are cleaned up when the transport closes.
+The adapter manages session lifecycle automatically - each new `initialize` request creates a new `StreamableHTTPServerTransport` with a UUID session ID. Sessions are cleaned up when the transport closes.
 
 CORS is configured out of the box, exposing MCP-specific headers (`Mcp-Session-Id`, `Mcp-Protocol-Version`, `Last-Event-Id`).
 
@@ -399,7 +403,7 @@ $ mytool greet --name "World" --enthusiastic
 
 ### Vercel Serverless
 
-Deploy your actions as a stateless MCP server on Vercel. Each request creates a fresh server instance — no sessions, no persistent connections, fully compatible with serverless constraints.
+Deploy your actions as a stateless MCP server on Vercel. Each request creates a fresh server instance - no sessions, no persistent connections, fully compatible with serverless constraints.
 
 ```typescript
 // api/mcp.ts (Vercel function)
@@ -417,7 +421,7 @@ await silkweave({ name: 'my-tools', description: 'My Tools', version: '1.0.0' })
 export default { fetch: handler }
 ```
 
-The `vercel()` function returns a compound object — `adapter` wires into the Silkweave builder, while `handler`/`GET`/`POST`/`DELETE` are the request handler for your Vercel route.
+The `vercel()` function returns a compound object - `adapter` wires into the Silkweave builder, while `handler`/`GET`/`POST`/`DELETE` are the request handler for your Vercel route.
 
 **For Next.js App Router** (`app/api/mcp/route.ts`):
 
@@ -437,7 +441,7 @@ export { GET, POST, DELETE }
 - Uses `WebStandardStreamableHTTPServerTransport` from the MCP SDK in stateless mode (`sessionIdGenerator: undefined`)
 - Each request creates a fresh `McpServer` + transport, registers tools, handles the request, and returns a Web Standard `Response`
 - Logging goes to `process.stderr` (Vercel log drain) and MCP client notifications
-- No CORS handling — use Next.js middleware or `vercel.json` headers
+- No CORS handling - use Next.js middleware or `vercel.json` headers
 
 **`VercelAdapterOptions`:**
 
@@ -486,6 +490,69 @@ run: async (input, { logger }) => {
 
 ---
 
+## Smart Tool Results
+
+MCP adapters (stdio, HTTP, and Vercel) use `smartToolResult()` by default to format action return values. This is a server-side best practice for managing LLM context bloat:
+
+- **Small responses** (≤ 4096 chars): returned as inline `TextContent` JSON
+- **Large responses** (> 4096 chars): split into a short text summary + a base64 **embedded resource**, keeping the LLM's context window lean while preserving full data access
+
+Some MCP clients (e.g. VS Code since December 2025) handle this client-side for all tool calls, but most clients don't — `smartToolResult` ensures good behavior regardless of client capabilities.
+
+### Custom `toolResult` Hook
+
+Actions can override the default formatting by defining a `toolResult` hook:
+
+```typescript
+import { createAction } from '@silkweave/core'
+import { smartToolResult } from '@silkweave/mcp'
+import z from 'zod'
+
+export const UserListAction = createAction({
+  name: 'user-list',
+  description: 'Return a list of users',
+  input: z.object({
+    format: z.enum(['full', 'summary']).default('summary')
+  }),
+  run: async ({ format }, context) => {
+    context.set('format', format)
+    return await fetchUsers()
+  },
+  toolResult: (users, context) => {
+    if (context.get('format') === 'full') {
+      return smartToolResult(users)  // Use default smart splitting
+    }
+    // Return a lean summary as text + full data as embedded resource
+    const summary = users.map(({ id, name }) => ({ id, name }))
+    return {
+      content: [
+        { type: 'text', text: JSON.stringify(summary) },
+        { type: 'resource', resource: {
+          uri: 'mcp://my-app/users.json',
+          mimeType: 'application/json',
+          blob: Buffer.from(JSON.stringify(users)).toString('base64')
+        }}
+      ]
+    }
+  }
+})
+```
+
+Return `undefined` from `toolResult` to fall through to the default `smartToolResult` behavior. The hook only affects MCP adapters — CLI and Fastify adapters handle serialization independently.
+
+### MCP Result Utilities
+
+All result utilities are exported from `@silkweave/mcp`:
+
+| Function | Description |
+|----------|-------------|
+| `smartToolResult(data)` | Default formatter — automatic embedded resource splitting at 4096 chars |
+| `jsonToolResult(data, isError?)` | Simple inline `TextContent` JSON (no splitting) |
+| `errorToolResult(error)` | Format a `SilkweaveError` as an error result |
+| `handleToolError(error)` | Catch-all error handler used by all MCP adapters |
+
+---
+
 ## Advanced Patterns
 
 ### Multiple Adapters Simultaneously
@@ -506,7 +573,7 @@ await silkweave({ name: 'my-platform', description: 'Multi-transport', version:
   .start()
 ```
 
-All adapters start concurrently. The MCP stdio server communicates over stdin/stdout while Fastify listens on port 8080 — each serving the exact same actions.
+All adapters start concurrently. The MCP stdio server communicates over stdin/stdout while Fastify listens on port 8080 - each serving the exact same actions.
 
 ### CLI Arguments vs Options
 
@@ -536,7 +603,7 @@ $ mytool deploy production v2.1.0 --dry-run
 ℹ Deploying v2.1.0 to production (dry run)
 ```
 
-Fields listed in `args` become positional arguments in the CLI. All other fields remain as `--options`. The `args` property has no effect on MCP or REST adapters — they always receive all fields as a single input object.
+Fields listed in `args` become positional arguments in the CLI. All other fields remain as `--options`. The `args` property has no effect on MCP or REST adapters - they always receive all fields as a single input object.
 
 ### Complex Input Types
 
@@ -673,6 +740,7 @@ interface Action<I, O> {
   args?: (keyof I)[]
   isEnabled?: (context: SilkweaveContext) => boolean
   run: (input: I, context: SilkweaveContext) => Promise<O>
+  toolResult?: (response: O, context: SilkweaveContext) => CallToolResult | undefined
 }
 ```
 
@@ -701,11 +769,11 @@ interface ProgressOptions {
 ### Adapter Factories
 
 ```typescript
-// MCP over stdin/stdout — from @silkweave/mcp
+// MCP over stdin/stdout - from @silkweave/mcp
 import { stdio } from '@silkweave/mcp'
 function stdio(): AdapterFactory
 
-// MCP Streamable HTTP — from @silkweave/mcp
+// MCP Streamable HTTP - from @silkweave/mcp
 import { http } from '@silkweave/mcp'
 function http(options: HttpAdapterOptions): AdapterFactory
 interface HttpAdapterOptions {
@@ -714,7 +782,7 @@ interface HttpAdapterOptions {
   // ...plus CreateMcpExpressAppOptions (e.g., allowedHosts)
 }
 
-// Fastify REST API with Swagger — from @silkweave/fastify
+// Fastify REST API with Swagger - from @silkweave/fastify
 import { fastify } from '@silkweave/fastify'
 function fastify(options: FastifyAdapterOptions): AdapterFactory
 interface FastifyAdapterOptions {
@@ -723,11 +791,11 @@ interface FastifyAdapterOptions {
   // ...plus all FastifyHttpOptions (logger, connectionTimeout, etc.)
 }
 
-// CLI via commander + clack — from @silkweave/cli
+// CLI via commander + clack - from @silkweave/cli
 import { cli } from '@silkweave/cli'
 function cli(): AdapterFactory
 
-// Vercel serverless — from @silkweave/vercel
+// Vercel serverless - from @silkweave/vercel
 import { vercel } from '@silkweave/vercel'
 function vercel(options?: VercelAdapterOptions): VercelAdapter
 interface VercelAdapterOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "silkweave",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Silkweave Umbrella Package",
   "repository": {
     "type": "git",
@@ -39,13 +39,13 @@
     }
   },
   "dependencies": {
-    "@silkweave/auth": "1.3.1",
-    "@silkweave/cli": "1.3.1",
-    "@silkweave/core": "1.3.1",
-    "@silkweave/fastify": "1.3.1",
-    "@silkweave/logger": "1.3.1",
-    "@silkweave/vercel": "1.3.1",
-    "@silkweave/mcp": "1.3.1"
+    "@silkweave/cli": "1.4.0",
+    "@silkweave/core": "1.4.0",
+    "@silkweave/logger": "1.4.0",
+    "@silkweave/auth": "1.4.0",
+    "@silkweave/mcp": "1.4.0",
+    "@silkweave/fastify": "1.4.0",
+    "@silkweave/vercel": "1.4.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",