typed-bridge 3.0.0 → 4.0.0

package/dist/bridge/index.d.ts

@@ -1,10 +1,10 @@
 import { Application, Request, Response } from 'express';
 import { Server } from 'http';
 import { MCPGetContext } from '../mcp';
-import { Bridge, BridgeEntries, LLMToolFormat } from '../tools';
+import { Bridge, BridgeEntries, ToolMode } from '../tools';
 interface CreateBridgeOptions {
     entries?: BridgeEntries;
-    toolsFormat?: LLMToolFormat;
+    toolMode?: ToolMode;
     mcp?: boolean | string;
     mcpGetContext?: MCPGetContext;
 }

package/dist/bridge/index.js

@@ -12,7 +12,6 @@ const path_1 = __importDefault(require("path"));
 const __1 = require("..");
 const helpers_1 = require("../helpers");
 const mcp_1 = require("../mcp");
-const tools_1 = require("../tools");
 const middlewares = [];
 const createMiddleware = (pattern, handler) => middlewares.push({ pattern, handler });
 exports.createMiddleware = createMiddleware;
@@ -86,31 +85,10 @@ const createBridge = (bridge, port, path = '/bridge', options) => {
             timestamp: new Date().toISOString()
         });
     });
-    // LLM tools endpoint
-    if (options?.entries) {
-        const entries = options.entries;
-        const defaultFormat = options.toolsFormat || 'openai';
-        app.get(path_1.default.join(path, 'tools'), (req, res) => {
-            const requestedFormat = req.query.format;
-            // No format provided → use the configured default
-            if (requestedFormat === undefined) {
-                res.json((0, tools_1.toLLMTools)(entries, { format: defaultFormat }));
-                return;
-            }
-            // Reject unknown formats instead of silently returning an empty tool list
-            if (typeof requestedFormat !== 'string' || !(0, tools_1.isLLMToolFormat)(requestedFormat)) {
-                res.status(400).json({
-                    error: `Invalid format: ${String(requestedFormat)}. Expected one of ${tools_1.LLM_TOOL_FORMATS.join(', ')}`
-                });
-                return;
-            }
-            res.json((0, tools_1.toLLMTools)(entries, { format: requestedFormat }));
-        });
-    }
     // MCP endpoint
     if (options?.mcp && options?.entries) {
         const mcpPath = typeof options.mcp === 'string' ? options.mcp : path_1.default.join(path, 'mcp');
-        (0, mcp_1.mountMCP)(app, bridge, options.entries, mcpPath, options.mcpGetContext);
+        (0, mcp_1.mountMCP)(app, bridge, options.entries, mcpPath, options.mcpGetContext, options.toolMode || 'on_demand');
     }
     app.use(path, bridgeHandler(bridge));
     const server = app.listen(port, () => (0, helpers_1.printStartLogs)(port));

package/dist/config/index.js

@@ -10,5 +10,5 @@ exports.config = {
         contextOnError: true
     },
     responseDelay: 0,
-    maxToolOutputChars: 0
+    maxToolOutputChars: 100_000
 };

package/dist/index.d.ts

@@ -3,6 +3,6 @@ export { createBridge, createMiddleware, onShutdown } from './bridge';
 export { config as tbConfig } from './config';
 export { mountMCP } from './mcp';
 export type { MCPGetContext } from './mcp';
-export { defineBridge, getMetaTools, handleMetaToolCall, toLLMTools, toolDescribe, toolSearch, toolUse } from './tools';
-export type { Bridge, BridgeEntries, BridgeEntry, LLMToolFormat, ToLLMToolsOptions, ToolCall } from './tools';
+export { defineBridge, defineEntry, getTools, handleToolCall, isToolMode, TOOL_MODES } from './tools';
+export type { Bridge, BridgeEntries, BridgeEntry, GetToolsOptions, HandleToolCallOptions, LLMToolFormat, ToolCall, ToolMode, ToolSurface } from './tools';
 export { z } from 'zod';

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.z = exports.toolUse = exports.toolSearch = exports.toolDescribe = exports.toLLMTools = exports.handleMetaToolCall = exports.getMetaTools = exports.defineBridge = exports.mountMCP = exports.tbConfig = exports.onShutdown = exports.createMiddleware = exports.createBridge = exports.Router = exports.express = void 0;
+exports.z = exports.TOOL_MODES = exports.isToolMode = exports.handleToolCall = exports.getTools = exports.defineEntry = exports.defineBridge = exports.mountMCP = exports.tbConfig = exports.onShutdown = exports.createMiddleware = exports.createBridge = exports.Router = exports.express = void 0;
 var express_1 = require("express");
 Object.defineProperty(exports, "express", { enumerable: true, get: function () { return __importDefault(express_1).default; } });
 Object.defineProperty(exports, "Router", { enumerable: true, get: function () { return express_1.Router; } });
@@ -17,11 +17,10 @@ var mcp_1 = require("./mcp");
 Object.defineProperty(exports, "mountMCP", { enumerable: true, get: function () { return mcp_1.mountMCP; } });
 var tools_1 = require("./tools");
 Object.defineProperty(exports, "defineBridge", { enumerable: true, get: function () { return tools_1.defineBridge; } });
-Object.defineProperty(exports, "getMetaTools", { enumerable: true, get: function () { return tools_1.getMetaTools; } });
-Object.defineProperty(exports, "handleMetaToolCall", { enumerable: true, get: function () { return tools_1.handleMetaToolCall; } });
-Object.defineProperty(exports, "toLLMTools", { enumerable: true, get: function () { return tools_1.toLLMTools; } });
-Object.defineProperty(exports, "toolDescribe", { enumerable: true, get: function () { return tools_1.toolDescribe; } });
-Object.defineProperty(exports, "toolSearch", { enumerable: true, get: function () { return tools_1.toolSearch; } });
-Object.defineProperty(exports, "toolUse", { enumerable: true, get: function () { return tools_1.toolUse; } });
+Object.defineProperty(exports, "defineEntry", { enumerable: true, get: function () { return tools_1.defineEntry; } });
+Object.defineProperty(exports, "getTools", { enumerable: true, get: function () { return tools_1.getTools; } });
+Object.defineProperty(exports, "handleToolCall", { enumerable: true, get: function () { return tools_1.handleToolCall; } });
+Object.defineProperty(exports, "isToolMode", { enumerable: true, get: function () { return tools_1.isToolMode; } });
+Object.defineProperty(exports, "TOOL_MODES", { enumerable: true, get: function () { return tools_1.TOOL_MODES; } });
 var zod_1 = require("zod");
 Object.defineProperty(exports, "z", { enumerable: true, get: function () { return zod_1.z; } });

package/dist/mcp/index.d.ts

@@ -1,5 +1,5 @@
 import { IncomingHttpHeaders } from 'node:http';
 import { Application } from 'express';
