typed-bridge 2.1.5 → 3.0.0

package/readme.md

@@ -1,363 +1,332 @@
-# Typed Bridge - Strictly Typed Server Functions for TypeScript
+<div align="center">
+
+<img src="assets/default.png" alt="Typed Bridge" width="380" />
+
+# Typed Bridge
+
+### Write one function. Get a typed API, an MCP server, and LLM tools.
 
 [![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)
 
-**End-to-End Type Safety · Framework Agnostic · Zero Config**
+**Type-safe RPC for humans. Native tools for AI. Zero glue code.**
 
-Typed Bridge lets you define **strictly typed server functions** and auto-generates a typed client for your frontend. Call server functions like local functions, with full type safety from backend to frontend. No routers, no resolvers, no schema stitching. Just plain TypeScript functions.
+</div>
 
 ---
 
-## Quick Start
+## Your backend just became AI-native
 
-### 1. Install
+You already write plain TypeScript functions on your server. Typed Bridge takes those exact functions and hands you three things at once:
 
-```bash
-npm i typed-bridge
-```
+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.
 
-### 2. Setup Server
+Same function. Same validation. No second codebase for AI. No hand written tool schemas. No drift.
 
-Create `server.ts`:
+> Every function you ship is instantly something an agent can call. That is the whole pitch.
 
-```typescript
-import { createBridge } from 'typed-bridge'
-import bridge from './bridge'
+---
 
-createBridge(bridge, 8080, '/bridge')
+## One function, three superpowers
+
+```mermaid
+flowchart LR
+    A[Your TypeScript functions] --> B[defineBridge]
+    B --> C[Typed client for your frontend]
+    B --> D[MCP server for AI tools]
+    B --> E[LLM tool definitions]
+    D --> F[Cursor, Claude, Windsurf]
+    E --> G[OpenAI, Anthropic, your agents]
 ```
 
-### 3. Create Bridge File
+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.
 
-Define routes in `bridge/index.ts`:
+---
 
-```typescript
-import * as user from './user'
+## Quick start
 
-export default {
-    'user.fetch': user.fetch,
-    'user.update': user.update,
-    'user.fetchAll': user.fetchAll
-}
-```
+### 1. Install
 
-### 4. Declare Functions
+```bash
+npm i typed-bridge
+```
 
-These are just normal async functions. The first argument is what the client sends, the return type is what the client receives. That's it.
+### 2. Write a normal function
 
 `bridge/user/index.ts`:
 
-```typescript
-interface User {
-    id: number
-    name: string
-    email: string
-}
+```ts
+import { z } from 'typed-bridge'
+import * as types from './types'
 
-// Fetch a single user by id
-export const fetch = async (args: { id: number }): Promise<User> => {
+export const fetch = async (args: z.infer<typeof types.fetch.args>) => {
     return db.users.findById(args.id)
 }
-
-// Update user fields
-export const update = async (args: { id: number; name?: string; email?: string }): Promise<User> => {
-    return db.users.update(args.id, args)
-}
-
-// List all users
-export const fetchAll = async (): Promise<User[]> => {
-    return db.users.findAll()
-}
 ```
 
-### 5. Generate Typed Client
+### 3. Describe it once
 
-Add the generation script to `package.json`:
+`bridge/user/types.ts`:
 
-```json
-{
-    "scripts": {
-        "gen:typed-bridge-client": "typed-bridge gen-typed-bridge-client --src ./src/bridge/index.ts --dest ./bridge.ts"
-    }
-}
-```
-
-Run it:
+```ts
+import { z } from 'typed-bridge'
 
-```bash
-npm run gen:typed-bridge-client
+export const fetch = {
+    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() })
+}
 ```
 
-### 6. Use in Frontend
+### 4. Wire it up with `defineBridge`
 
-Import the generated `bridge.ts` file in your frontend:
+`bridge/index.ts`:
 
-```typescript
-import bridge, { typedBridgeConfig } from './bridge'
+```ts
+import { defineBridge } from 'typed-bridge'
+import * as user from './user'
+import * as userTypes from './user/types'
 
-typedBridgeConfig.host = 'http://localhost:8080/bridge'
-typedBridgeConfig.headers = {
-    'Content-Type': 'application/json',
-    Authorization: 'Bearer 123'
-}
-typedBridgeConfig.onResponse = res => {
-    // Custom response handling
+export const entries = {
+    'user.fetch': { handler: user.fetch, ...userTypes.fetch }
 }
 
-const user = await bridge['user.fetch']({ id: 1 })
+export default defineBridge(entries)
 ```
 
