typed-bridge 2.1.4 → 3.0.0

package/dist/tools/index.d.ts

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+export type BridgeEntry = {
+    handler: (...args: any[]) => Promise<any>;
+    description?: string;
+    args?: z.ZodType;
+    res: z.ZodType;
+    mcp?: boolean;
+    llm?: boolean;
+};
+export type BridgeEntries = Record<string, BridgeEntry>;
+export type ExtractHandlers<T extends BridgeEntries> = {
+    [K in keyof T]: T[K] extends {
+        handler: infer H;
+    } ? H : never;
+};
+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 interface ToLLMToolsOptions {
+    format?: LLMToolFormat;
+    includeResponse?: boolean;
+}
+export interface ToolCall {
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export declare function defineBridge<T extends BridgeEntries>(entries: T): ExtractHandlers<T>;
+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[];
+export declare function getMetaTools(options?: {
+    format?: LLMToolFormat;
+}): ({
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+} | {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+})[] | {
+    type: string;
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                query: {
+                    type: string;
+                    description: string;
+                };
+            };
+        };
+    } | {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+}[] | {
+    name: string;
+    description: string;
+    input_schema: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+        };
+    } | {
+        type: string;
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+}[];
+export declare function toolSearch(entries: BridgeEntries, query?: string): {
+    name: string;
+    description?: string;
+}[];
+export declare function toolDescribe(entries: BridgeEntries, name: string): {
+    name: string;
+    description: string | undefined;
+    args: any;
+    response: any;
+};
+/**
+ * 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.
+ */
+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>;