-import { Bridge, BridgeEntries } from '../tools';
+import { Bridge, BridgeEntries, ToolMode } from '../tools';
 export type MCPGetContext = (headers: IncomingHttpHeaders) => Record<string, unknown> | Promise<Record<string, unknown>>;
-export declare function mountMCP(app: Application, bridge: Bridge, entries: BridgeEntries, path?: string, getContext?: MCPGetContext): void;
+export declare function mountMCP(app: Application, bridge: Bridge, entries: BridgeEntries, path?: string, getContext?: MCPGetContext, toolMode?: ToolMode): void;

package/dist/mcp/index.js

@@ -9,13 +9,17 @@ const tools_1 = require("../tools");
 const SESSION_TTL_MS = 30 * 60 * 1000;
 const SWEEP_INTERVAL_MS = 5 * 60 * 1000;
 const MAX_SESSIONS = 1000;
-function createMCPServer(bridge, entries, headersRef, getContext) {
+// The 3 meta-tools, shaped for MCP's { name, description, inputSchema } listing.
+const metaToolsForMCP = () => (0, tools_1.getMetaTools)({ format: 'json-schema' }).map(tool => ({ name: tool.name, description: tool.description, inputSchema: tool.parameters }));
+function createMCPServer(bridge, entries, headersRef, getContext, toolMode = 'on_demand') {
     const server = new index_js_1.Server({ name: 'typed-bridge', version: '1.0.0' }, { capabilities: { tools: {} } });
-    // An entry is exposed to MCP unless it explicitly opts out with `mcp: false`
-    const isExposed = (entry) => !!entry && entry.mcp !== false;
     server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+        // on_demand: hand the model the 3 meta-tools and let it discover the rest
+        if (toolMode === 'on_demand')
+            return { tools: metaToolsForMCP() };
+        // attach_all: one tool per entry visible to MCP (respects `mcp: false`)
         const tools = Object.entries(entries)
-            .filter(([, entry]) => isExposed(entry))
+            .filter(([, entry]) => (0, tools_1.isEntryVisible)(entry, 'mcp'))
             .map(([name, entry]) => ({
             name,
             description: entry.description,
@@ -26,18 +30,12 @@ function createMCPServer(bridge, entries, headersRef, getContext) {
     server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
         try {
-            // Block execution of hidden tools, not just their listing
-            if (!isExposed(entries[name]))
-                throw new Error(`Tool not found: ${name}`);
-            const handler = bridge[name];
-            if (!handler)
-                throw new Error(`Tool not found: ${name}`);
             // Derive per-request context from forwarded headers
             const context = getContext ? await getContext(headersRef.current) : undefined;
-            const result = await handler(args || {}, context);
-            // Throws if the result exceeds tbConfig.maxToolOutputChars — handled below as isError
-            const text = (0, tools_1.enforceToolOutputLimit)(result);
-            return { content: [{ type: 'text', text }] };
+            // Mode-agnostic dispatch: meta-tool names run discovery, anything else runs the
+            // entry directly. Visibility (`mcp: false`) and the output limit are enforced inside.
+            const result = await (0, tools_1.handleToolCall)(bridge, entries, { name, arguments: args || {} }, { context, surface: 'mcp' });
+            return { content: [{ type: 'text', text: JSON.stringify(result) ?? '' }] };
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -46,7 +44,7 @@ function createMCPServer(bridge, entries, headersRef, getContext) {
     });
     return server;
 }
-function mountMCP(app, bridge, entries, path = '/mcp', getContext) {
+function mountMCP(app, bridge, entries, path = '/mcp', getContext, toolMode = 'on_demand') {
     const sessions = new Map();
     // Evict sessions idle for longer than SESSION_TTL_MS
     const sweepInterval = setInterval(() => {
@@ -70,7 +68,7 @@ function mountMCP(app, bridge, entries, path = '/mcp', getContext) {
         }
         else if (!sessionId && req.method === 'POST') {
             const headersRef = { current: req.headers };
-            const server = createMCPServer(bridge, entries, headersRef, getContext);
+            const server = createMCPServer(bridge, entries, headersRef, getContext, toolMode);
             transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
                 sessionIdGenerator: () => (0, node_crypto_1.randomUUID)(),
                 onsessioninitialized: (id) => {

package/dist/scripts/typedBridgeCleaner.js

@@ -223,6 +223,31 @@ const removeSecondParamTransformer = context => {
 };
 /**
  * Transformer #3:
+ * Make any parameter typed as `undefined` optional so callers can omit it.
+ * e.g. `(_args: undefined) => Promise<...>` → `(_args?: undefined) => Promise<...>`
+ */
+const optionalUndefinedParamTransformer = context => {
+    return sourceFile => {
+        function visitor(node) {
+            if (typescript_1.default.isFunctionTypeNode(node)) {
+                const params = node.parameters.map(param => {
+                    if (param.type &&
+                        typescript_1.default.isToken(param.type) &&
+                        param.type.kind === typescript_1.default.SyntaxKind.UndefinedKeyword &&
+                        !param.questionToken) {
+                        return typescript_1.default.factory.updateParameterDeclaration(param, param.modifiers, param.dotDotDotToken, param.name, typescript_1.default.factory.createToken(typescript_1.default.SyntaxKind.QuestionToken), param.type, param.initializer);
+                    }
+                    return param;
+                });
+                return typescript_1.default.factory.updateFunctionTypeNode(node, node.typeParameters, typescript_1.default.factory.createNodeArray(params), node.type);
+            }
+            return typescript_1.default.visitEachChild(node, visitor, context);
+        }
+        return typescript_1.default.visitEachChild(sourceFile, visitor, context);
+    };
+};
+/**
+ * Transformer #4:
  * Resolve ExtractHandlers<T> in the _default declaration by unwrapping
  * { handler: fn, ... } entries to just the function type.
  * Also removes helper type definitions and the entries declaration that
@@ -316,7 +341,7 @@ const unwrapBridgeEntryTransformer = _context => {
     };
 };
 /**
- * Transformer #4:
+ * Transformer #5:
  * Remove the rollup default export (`export { X as default }` for any X, or
  * `export default X`). The proxy snippet provides its own default export.
  */
@@ -343,7 +368,7 @@ const removeDefaultExportTransformer = _context => {
     };
 };
 /**
- * Transformer #5:
+ * Transformer #6:
  * Drop every top-level statement that is not reachable from the `TypedBridge`
  * alias. When typed-bridge is an external dependency, rollup leaves behind stray
  * imports (e.g. `import * as ... from 'typed-bridge/dist/tools'`) and inlined
@@ -437,6 +462,7 @@ function cleanTsFile(src) {
         unwrapBridgeEntryTransformer,
         resolveZodTypesTransformer,
         removeSecondParamTransformer,
+        optionalUndefinedParamTransformer,
         removeDefaultExportTransformer,
         pruneUnreachableTransformer
     ]);

package/dist/tools/index.d.ts

@@ -17,15 +17,66 @@ export type Bridge = Record<string, (...args: any[]) => Promise<any>>;
 export declare const LLM_TOOL_FORMATS: readonly ["openai", "anthropic", "json-schema"];
 export type LLMToolFormat = (typeof LLM_TOOL_FORMATS)[number];
 export declare function isLLMToolFormat(value: string): value is LLMToolFormat;
+export declare const TOOL_MODES: readonly ["attach_all", "on_demand"];
+export type ToolMode = (typeof TOOL_MODES)[number];
+export declare function isToolMode(value: string): value is ToolMode;
+export type ToolSurface = 'llm' | 'mcp';
+export declare function isEntryVisible(entry: BridgeEntry | undefined, surface: ToolSurface): boolean;
 export interface ToLLMToolsOptions {
     format?: LLMToolFormat;
     includeResponse?: boolean;
+    surface?: ToolSurface;
+}
+export interface GetToolsOptions {
+    toolMode?: ToolMode;
+    format?: LLMToolFormat;
+    surface?: ToolSurface;
+    includeResponse?: boolean;
+}
+export interface HandleToolCallOptions {
+    context?: unknown;
+    surface?: ToolSurface;
 }
 export interface ToolCall {
     name: string;
     arguments: Record<string, unknown>;
 }
 export declare function defineBridge<T extends BridgeEntries>(entries: T): ExtractHandlers<T>;
+/**
+ * Bundle an entry's schema and handler into a single, self-contained object.
+ * Purely a typing helper — it returns its input unchanged at runtime — but it
+ * infers the handler's argument type from `args` and checks the return against
+ * `res`, so you never write `z.infer<typeof ...>`. `context` stays `any` so you
+ * can annotate it with your own named context type inline.
+ */
+export declare function defineEntry<A extends z.ZodType, R extends z.ZodType>(entry: {
+    description?: string;
+    args: A;
+    res: R;
+    mcp?: boolean;
+    llm?: boolean;
+    handler: (args: z.infer<A>, context: any) => Promise<z.infer<R>>;
+}): {
+    description?: string;
+    args: A;
+    res: R;
+    mcp?: boolean;
+    llm?: boolean;
+    handler: (args: z.infer<A>, context: any) => Promise<z.infer<R>>;
+};
+export declare function defineEntry<R extends z.ZodType>(entry: {
+    description?: string;
+    res: R;
+    mcp?: boolean;
+    llm?: boolean;
+    handler: (args: undefined, context: any) => Promise<z.infer<R>>;
+}): {
+    description?: string;
+    res: R;
+    mcp?: boolean;
+    llm?: boolean;
+    handler: (args: undefined, context: any) => Promise<z.infer<R>>;
+};
 export declare function toToolInputSchema(args?: z.ZodType): any;
 export declare function schemaToJSONSchema(schema: z.ZodType): any;
 export declare function toLLMTools(entries: BridgeEntries, options?: ToLLMToolsOptions): unknown[];
@@ -106,11 +157,11 @@ export declare function getMetaTools(options?: {
         required: string[];
     };
 }[];
-export declare function toolSearch(entries: BridgeEntries, query?: string): {
+export declare function toolSearch(entries: BridgeEntries, query?: string, surface?: ToolSurface): {
     name: string;
     description?: string;
 }[];
-export declare function toolDescribe(entries: BridgeEntries, name: string): {
+export declare function toolDescribe(entries: BridgeEntries, name: string, surface?: ToolSurface): {
     name: string;
     description: string | undefined;
     args: any;
@@ -119,8 +170,22 @@ export declare function toolDescribe(entries: BridgeEntries, name: string): {
 /**
  * Serialize a tool result and enforce `tbConfig.maxToolOutputChars`. Oversized results
  * throw (instead of truncating to invalid JSON) so the model is prompted to narrow its
- * query. Returns the serialized JSON so callers can reuse it without re-stringifying.
+ * query. Returns the serialized JSON (callers may discard it; it's used only to measure).
  */
 export declare function enforceToolOutputLimit(result: unknown): string;
 export declare function toolUse(bridge: Bridge, name: string, args: unknown, context?: unknown): Promise<any>;
-export declare function handleMetaToolCall(bridge: Bridge, entries: BridgeEntries, toolCall: ToolCall, context?: unknown): Promise<unknown>;
+export declare function handleMetaToolCall(bridge: Bridge, entries: BridgeEntries, toolCall: ToolCall, context?: unknown, surface?: ToolSurface): Promise<unknown>;
+export declare const META_TOOL_NAMES: readonly ["tool_search", "tool_describe", "tool_use"];
+export declare function isMetaToolName(name: string): boolean;
+/**
+ * Build the tool list for a model, honoring the chosen mode:
+ *  - 'attach_all'  → one tool per visible entry (current `toLLMTools` behavior)
+ *  - 'on_demand'   → the 3 meta-tools (`tool_search`, `tool_describe`, `tool_use`)
+ */
+export declare function getTools(entries: BridgeEntries, options?: GetToolsOptions): unknown[];
+/**
+ * Execute whatever the model called, in either mode. Dispatches on the tool name:
+ * a meta-tool name runs the discovery flow, anything else runs that entry directly.
+ * Identical handler execution, validation, and output-limit enforcement either way.
+ */
+export declare function handleToolCall(bridge: Bridge, entries: BridgeEntries, toolCall: ToolCall, options?: HandleToolCallOptions): Promise<unknown>;

package/dist/tools/index.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LLM_TOOL_FORMATS = void 0;
+exports.META_TOOL_NAMES = exports.TOOL_MODES = exports.LLM_TOOL_FORMATS = void 0;
 exports.isLLMToolFormat = isLLMToolFormat;
+exports.isToolMode = isToolMode;
+exports.isEntryVisible = isEntryVisible;
 exports.defineBridge = defineBridge;
+exports.defineEntry = defineEntry;
 exports.toToolInputSchema = toToolInputSchema;
 exports.schemaToJSONSchema = schemaToJSONSchema;
 exports.toLLMTools = toLLMTools;
@@ -12,15 +15,35 @@ exports.toolDescribe = toolDescribe;
 exports.enforceToolOutputLimit = enforceToolOutputLimit;
 exports.toolUse = toolUse;
 exports.handleMetaToolCall = handleMetaToolCall;
+exports.isMetaToolName = isMetaToolName;
+exports.getTools = getTools;
+exports.handleToolCall = handleToolCall;
 const zod_1 = require("zod");
 const config_1 = require("../config");
 exports.LLM_TOOL_FORMATS = ['openai', 'anthropic', 'json-schema'];
 function isLLMToolFormat(value) {
     return exports.LLM_TOOL_FORMATS.includes(value);
 }
+// How tools are presented to an AI surface:
+//  - 'attach_all'  → every eligible entry is attached as its own tool
+//  - 'on_demand'   → the model gets the 3 meta-tools and discovers the rest
+exports.TOOL_MODES = ['attach_all', 'on_demand'];
+function isToolMode(value) {
+    return exports.TOOL_MODES.includes(value);
+}
+// An entry is exposed to a surface unless it explicitly opts out via its flag.
+function isEntryVisible(entry, surface) {
+    if (!entry)
+        return false;
+    return surface === 'mcp' ? entry.mcp !== false : entry.llm !== false;
+}
 function defineBridge(entries) {
     const bridge = {};
     for (const [key, entry] of Object.entries(entries)) {
+        // Reserved: these names drive the on_demand discovery flow. An entry using one
+        // would be shadowed by the meta-tool in handleToolCall and never reachable by name.
+        if (isMetaToolName(key))
+            throw new Error(`Entry name "${key}" is reserved for a meta-tool — rename the entry.`);
         bridge[key] = async (...handlerArgs) => {
             if (entry.args)
                 handlerArgs[0] = entry.args.parse(handlerArgs[0]);
@@ -29,6 +52,12 @@ function defineBridge(entries) {
     }
     return bridge;
 }
+// `any` is required here: an overload implementation signature must be `any`, and the
+// handler's `context: any` is what lets callers annotate it inline (e.g. `_ctx: context.user`) —
+// a narrower declared type like `unknown` would reject that annotation.
+function defineEntry(entry) {
+    return entry;
+}
 const NO_ARGS_SCHEMA = { type: 'object', properties: {}, additionalProperties: false };
 function toToolInputSchema(args) {
     if (!args)
@@ -56,12 +85,13 @@ function schemaToJSONSchema(schema) {
 function toLLMTools(entries, options) {
     const format = options?.format || 'openai';
     const includeResponse = options?.includeResponse || false;
+    const surface = options?.surface || 'llm';
     // Guard against invalid formats slipping in via casts (e.g. from query params)
     if (!isLLMToolFormat(format))
         throw new Error(`Invalid LLM tool format: ${format}. Expected one of ${exports.LLM_TOOL_FORMATS.join(', ')}`);
     const tools = [];
     for (const [name, entry] of Object.entries(entries)) {
-        if (entry.llm === false)
+        if (!isEntryVisible(entry, surface))
             continue;
         const description = entry.description;
         const parameters = toToolInputSchema(entry.args);
@@ -152,24 +182,49 @@ function getMetaTools(options) {
             return tools;
     }
 }
-function toolSearch(entries, query) {
-    const results = [];
-    const q = query?.toLowerCase();
+function toolSearch(entries, query, surface = 'llm') {
+    const visible = [];
     for (const [name, entry] of Object.entries(entries)) {
-        if (entry.llm === false)
+        if (!isEntryVisible(entry, surface))
             continue;
-        if (q) {
-            const haystack = `${name} ${entry.description || ''}`.toLowerCase();
-            if (!haystack.includes(q))
-                continue;
-        }
-        results.push({ name, description: entry.description });
+        visible.push({ name, description: entry.description });
     }
-    return results;
+    const q = query?.trim().toLowerCase();
+    if (!q)
+        return visible;
+    // Tokenize the query so natural, multi-word searches still match. A plain substring
+    // match fails on queries like "views analytics last 3 days" because the whole phrase is
+    // never a contiguous substring of any tool. Instead we score each tool by how many query
+    // tokens appear in its name/description, with a big boost for a full-phrase hit, and
+    // return only matching tools ranked best-first.
+    //
+    // Single-character tokens (stray punctuation splits, lone digits like "3") are dropped:
+    // they match almost everything and only add noise to results the model has to sift through.
+    const tokens = q.split(/[^a-z0-9]+/).filter(token => token.length > 1);
+    return visible
+        .map(tool => {
+        const name = tool.name.toLowerCase();
+        const description = (tool.description || '').toLowerCase();
+        const haystack = `${name} ${description}`;
+        // A full-phrase hit dominates; name hits outweigh description hits so the most
+        // on-point tools rank above ones that only mention a token in passing.
+        const phraseScore = haystack.includes(q) ? 1000 : 0;
+        const tokenScore = tokens.reduce((score, token) => {
+            if (name.includes(token))
+                return score + 3;
+            if (description.includes(token))
+                return score + 1;
+            return score;
+        }, 0);
+        return { tool, score: phraseScore + tokenScore };
+    })
+        .filter(scored => scored.score > 0)
+        .sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name))
+        .map(scored => scored.tool);
 }
-function toolDescribe(entries, name) {
+function toolDescribe(entries, name, surface = 'llm') {
     const entry = entries[name];
-    if (!entry || entry.llm === false)
+    if (!entry || !isEntryVisible(entry, surface))
         throw new Error(`Tool not found: ${name}`);
     return {
         name,
@@ -181,7 +236,7 @@ function toolDescribe(entries, name) {
 /**
  * Serialize a tool result and enforce `tbConfig.maxToolOutputChars`. Oversized results
  * throw (instead of truncating to invalid JSON) so the model is prompted to narrow its
- * query. Returns the serialized JSON so callers can reuse it without re-stringifying.
+ * query. Returns the serialized JSON (callers may discard it; it's used only to measure).
  */
 function enforceToolOutputLimit(result) {
     const serialized = JSON.stringify(result) ?? '';
@@ -191,6 +246,9 @@ function enforceToolOutputLimit(result) {
     }
     return serialized;
 }
+// The single execution boundary: runs the handler and enforces tbConfig.maxToolOutputChars
+// on its result. Every path that actually executes an entry (tool_use, direct call) goes
+// through here, so output is capped exactly once. Discovery (search/describe) never does.
 async function toolUse(bridge, name, args, context) {
     const handler = bridge[name];
     if (!handler)
@@ -199,16 +257,15 @@ async function toolUse(bridge, name, args, context) {
     enforceToolOutputLimit(result);
     return result;
 }
-async function handleMetaToolCall(bridge, entries, toolCall, context) {
+async function handleMetaToolCall(bridge, entries, toolCall, context, surface = 'llm') {
     switch (toolCall.name) {
         case 'tool_search':
-            return toolSearch(entries, toolCall.arguments?.query);
+            return toolSearch(entries, toolCall.arguments?.query, surface);
         case 'tool_describe':
-            return toolDescribe(entries, toolCall.arguments?.name);
+            return toolDescribe(entries, toolCall.arguments?.name, surface);
         case 'tool_use': {
             const args = toolCall.arguments;
-            const entry = entries[args.name];
-            if (!entry || entry.llm === false)
+            if (!isEntryVisible(entries[args.name], surface))
                 throw new Error(`Tool not found: ${args.name}`);
             return toolUse(bridge, args.name, args.arguments || {}, context);
         }
@@ -216,3 +273,45 @@ async function handleMetaToolCall(bridge, entries, toolCall, context) {
             throw new Error(`Unknown meta-tool: ${toolCall.name}. Expected "tool_search", "tool_describe", or "tool_use".`);
     }
 }
+// The three meta-tool names are reserved; a tool call by any of these runs the
+// discovery flow, anything else is treated as a direct entry call.
+exports.META_TOOL_NAMES = ['tool_search', 'tool_describe', 'tool_use'];
+function isMetaToolName(name) {
+    return exports.META_TOOL_NAMES.includes(name);
+}
+/**
+ * Build the tool list for a model, honoring the chosen mode:
+ *  - 'attach_all'  → one tool per visible entry (current `toLLMTools` behavior)
+ *  - 'on_demand'   → the 3 meta-tools (`tool_search`, `tool_describe`, `tool_use`)
+ */
+function getTools(entries, options) {
+    const toolMode = options?.toolMode || 'on_demand';
+    const format = options?.format || 'openai';
+    if (toolMode === 'on_demand')
+        return getMetaTools({ format });
+    return toLLMTools(entries, {
+        format,
+        surface: options?.surface || 'llm',
+        includeResponse: options?.includeResponse
+    });
+}
+/**
+ * Execute whatever the model called, in either mode. Dispatches on the tool name:
+ * a meta-tool name runs the discovery flow, anything else runs that entry directly.
+ * Identical handler execution, validation, and output-limit enforcement either way.
+ */
+async function handleToolCall(bridge, entries, toolCall, options) {
+    const surface = options?.surface || 'llm';
+    const context = options?.context;
+    if (isMetaToolName(toolCall.name)) {
+        return handleMetaToolCall(bridge, entries, toolCall, context, surface);
+    }
+    // Direct entry call (attach_all mode): respect per-surface visibility.
+    if (!isEntryVisible(entries[toolCall.name], surface))
+        throw new Error(`Tool not found: ${toolCall.name}`);
+    // `toolUse` enforces tbConfig.maxToolOutputChars on the executed result — the only
+    // place output is unbounded. Discovery results (tool_search / tool_describe) are
+    // deliberately left uncapped so a blanket search can never deadlock the model's
+    // own recovery path.
+    return toolUse(bridge, toolCall.name, toolCall.arguments || {}, context);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "typed-bridge",
     "description": "Type-safe server functions for TypeScript that also expose your backend as an MCP server and LLM tools for AI agents",
-    "version": "3.0.0",
+    "version": "4.0.0",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "author": "neilveil",
@@ -13,6 +13,7 @@
         "test:server": "tsx --watch src/demo/index.ts",
         "test:cli": "tsx src/scripts/cli.ts gen-typed-bridge-client --src ./src/demo/bridge/index.ts --dest ./test/bridge.ts",
         "test:bridge": "tsx test/index.ts",
+        "test:mcp": "tsx test/mcp.ts",
         "test:llm": "tsx test/llm.ts",
         "lint": "eslint",
         "prepublishOnly": "npm run dist"

package/readme.md

@@ -4,29 +4,31 @@
 
 # Typed Bridge
 
-### Write one function. Get a typed API, an MCP server, and LLM tools.
+### Let AI talk to your API. Natively.
 
 [![Downloads](https://img.shields.io/npm/dm/typed-bridge.svg)](https://www.npmjs.com/package/typed-bridge)
 [![Version](https://img.shields.io/npm/v/typed-bridge.svg)](https://www.npmjs.com/package/typed-bridge)
 [![License](https://img.shields.io/npm/l/typed-bridge.svg)](https://github.com/neilveil/typed-bridge/blob/main/license.txt)
 
-**Type-safe RPC for humans. Native tools for AI. Zero glue code.**
+**Write one TypeScript function. Get a typed client, OpenAI & Anthropic tools, and an MCP server — from a single Zod schema.**
 
 </div>
 
 ---
 
-## Your backend just became AI-native
+## Stop maintaining two backends
 
-You already write plain TypeScript functions on your server. Typed Bridge takes those exact functions and hands you three things at once:
+Most backends now ship twice. Once for your app — then again for AI: tool schemas, an MCP server, agent integrations, all kept in sync by hand for months.
 
-1. A **fully typed client** your frontend calls like local functions.
-2. An **MCP server** so Cursor, Claude Desktop, and Windsurf can call your backend directly.
-3. **LLM tool definitions** so OpenAI and Anthropic can use your backend as tools.
+Typed Bridge kills the duplication. Write a TypeScript function once, describe it with Zod, and instantly get:
 
-Same function. Same validation. No second codebase for AI. No hand written tool schemas. No drift.
+- A **fully typed API client** for your frontend — React, Vue, Angular, React Native, anything.
+- **OpenAI & Anthropic tools** so your agents can call your backend.
+- An **MCP server** for Cursor, Claude, and Windsurf.
 
-> Every function you ship is instantly something an agent can call. That is the whole pitch.
+And auth is not an afterthought: **agents inherit the exact same auth context and permissions as your users** — an agent can never reach something the signed-in user can't. One function. One schema. Every surface, secured the same way.
+
+> Your backend just became AI-native.
 
 ---
 
@@ -38,12 +40,23 @@ flowchart LR
     B --> C[Typed client for your frontend]
     B --> D[MCP server for AI tools]
     B --> E[LLM tool definitions]
+    C --> H[React, Vue, Angular, React Native]
     D --> F[Cursor, Claude, Windsurf]
     E --> G[OpenAI, Anthropic, your agents]
 ```
 
 You describe a function once with a Zod schema. Typed Bridge derives the client types, the MCP tool schema, and the LLM tool schema from that single source. They can never fall out of sync, because there is only one truth.
 
+### What that unlocks
+
+Point Claude or Cursor at your backend and it works across your real functions, with your real auth:
+
+> **You:** "Email the invoice for order #1234 to the customer."
+>
+> The agent searches your tools, finds `order.fetch`, `invoice.create`, and `email.send`, reads their schemas, and calls them in turn — running as the signed-in user, blocked from anything that user can't touch.
+
+No glue code. No tool schemas written by hand. No second backend. Just your functions.
+
 ---
 
 ## Quick start
@@ -54,50 +67,60 @@ You describe a function once with a Zod schema. Typed Bridge derives the client
 npm i typed-bridge
 ```
 
-### 2. Write a normal function
+### 2. Define your contexts (optional)
 
-`bridge/user/index.ts`:
+Name the shapes your middleware injects, so handlers can declare what they expect. `bridge/context.ts`:
 
 ```ts
-import { z } from 'typed-bridge'
-import * as types from './types'
-
-export const fetch = async (args: z.infer<typeof types.fetch.args>) => {
-    return db.users.findById(args.id)
-}
+export type user = { id: number }
+export type admin = { id: number; role: 'admin' }
+export type guest = { requestedAt: number }
 ```
 
-### 3. Describe it once
+### 3. Define an entry
 
-`bridge/user/types.ts`:
+One self-contained object per handler — schema and logic together. `bridge/user/index.ts`:
 
 ```ts
-import { z } from 'typed-bridge'
+import { z, defineEntry } from 'typed-bridge'
+import * as context from '../context'
 
-export const fetch = {
+export const fetch = defineEntry({
     description: 'Fetch a user by ID',
-    args: z.object({ id: z.number().min(1).describe('Unique user identifier') }),
-    res: z.object({ id: z.number(), name: z.string(), email: z.string() })
-}
+    args: z.object({
+        id: z.number().min(1).describe('Unique user identifier')
+    }),
+    res: z.object({
+        id: z.number().describe('User ID'),
+        name: z.string().describe('Full name'),
+        email: z.string().describe('Primary email address')
+    }),
+    handler: async (args, ctx: context.user) => {
+        return db.users.findById(args.id) // `args` is inferred as { id: number }
+    }
+})
 ```
 
-### 4. Wire it up with `defineBridge`
+`defineEntry` infers the handler's argument type from `args` and checks its return against `res` — no `z.infer<typeof ...>`, no manual `.parse()`, ever.
+
+`.describe()` your `res` fields too, not just `args`. In `on_demand` mode the model reads the response schema via `tool_describe` before it calls, so those descriptions help it use the output correctly.
+
+### 4. Register your entries
 
-`bridge/index.ts`:
+Map each route name straight to its entry. `bridge/index.ts`:
 
 ```ts
 import { defineBridge } from 'typed-bridge'
 import * as user from './user'
-import * as userTypes from './user/types'
 
 export const entries = {
-    'user.fetch': { handler: user.fetch, ...userTypes.fetch }
+    'user.fetch': user.fetch
 }
 
 export default defineBridge(entries)
 ```
 
-`defineBridge` auto-validates incoming args against your Zod schema. No manual `.parse()` in handlers, ever.
+A clean 1:1 mapping — `user.fetch` → `fetch`. No spreads, no schema copying. (Need to keep a handler off MCP or LLM? Add `mcp: false` / `llm: false` to its entry — covered in [Superpower 2](#choose-what-each-surface-can-touch).)
 
 ### 5. Boot the server, AI included
 
@@ -108,7 +131,7 @@ import bridge, { entries } from './bridge'
 createBridge(bridge, 8080, '/bridge', { entries, mcp: true })
 ```
 
-That is it. You now have a typed HTTP API, an MCP endpoint at `/bridge/mcp`, and an LLM tools endpoint at `/bridge/tools`. From one function.
+That is it. You now have a typed HTTP API and an MCP endpoint at `/bridge/mcp`. From one function.
 
 ---
 
@@ -130,6 +153,32 @@ typedBridgeConfig.host = 'http://localhost:8080/bridge'
 const user = await bridge['user.fetch']({ id: 1 })
 ```
 
+### Sending headers (auth and more)
+
+Every request sends `typedBridgeConfig.headers`. Set them once after login, or update a single header any time — the change applies to all subsequent calls:
+
+```ts
+// Set the full header set (e.g. right after sign-in)
+typedBridgeConfig.headers = {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${token}`
+}
+
+// Or add / change one header on the fly
+typedBridgeConfig.headers['X-Tenant'] = 'acme'
+
+// Clear it on logout
+delete typedBridgeConfig.headers['Authorization']
+```
+
+These headers are exactly what your `createMiddleware` and `mcpGetContext` read on the server, so the same token drives auth across HTTP and AI surfaces. You can also tap every response with `typedBridgeConfig.onResponse`:
+
+```ts
+typedBridgeConfig.onResponse = res => {
+    if (res.status === 401) redirectToLogin()
+}
+```
+
 Full autocomplete, full type safety, from server to screen. Your frontend never imports Zod and never sees your backend code. It is one generated file you can drop into React, Vue, Angular, React Native, or anything else.
 
 ---
@@ -149,13 +198,14 @@ Point any MCP client at it:
     "mcpServers": {
         "my-backend": {
             "url": "http://localhost:8080/bridge/mcp",
-            "headers": { "Authorization": "Bearer ${MCP_API_KEY}" },
-            "env": { "MCP_API_KEY": "your-api-key" }
+            "headers": { "Authorization": "Bearer your-api-key" }
         }
     }
 }
 ```
 
+Typed Bridge is a **remote (HTTP) MCP server**, so the client just needs the `url` and any auth `headers` — those headers reach your `mcpGetContext`. (The `env` block you may have seen elsewhere is only for **stdio** servers the client launches as a local process; there is no subprocess here, so it does nothing.)
+
 ### Auth that actually works
 
 MCP requests skip your normal middleware, so you derive context straight from headers:
@@ -173,72 +223,115 @@ createBridge(bridge, 8080, '/bridge', {
 
 The returned context lands in every handler as the second argument, exactly like middleware context. Same security model for humans and agents.
 
+### Control how many tools the client sees
+
+A `toolMode` option, set once on `createBridge`, decides how the server presents tools (defaults to `on_demand`):
+
+```ts
+createBridge(bridge, 8080, '/bridge', { entries, mcp: true, toolMode: 'attach_all' })
+```
+
+In `on_demand` (the default) the server lists just `tool_search`, `tool_describe`, and `tool_use`, and the client discovers the rest as it needs them — ideal for a large API behind a single MCP connection. In `attach_all` it lists every exposed entry as its own tool. Same two modes power direct LLM tool calling too — see [Superpower 3](#superpower-3-llm-tool-calling).
+
+`toolMode` controls **what's listed**, not what's reachable. It's a discovery strategy, not a sandbox: any entry visible to a surface stays callable (via `tool_use` or by its own name), so the two modes always execute identically. The hard boundary is the `mcp` / `llm` visibility flags — a hidden entry is never listed, discoverable, or callable.
+
 ### Choose what each surface can touch
 
-MCP and LLM tools are independent surfaces. Every entry is exposed to both by default, and two flags let you hide a handler from either one while it stays fully callable over HTTP:
+MCP and LLM tools are independent surfaces. Every entry is exposed to both by default, and two flags — set right on the entry via `defineEntry` — hide a handler from either one while it stays fully callable over HTTP:
 
 - `mcp: false` keeps a handler off the MCP server.
-- `llm: false` keeps it out of `toLLMTools`, tool search, and the `/bridge/tools` endpoint.
+- `llm: false` keeps it out of `getTools` and tool search.
 
 ```ts
-export const entries = {
-    'user.fetch': { handler: user.fetch, ...userTypes.fetch },
-    'user.remove': { handler: user.remove, ...userTypes.remove, mcp: false }, // your LLM app can call it, external MCP clients cannot
-    'admin.sync': { handler: admin.sync, ...adminTypes.sync, llm: false } // HTTP and MCP only, never an LLM tool
-}
+// Your LLM app can call it, external MCP clients cannot
+export const remove = defineEntry({
+    description: 'Remove a user',
+    args: z.object({ id: z.number().min(1) }),
+    res: z.object({ ok: z.boolean() }),
+    mcp: false,
+    handler: async (args, ctx: context.admin) => { ... }
+})
+
+// HTTP and MCP only, never an LLM tool
+export const sync = defineEntry({
+    description: 'Sync admin records',
+    args: z.object({}),
+    res: z.object({ synced: z.number() }),
+    llm: false,
+    handler: async (args, ctx: context.admin) => { ... }
+})
 ```
 
-Hidden tools are dropped from discovery and rejected if called by name, so a model cannot reach them even by guessing.
+Each flag governs its surface in **both modes** — under `attach_all` and `on_demand` alike, a hidden entry is neither attached directly nor discoverable through `tool_search`, and it is rejected if called by name. A model cannot reach it even by guessing.
 
 ---
 
 ## Superpower 3: LLM tool calling
 
-Skip MCP and talk to models directly. Typed Bridge speaks OpenAI, Anthropic, and raw JSON Schema.
+Skip MCP and talk to models directly. Typed Bridge speaks OpenAI, Anthropic, and raw JSON Schema — and one option decides **how** your tools reach the model.
+
+### Two modes, set with `toolMode`
 
-### Hand every tool to the model
+- **`on_demand`** (default) — the model gets three meta-tools and discovers the rest as it needs them.
+- **`attach_all`** — every eligible entry is attached as its own tool.
+
+You choose per call, right where you build the tool list. No global state:
 
 ```ts
-import { toLLMTools } from 'typed-bridge'
+import { getTools, handleToolCall } from 'typed-bridge'
 
-const tools = toLLMTools(entries, { format: 'openai' })
-// Pass `tools` straight into openai.chat.completions.create()
+// Build the tool list (openai | anthropic | json-schema). Omit toolMode to use the default, on_demand.
+const tools = getTools(entries, { toolMode: 'on_demand', format: 'openai' })
+
+// Execute whatever the model called — same call for both modes
+const result = await handleToolCall(bridge, entries, toolCall, { context })
 ```
 
-Formats: `openai`, `anthropic`, `json-schema`.
+Because you pass `toolMode` explicitly, a single process can run one assistant with `attach_all` and another with `on_demand`. `handleToolCall` needs no mode at all — it dispatches on the tool name (a meta-tool name runs the discovery flow, anything else runs that entry directly), so your loop is written once and never changes when you switch modes.
 
-### Have a giant API? Use meta-tools.
+### `on_demand` — three tools, discovered as needed (default)
 
-For hundreds of endpoints, do not flood the context window. Give the model three tools instead of two hundred:
+Most APIs have more endpoints than a model should see at once, so this is the default. Do not flood the context window — give the model three tools instead of two hundred:
 
 ```ts
-import { getMetaTools, handleMetaToolCall } from 'typed-bridge'
+const tools = getTools(entries, { toolMode: 'on_demand', format: 'openai' })
+// → tool_search, tool_describe, tool_use
 
-const tools = getMetaTools({ format: 'openai' })
-
-// The model discovers tools, inspects their schema, then calls them:
+// The model discovers, inspects, then calls:
 // 1. tool_search({ query: "user" })       → [{ name: "user.fetch", description: "..." }, ...]
 // 2. tool_describe({ name: "user.fetch" }) → { name, description, args, response }
 // 3. tool_use({ name: "user.fetch", arguments: { id: 1 } }) → { id: 1, name: "Alice" }
-
-const result = await handleMetaToolCall(bridge, entries, {
-    name: 'tool_use',
-    arguments: { name: 'user.fetch', arguments: { id: 1 } }
-})
 ```
 
 The model calls `tool_search` to discover what exists (names and descriptions only), `tool_describe` to get the full schema for the tool it needs, then `tool_use` to run it. Your token bill stays flat as your API grows.
 
-### Or just hit the REST endpoint
+### `attach_all` — every tool, up front
 
-```
-GET /bridge/tools?format=openai
+```ts
+const tools = getTools(entries, { toolMode: 'attach_all', format: 'openai' })
+// → one tool per entry: user.fetch, product.create, ...
+// Pass `tools` straight into openai.chat.completions.create()
 ```
 
+Best when you have a handful of endpoints and want the model to see them all immediately.
+
+> Two functions cover every case: `getTools` to build the tool list and `handleToolCall` to run whatever the model picks — in either mode.
+
 ---
 
 ## Why Typed Bridge
 
+You could wire all of this by hand. Here is what you skip.
+
+### vs hand-rolled REST + Express
+
+|                     | **Typed Bridge**                          | **Hand-rolled REST**                          |
+| ------------------- | ----------------------------------------- | --------------------------------------------- |
+| Endpoints           | Plain functions, auto-routed              | Routes, controllers, and handlers wired by hand |
+| Request validation  | Built in with Zod, automatic              | Added and maintained per route                |
+| Client + types      | One generated file, always in sync        | Hand-written fetch calls and types, or none   |
+| AI tooling          | MCP and LLM tools included                 | Build the whole AI layer yourself             |
+
 ### vs writing AI tools by hand
 
 |                          | **Typed Bridge**                          | **DIY tool calling**                         |
@@ -257,6 +350,8 @@ GET /bridge/tools?format=openai
 | Frontend framework     | Any                                           | React first, adapters for others    |
 | AI tooling             | Built in (MCP and LLM)                         | Not included                        |
 
+tRPC has a deeper React/inference ecosystem and richer client features. Reach for Typed Bridge when you also want AI surfaces and a framework-agnostic, standalone client.
+
 ### vs GraphQL
 
 |                    | **Typed Bridge**                          | **GraphQL**                                  |
@@ -266,6 +361,8 @@ GET /bridge/tools?format=openai
 | Learning curve     | Minimal, plain TypeScript                 | SDL, resolvers, fragments, queries           |
 | AI tooling         | Built in                                  | Roll your own                                |
 
+GraphQL is unmatched when clients need to shape their own queries across a complex graph. Typed Bridge is the simpler choice when you want typed RPC plus native AI access, not a query language.
+
 ---
 
 ## Middleware when you need it
@@ -280,11 +377,71 @@ createMiddleware('user.*', async (req, res) => {
         res.status(401).send('Unauthorized')
         return { next: false }
     }
-    return { context: { userId: 1 } }
+    return { context: { id: 1 } } // shape matches `context.user` from bridge/context.ts
+})
+```
+
+A middleware returns one of:
+
+- `{ context }` — merge these values into the context and continue.
+- `{ next: false }` — stop here. You must have sent a response (`res.status(...).send(...)`); the handler never runs.
+- nothing — continue with no context change.
+
+### Middlewares stack, broad to specific
+
+Every middleware whose pattern matches the route runs, ordered from least to most specific (a literal segment counts as more specific than `*`). Each one's context is merged on top of the previous, so the handler receives the combined result:
+
+```ts
+createMiddleware('*', async () => {
+    return { context: { requestedAt: Date.now() } } // runs first, for every route
+})
+
+createMiddleware('user.*', async (req, res) => {
+    const token = req.headers.authorization
+    if (!token?.startsWith('Bearer ')) {
+        res.status(401).send('Unauthorized')
+        return { next: false }
+    }
+    return { context: { userId: Number(token.split(' ')[1]) } }
+})
+
+createMiddleware('user.remove', async (req, res) => {
+    if (req.headers['x-admin'] !== 'true') {
+        res.status(403).send('Admin access required')
+        return { next: false }
+    }
+    return { context: { isAdmin: true } }
 })
 ```
 
-Broader patterns run first (`*`, then `user.*`, then `user.fetch`). Returned context is merged and passed to the handler.
+A call to `user.remove` runs all three in order — `*` → `user.*` → `user.remove` — and the handler's `ctx` is the merged `{ requestedAt, userId, isAdmin }`. A call to `user.fetch` runs only the first two and gets `{ requestedAt, userId }`. If any middleware returns `{ next: false }`, the chain stops immediately and the rest never run.
+
+### Reusing logic across middlewares
+
+The pattern stacking above is automatic. When you instead want one middleware to *build on* another's logic, extract a plain function and call it — full control over order and short-circuiting:
+
+```ts
+const auth = async (req: Request, res: Response) => {
+    const user = verifyToken(req.headers['x-auth-token'] || '')
+    if (!user) {
+        res.status(401).send('Unauthorized')
+        return { next: false as const }
+    }
+    return { next: true as const, context: user }
+}
+
+createMiddleware('admin.*', async (req, res) => {
+    const authRes = await auth(req, res)
+    if (authRes.next === false) return authRes // 401 already sent
+
+    if (!authRes.context.role.includes('admin')) {
+        res.status(403).send('Forbidden')
+        return { next: false }
+    }
+
+    return authRes // passes the authenticated user through as context
+})
+```
 
 ---
 
@@ -296,34 +453,52 @@ import { tbConfig } from 'typed-bridge'
 tbConfig.logs.request = true
 tbConfig.logs.response = true
 tbConfig.logs.error = true
+tbConfig.logs.argsOnError = true // Include handler args in error logs
+tbConfig.logs.contextOnError = true // Include resolved context in error logs
 tbConfig.responseDelay = 0 // Artificial delay in ms for testing loading states
-tbConfig.maxToolOutputChars = 0 // Cap MCP/LLM tool results (chars of JSON); 0 = unlimited
+tbConfig.maxToolOutputChars = 100_000 // Cap MCP/LLM tool results (chars of JSON); default 100_000, set 0 to disable
 ```
 
+> Tool exposure (`attach_all` vs `on_demand`) is **not** global — you pass `toolMode` explicitly to `getTools` for your own loop, and to `createBridge` for the MCP server.
+
 `createBridge` also returns the underlying Express `app` and `server`, so you can add routes, serve static files, or attach any Express middleware.
 
 ### Guarding tool output size
 
-The same function can serve a data-heavy response over HTTP and as an AI tool. A frontend handles a large payload fine, but feeding it to a model wastes tokens or overflows the context window. Set `tbConfig.maxToolOutputChars` to cap the serialized result on the **MCP and LLM tool surfaces only** (HTTP is never limited). Oversized results are **rejected, not truncated** — the caller gets an error telling it to narrow the query, so the model never receives invalid JSON:
+The same function can serve a data-heavy response over HTTP and as an AI tool. A frontend handles a large payload fine, but feeding it to a model wastes tokens or overflows the context window. So by default Typed Bridge caps tool results at **100,000 characters** on the **MCP and LLM tool surfaces only** (HTTP is never limited). Oversized results are **rejected, not truncated** — the caller gets an error telling it to narrow the query, so the model never receives invalid JSON:
 
 ```ts
-tbConfig.maxToolOutputChars = 100_000
-
-// A tool returning more than that responds with:
+// A tool result over the cap responds with:
 // "Result too large (182431 chars, limit 100000). Narrow the query with filters or pagination."
+
+tbConfig.maxToolOutputChars = 250_000 // raise it
+tbConfig.maxToolOutputChars = 0       // or disable the cap entirely
 ```
 
 ---
 
 ## Adding a new route
 
-1. Create the handler in `bridge/<module>/index.ts`.
-2. Add its Zod schema in `<module>/types.ts`.
-3. Register it in `bridge/index.ts`:
-    - Flat map for a plain typed API: `export default { 'module.action': module.action }`
-    - Entry based for AI features: `export const entries = { 'module.action': { handler: module.action, ...moduleTypes.action } }` then `export default defineBridge(entries)`
-4. Add middleware if needed and import it in your server entry.
-5. Regenerate the client.
+1. Define the entry with `defineEntry` in `bridge/<module>/index.ts` (description, args, res, handler, plus any `mcp`/`llm` flags).
+2. Register it in `bridge/index.ts` with a direct mapping: `export const entries = { 'module.action': module.action }` then `export default defineBridge(entries)`.
+3. Add middleware if needed and import it in your server entry.
+4. Regenerate the client.
+
+---
+
+## Upgrading from v3
+
+v4 unifies the LLM and MCP tool paths behind two functions and a single `toolMode` option. The MCP server itself is unchanged — `mcp: true` still mounts `/bridge/mcp` — but `toolMode` now defaults to `on_demand`.
+
+| v3                                                  | v4                                                            |
+| --------------------------------------------------- | ------------------------------------------------------------ |
+| `toolsFormat` option / `GET /bridge/tools` endpoint | Build the list in code: `getTools(entries, { toolMode, format })` |
+| `toLLMTools(entries, { format })`                   | `getTools(entries, { toolMode: 'attach_all', format })`      |
+| `getMetaTools({ format })`                          | `getTools(entries, { toolMode: 'on_demand', format })`       |
+| `handleMetaToolCall(...)` / direct `toolUse(...)`   | `handleToolCall(bridge, entries, toolCall, { context, surface })` |
+| `{ handler, ...types.fetch }` + separate `types.ts` | One `defineEntry({ ... })` object, mapped 1:1 in `entries`   |
+
+`handleToolCall` is mode-agnostic: it dispatches on the tool name, so the same loop runs whether you chose `attach_all` or `on_demand`.
 
 ---