----
-
-## Keeping the Client in Sync
+`defineBridge` auto-validates incoming args against your Zod schema. No manual `.parse()` in handlers, ever.
 
-The generated `bridge.ts` file lives in your backend and needs to reach your frontend. Here are common approaches:
+### 5. Boot the server, AI included
 
-**Monorepo**: Import the file directly across packages. Simplest if your repos are co-located.
+```ts
+import { createBridge } from 'typed-bridge'
+import bridge, { entries } from './bridge'
 
-**Copy script**: Add a build step that copies the file: `cp ../backend/bridge.ts ./src/bridge.ts`
+createBridge(bridge, 8080, '/bridge', { entries, mcp: true })
+```
 
-**Serve and fetch**: Host the generated file via Express static and use [clone-kit](https://www.npmjs.com/package/clone-kit) to pull it in your frontend build. [Full guide](./docs/auto-bridge-sync.md)
+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.
 
 ---
 
-## Middleware
+## Superpower 1: The typed client
 
-Typed Bridge provides middleware that runs before bridge handlers.
+Generate a standalone client file for your frontend:
 
-```ts
-createMiddleware('user.fetch', async (req, res) => {
-    console.log('Middleware for user.fetch')
-})
+```bash
+typed-bridge gen-typed-bridge-client --src ./src/bridge/index.ts --dest ./bridge.ts
 ```
 
-Use glob patterns to match multiple routes:
+Call your backend like it lives in the same file:
 
 ```ts
-createMiddleware('user.*', async (req, res) => {
-    console.log('Middleware for all user routes')
-})
-```
+import bridge, { typedBridgeConfig } from './bridge'
 
-Middlewares execute in order of specificity, broader patterns run first:
+typedBridgeConfig.host = 'http://localhost:8080/bridge'
 
-```
-*            → runs first (matches everything)
-user.*       → runs second
-user.fetch   → runs last (most specific)
+const user = await bridge['user.fetch']({ id: 1 })
 ```
 
-### Context
+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.
 
-Middlewares can return a `context` object that gets merged and passed to the handler:
-
-```ts
-createMiddleware('user.*', async (req, res) => {
-    return {
-        context: {
-            a: 1
-        }
-    }
-})
+---
 
-createMiddleware('user.fetch', async (req, res) => {
-    return {
-        context: {
-            b: 2
-        }
-    }
-})
-```
+## Superpower 2: The MCP server (the headline act)
 
-The handler receives the merged context:
+Flip one flag and your backend becomes a [Model Context Protocol](https://modelcontextprotocol.io) server. AI tools connect to it and call your real functions, with your real validation.
 
 ```ts
-type Context = {
-    a: number
-    b: number
-}
+createBridge(bridge, 8080, '/bridge', { entries, mcp: true })
+```
 
-export const fetch = async (
-    args: { id: number },
-    context: Context
-): Promise<{ id: number; name: string } | undefined> => {
-    console.log(context) // { a: 1, b: 2 }
-    return users.find(user => user.id === args.id)
+Point any MCP client at it:
+
+```json
+{
+    "mcpServers": {
+        "my-backend": {
+            "url": "http://localhost:8080/bridge/mcp",
+            "headers": { "Authorization": "Bearer ${MCP_API_KEY}" },
+            "env": { "MCP_API_KEY": "your-api-key" }
+        }
+    }
 }
 ```
 
-### Request Validation
+### Auth that actually works
 
-Throw errors or send custom responses to block requests:
+MCP requests skip your normal middleware, so you derive context straight from headers:
 
 ```ts
-createMiddleware('user.*', async (req, res) => {
-    if (req.headers.authorization !== 'Bearer 123') {
-        throw new Error('Unauthorized')
+createBridge(bridge, 8080, '/bridge', {
+    entries,
+    mcp: true,
+    mcpGetContext: async headers => {
+        const user = await verifyToken(headers['authorization'])
+        return { userId: user.id, role: user.role }
     }
 })
 ```
 
-For custom status codes:
+The returned context lands in every handler as the second argument, exactly like middleware context. Same security model for humans and agents.
 
-```ts
-createMiddleware('user.*', async (req, res) => {
-    if (req.headers.authorization !== 'Bearer 123') {
-        res.status(401).send('Unauthorized')
+### Choose what each surface can touch
 
-        // Required to stop processing, otherwise the next middleware or handler will run
-        return { next: false }
-    }
-})
+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: false` keeps a handler off the MCP server.
+- `llm: false` keeps it out of `toLLMTools`, tool search, and the `/bridge/tools` endpoint.
+
+```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
+}
 ```
 
----
+Hidden tools are dropped from discovery and rejected if called by name, so a model cannot reach them even by guessing.
 
-## Zod Validation
+---
 
-Typed Bridge ships with Zod and re-exports it as `z`. Define schemas and use them in handlers:
+## Superpower 3: LLM tool calling
 
-### 1. Declare Schemas
+Skip MCP and talk to models directly. Typed Bridge speaks OpenAI, Anthropic, and raw JSON Schema.
 
-`types.ts`:
+### Hand every tool to the model
 
 ```ts
-import { z } from 'typed-bridge'
+import { toLLMTools } from 'typed-bridge'
 
-export const fetch = {
-    args: z.object({
-        id: z.number().min(1)
-    }),
-    res: z.object({
-        id: z.number(),
-        name: z.string()
-    })
-}
+const tools = toLLMTools(entries, { format: 'openai' })
+// Pass `tools` straight into openai.chat.completions.create()
 ```
 
-### 2. Use in Handler
+Formats: `openai`, `anthropic`, `json-schema`.
+
+### Have a giant API? Use meta-tools.
+
+For hundreds of endpoints, do not flood the context window. Give the model three tools instead of two hundred:
 
 ```ts
-import { z } from 'typed-bridge'
-import * as types from './types'
+import { getMetaTools, handleMetaToolCall } from 'typed-bridge'
 
-export const fetch = async (
-    args: z.infer<typeof types.fetch.args>,
-    context: { id: number }
-): Promise<z.infer<typeof types.fetch.res>> => {
-    args = types.fetch.args.parse(args)
+const tools = getMetaTools({ format: 'openai' })
 
-    const user = users.find(user => user.id === args.id)
-    if (!user) {
-        throw new Error(`User with ID ${args.id} not found`)
-    }
+// The model discovers tools, inspects their schema, then calls them:
+// 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" }
 
-    return user
-}
+const result = await handleMetaToolCall(bridge, entries, {
+    name: 'tool_use',
+    arguments: { name: 'user.fetch', arguments: { id: 1 } }
+})
 ```
 
-The generated client automatically resolves Zod types to plain TypeScript. Your frontend never depends on Zod.
+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
 
-## Configuration
+```
+GET /bridge/tools?format=openai
+```
 
-```typescript
-import { tbConfig } from 'typed-bridge'
+---
 
-tbConfig.logs.request = true
-tbConfig.logs.response = true
-tbConfig.logs.error = true
+## Why Typed Bridge
 
-tbConfig.logs.argsOnError = true
-tbConfig.logs.contextOnError = true
+### vs writing AI tools by hand
 
-tbConfig.responseDelay = 0 // Artificial delay in ms (useful for testing loading states)
-```
+|                          | **Typed Bridge**                          | **DIY tool calling**                         |
+| ------------------------ | ----------------------------------------- | -------------------------------------------- |
+| Tool schemas             | Derived from your Zod types               | Hand written and kept in sync manually       |
+| MCP server               | One flag                                  | A separate service to build and maintain     |
+| Validation               | Shared with your API                      | Re-implemented for the AI path               |
+| Drift between code and AI | Impossible, single source                | Constant, two sources                        |
 
----
+### vs tRPC
 
-## Extending the Server
+|                        | **Typed Bridge**                              | **tRPC**                            |
+| ---------------------- | --------------------------------------------- | ----------------------------------- |
+| Setup                  | Plain functions, generate a client, done      | Routers, procedures, adapters       |
+| Monorepo required      | No, the client is a standalone file           | Practically yes for type inference  |
+| Frontend framework     | Any                                           | React first, adapters for others    |
+| AI tooling             | Built in (MCP and LLM)                         | Not included                        |
 
-`createBridge` returns the underlying Express `app` and `server` instances, so you can add custom routes, serve static files, or attach any Express middleware:
+### vs GraphQL
+
+|                    | **Typed Bridge**                          | **GraphQL**                                  |
+| ------------------ | ----------------------------------------- | -------------------------------------------- |
+| Setup              | Define functions, generate client         | Schema, resolvers, codegen                   |
+| Type safety        | Automatic from signatures                 | Requires a codegen toolchain                 |
+| Learning curve     | Minimal, plain TypeScript                 | SDL, resolvers, fragments, queries           |
+| AI tooling         | Built in                                  | Roll your own                                |
 
-```typescript
-import { createBridge, onShutdown } from 'typed-bridge'
-import path from 'path'
-import bridge from './bridge'
+---
 
-const { app, server } = createBridge(bridge, 8080, '/bridge')
+## Middleware when you need it
 
-// Serve static files
-app.use(express.static(path.join(__dirname, 'public')))
+Pattern based middleware runs before handlers and can inject context:
 
-// Custom GET endpoint
-app.get('/status', (req, res) => {
-    res.json({ status: 'ok', uptime: process.uptime() })
-})
+```ts
+import { createMiddleware } from 'typed-bridge'
 
-// Cleanup on graceful shutdown (SIGINT/SIGTERM)
-onShutdown(() => {
-    console.log('Server shutting down')
+createMiddleware('user.*', async (req, res) => {
+    if (!req.headers.authorization) {
+        res.status(401).send('Unauthorized')
+        return { next: false }
+    }
+    return { context: { userId: 1 } }
 })
 ```
 
----
+Broader patterns run first (`*`, then `user.*`, then `user.fetch`). Returned context is merged and passed to the handler.
 
-## Typed Bridge vs Alternatives
+---
 
-### vs tRPC
+## Configuration
 
-|                        | **Typed Bridge**                              | **tRPC**                                           |
-| ---------------------- | --------------------------------------------- | -------------------------------------------------- |
-| **Setup**              | Define functions, generate typed client, done | Routers, procedures, adapters                      |
-| **Monorepo required?** | No, generated client is a standalone file     | Practically yes, for type inference                |
-| **Frontend framework** | Any (React, Vue, Angular, RN, etc.)           | React-first, adapters for others                   |
-| **Learning curve**     | Minimal, plain async functions                | Moderate, procedures, context, middleware patterns |
-| **Runtime validation** | Zod (built-in)                                | Zod or others via `.input()`                       |
+```ts
+import { tbConfig } from 'typed-bridge'
 
-### vs GraphQL
+tbConfig.logs.request = true
+tbConfig.logs.response = true
+tbConfig.logs.error = true
+tbConfig.responseDelay = 0 // Artificial delay in ms for testing loading states
+tbConfig.maxToolOutputChars = 0 // Cap MCP/LLM tool results (chars of JSON); 0 = unlimited
+```
 
-|                    | **Typed Bridge**                                       | **GraphQL**                                                |
-| ------------------ | ------------------------------------------------------ | ---------------------------------------------------------- |
-| **Setup**          | Define functions, generate typed client, done          | Schema definition, resolvers, codegen                      |
-| **Type safety**    | Automatic from function signatures                     | Requires codegen toolchain (e.g. GraphQL Code Generator)   |
-| **Overfetching**   | Not applicable, you control what each function returns | Solved by design with field selection                      |
-| **Learning curve** | Minimal, plain TypeScript                              | Significant: SDL, resolvers, fragments, queries, mutations |
-| **Best for**       | App-specific backends, internal APIs                   | Public APIs, multi-client data graphs                      |
+`createBridge` also returns the underlying Express `app` and `server`, so you can add routes, serve static files, or attach any Express middleware.
 
-Typed Bridge is for teams that want **type-safe RPCs without the architecture overhead**. You write normal TypeScript functions on the server, and the client just works.
+### 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:
 
-## Recommended File Organization
+```ts
+tbConfig.maxToolOutputChars = 100_000
 
+// A tool returning more than that responds with:
+// "Result too large (182431 chars, limit 100000). Narrow the query with filters or pagination."
 ```
-src/
-  server.ts           Server entry
-  middleware.ts        Middleware registrations (side-effect import)
-  bridge/
-    index.ts          Route map (flat object)
-    user/
-      index.ts        Handler functions
-      types.ts        Zod schemas (optional)
-    product/
-      index.ts        Handler functions
-      types.ts        Zod schemas (optional)
-```
 
-### Adding a new route
+---
+
+## Adding a new route
 
-1. Create handler in `bridge/<module>/index.ts`
-2. If using Zod, add schemas in `<module>/types.ts` using `z` from `typed-bridge`
-3. Register route in `bridge/index.ts` as `'module.action': module.action`
-4. If middleware needed, add `createMiddleware(...)` and import the file in server entry
-5. Run `gen:typed-bridge-client` to regenerate the typed client
+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.
 
 ---
 
 ## Developer
 
-Developed & maintained by [neilveil](https://github.com/neilveil). Give a star to support this project!
+Built and maintained by [neilveil](https://github.com/neilveil). If Typed Bridge saves you a codebase, drop a star.

package/.vscode/settings.json

@@ -1,3 +0,0 @@
-{
-    "editor.formatOnSave": true
-}