package/dist/tools/index.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLM_TOOL_FORMATS = void 0;
+exports.isLLMToolFormat = isLLMToolFormat;
+exports.defineBridge = defineBridge;
+exports.toToolInputSchema = toToolInputSchema;
+exports.schemaToJSONSchema = schemaToJSONSchema;
+exports.toLLMTools = toLLMTools;
+exports.getMetaTools = getMetaTools;
+exports.toolSearch = toolSearch;
+exports.toolDescribe = toolDescribe;
+exports.enforceToolOutputLimit = enforceToolOutputLimit;
+exports.toolUse = toolUse;
+exports.handleMetaToolCall = handleMetaToolCall;
+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);
+}
+function defineBridge(entries) {
+    const bridge = {};
+    for (const [key, entry] of Object.entries(entries)) {
+        bridge[key] = async (...handlerArgs) => {
+            if (entry.args)
+                handlerArgs[0] = entry.args.parse(handlerArgs[0]);
+            return entry.handler(...handlerArgs);
+        };
+    }
+    return bridge;
+}
+const NO_ARGS_SCHEMA = { type: 'object', properties: {}, additionalProperties: false };
+function toToolInputSchema(args) {
+    if (!args)
+        return { ...NO_ARGS_SCHEMA };
+    const s = schemaToJSONSchema(args);
+    if (!s || s.type !== 'object')
+        return { ...NO_ARGS_SCHEMA };
+    return s;
+}
+function schemaToJSONSchema(schema) {
+    const jsonSchema = zod_1.z.toJSONSchema(schema, {
+        unrepresentable: 'any',
+        override: (ctx) => {
+            // z.date() is unrepresentable in JSON Schema — emit ISO 8601 string
+            if (ctx.zodSchema?._zod?.def?.type === 'date') {
+                ctx.jsonSchema.type = 'string';
+                ctx.jsonSchema.format = 'date-time';
+            }
+        }
+    });
+    delete jsonSchema['$schema'];
+    return jsonSchema;
+}
+// --- Direct tool generation (attach all tools to LLM) ---
+function toLLMTools(entries, options) {
+    const format = options?.format || 'openai';
+    const includeResponse = options?.includeResponse || false;
+    // 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)
+            continue;
+        const description = entry.description;
+        const parameters = toToolInputSchema(entry.args);
+        let response;
+        if (includeResponse)
+            response = schemaToJSONSchema(entry.res);
+        switch (format) {
+            case 'openai':
+                tools.push({
+                    type: 'function',
+                    function: { name, description, parameters, ...(response ? { response } : {}) }
+                });
+                break;
+            case 'anthropic':
+                tools.push({
+                    name,
+                    description,
+                    input_schema: parameters,
+                    ...(response ? { output_schema: response } : {})
+                });
+                break;
+            case 'json-schema':
+                tools.push({ name, description, parameters, ...(response ? { response } : {}) });
+                break;
+            default: {
+                const exhaustiveCheck = format;
+                throw new Error(`Unhandled LLM tool format: ${exhaustiveCheck}`);
+            }
+        }
+    }
+    return tools;
+}
+// --- Meta-tools (tool_search → tool_describe → tool_use) ---
+function getMetaTools(options) {
+    const format = options?.format || 'openai';
+    const searchTool = {
+        name: 'tool_search',
+        description: 'Search for available tools by keyword. Returns matching tool names and descriptions. Use tool_describe to get the full schema before calling tool_use.',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Case-insensitive search query matched against tool names and descriptions'
+                }
+            }
+        }
+    };
+    const describeTool = {
+        name: 'tool_describe',
+        description: 'Get the full input and output schema for a tool. Call this after tool_search and before tool_use.',
+        parameters: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'The tool name returned by tool_search (e.g., "user.fetch")'
+                }
+            },
+            required: ['name']
+        }
+    };
+    const useTool = {
+        name: 'tool_use',
+        description: 'Execute a tool by name. Use tool_search and tool_describe first to discover tools and their schemas.',
+        parameters: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'The tool name to execute'
+                },
+                arguments: {
+                    type: 'object',
+                    description: 'Arguments matching the input schema from tool_describe'
+                }
+            },
+            required: ['name']
+        }
+    };
+    const tools = [searchTool, describeTool, useTool];
+    switch (format) {
+        case 'openai':
+            return tools.map(t => ({ type: 'function', function: t }));
+        case 'anthropic':
+            return tools.map(t => ({ name: t.name, description: t.description, input_schema: t.parameters }));
+        default:
+            return tools;
+    }
+}
+function toolSearch(entries, query) {
+    const results = [];
+    const q = query?.toLowerCase();
+    for (const [name, entry] of Object.entries(entries)) {
+        if (entry.llm === false)
+            continue;
+        if (q) {
+            const haystack = `${name} ${entry.description || ''}`.toLowerCase();
+            if (!haystack.includes(q))
+                continue;
+        }
+        results.push({ name, description: entry.description });
+    }
+    return results;
+}
+function toolDescribe(entries, name) {
+    const entry = entries[name];
+    if (!entry || entry.llm === false)
+        throw new Error(`Tool not found: ${name}`);
+    return {
+        name,
+        description: entry.description,
+        args: toToolInputSchema(entry.args),
+        response: schemaToJSONSchema(entry.res)
+    };
+}
+/**
+ * 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.
+ */
+function enforceToolOutputLimit(result) {
+    const serialized = JSON.stringify(result) ?? '';
+    const limit = config_1.config.maxToolOutputChars;
+    if (limit > 0 && serialized.length > limit) {
+        throw new Error(`Result too large (${serialized.length} chars, limit ${limit}). Narrow the query with filters or pagination.`);
+    }
+    return serialized;
+}
+async function toolUse(bridge, name, args, context) {
+    const handler = bridge[name];
+    if (!handler)
+        throw new Error(`Tool not found: ${name}`);
+    const result = await handler(args, context);
+    enforceToolOutputLimit(result);
+    return result;
+}
+async function handleMetaToolCall(bridge, entries, toolCall, context) {
+    switch (toolCall.name) {
+        case 'tool_search':
+            return toolSearch(entries, toolCall.arguments?.query);
+        case 'tool_describe':
+            return toolDescribe(entries, toolCall.arguments?.name);
+        case 'tool_use': {
+            const args = toolCall.arguments;
+            const entry = entries[args.name];
+            if (!entry || entry.llm === false)
+                throw new Error(`Tool not found: ${args.name}`);
+            return toolUse(bridge, args.name, args.arguments || {}, context);
+        }
+        default:
+            throw new Error(`Unknown meta-tool: ${toolCall.name}. Expected "tool_search", "tool_describe", or "tool_use".`);
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "typed-bridge",
-    "description": "Strictly typed server functions for typescript apps",
-    "version": "2.1.4",
+    "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",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "author": "neilveil",
@@ -13,13 +13,15 @@
         "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:llm": "tsx test/llm.ts",
         "lint": "eslint",
-        "docs": "cat readme.md docs/* > docs.md"
+        "prepublishOnly": "npm run dist"
     },
     "bin": {
         "typed-bridge": "./dist/scripts/cli.js"
     },
     "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.29.0",
         "chalk": "^5.4.1",
         "commander": "^13.1.0",
         "compression": "^1.8.0",
@@ -38,10 +40,12 @@
         "@types/node": "^22.14.1",
         "@typescript-eslint/eslint-plugin": "^8.30.1",
         "@typescript-eslint/parser": "^8.30.1",
+        "dotenv": "^17.4.2",
         "eslint": "^9.25.0",
         "eslint-plugin-node": "^11.1.0",
         "globals": "^16.0.0",
         "nodemon": "^3.1.9",
+        "openai": "^6.42.0",
         "prettier": "^3.5.3",
         "rimraf": "^6.0.1",
         "tsconfig-paths": "^4.2.0",
@@ -49,15 +53,26 @@
         "typescript-eslint": "^8.30.1"
     },
     "keywords": [
+        "agents",
+        "ai",
+        "anthropic",
         "api",
         "backend",
-        "development",
         "framework",
         "functions",
         "grpc",
+        "llm",
+        "mcp",
+        "model-context-protocol",
+        "openai",
+        "rpc",
         "server",
+        "tool-calling",
+        "tools",
         "trpc",
+        "type-safe",
         "typed",
+        "typescript",
         "validation",
         "zod"
     ]