Skip to content
v0.6.0MIT licensed, for Node.js, Bun and the browser

TypeScript functions, served as MCP tools.

Register an object of functions. defuss-mcp publishes them to every Model Context Protocol client over stdio, Express, bunway or any Fetch handler. Agents read named schemas and repair rejected calls, and TypeScript callers get the original types back.

bun add defuss-mcp
import { createMcpApi } from 'defuss-mcp';
import { createMcpHttp } from 'defuss-mcp/http';
const identity = { name: 'greeter', version: '1.0.0' };
const functions = { greet: (name: string) => 'Hello, ' + name };
export const api = createMcpApi(identity, functions, {
  metadata: { greet: { annotations: { readOnlyHint: true } } },
});
const endpoint = createMcpHttp(api);
Bun.serve({ port: 3000, fetch: (req) => endpoint.fetch(req) });

await tools.greet('Ada') "Hello, Ada" : string

#What you get from one registry

Functions become tools

Pass { add, greet } to createMcpApi. Object keys are tool names, so bundling and minification never rename a tool.

Agents repair their own calls

A generated contract turns the signature and JSDoc into named JSON Schema. A rejected argument returns its JSON Pointer and an instruction, not a stack trace.

Bytes and rich values arrive intact

Typed arrays travel as base64 trees, and Maps, BigInts, Dates and cycles use DSON. A plain JSON client still sees ordinary schemas.

One catalog, any host

stdio, Express, bunway and Fetch share one frozen catalog in JSON, SSE or automatic Streamable HTTP reply mode. Your application keeps its listener.

Your guards keep running

Authorization sees every HTTP exchange, and the defuss-rpc bridge re-enters the RPC dispatcher, so method guards also apply to MCP callers.

Hints for the host

Titles and annotations such as readOnlyHint and destructiveHint reach tools/list, where hosts decide whether to ask before a call.

How it works

#Write a function. Every client can call it.

The registry freezes its catalog when the first transport starts. Each HTTP request gets its own SDK server with its own headers and cancellation signal, while every request shares the compiled schemas.

Your functions { add, greet, byteAdd }
createMcpApi Tool registry schemas, metadata, hooks
serveMcpStdio Child process
endpoint.middleware Express, bunway
endpoint.fetch Bun.serve, browser
MCP clients TypeScript, Python, Go, Inspector
  1. Register

    An object of functions, a tuple, or explicit .json, .dson and .binary tools with their own schemas.

  2. Describe

    bunx defuss-mcp reads exports and JSDoc and writes named schemas that agents can discover.

  3. Mount

    Hand the registry to createMcpHttp or serveMcpStdio. Your host keeps its routes, listener and authentication.

  4. Call

    getMcpClient<typeof api> returns typed functions. Every other MCP client uses the advertised schemas.

Live demo

#An MCP server running in this tab

This page imports the published build, registers four tools and connects the official MCP TypeScript client to endpoint.fetch. Every exchange below is real Streamable HTTP; it never leaves your browser.

The demo starts when it scrolls into view.

tools/list

The catalog a stock MCP client receives. Pick a tool, edit its arguments as JSON and send tools/call.

    
                  
    Input schema

    Wire log

    HTTP exchanges between the SDK client and the endpoint in this page
    #JSON-RPCStatusReplyBytes in, outms
    Tested clients

    #Cross-runtime and client test-matrix

    Before a release, make e2e installs the tarball into an empty project and starts real server processes. Each official client discovers a byte tool, repairs a rejected field and calls the guarded RPC bridge, in every reply mode. A missing or failed cell fails the build.

    Passed cells per client and server; HTTP cells cover the JSON, SSE and automatic reply modes in each protocol era.
    ClientNode, ExpressBun, ExpressBun, bunwayBun, FetchNode, stdioBun, stdio
    TypeScript SDK on Node.js666622
    TypeScript SDK on Bun666622
    Python SDK666622
    Go SDK333311
    MCP Inspector CLI333311

    Measured with Node.js 24.22.3, Bun 1.4.5, Python 3.12.15 (MCP SDK 2.3.0), Go 1.27.4 (MCP SDK v1.8.0), MCP Inspector 2.16.0 and the TypeScript SDK 2.4.0 on Apple M5 Max, tarball sha256 1417c6d1d467.

    Performance

    #Measured in bench

    Every figure comes from make bench for v0.6.0 on one Apple M5 Max with other work running (load average 7.5). Clients and servers run in separate processes over loopback.

    Latency per call, Bun client

    Median of serial calls in milliseconds; shorter is faster. The MCP bar calls a registered function with a JSON reply, the RPC bar calls the same function through defuss-rpc on the same listener.

    Node, Express0.106 ms0.081 ms
    Bun, Express0.103 ms0.067 ms
    Bun, bunway0.072 ms0.051 ms
    Bun, Fetch0.070 ms0.048 ms
    Node, stdio0.033 ms
    Bun, stdio0.028 ms
    Data
    CaseMCP function calldefuss-rpc call
    Node, Express0.106 ms0.081 ms
    Bun, Express0.103 ms0.067 ms
    Bun, bunway0.072 ms0.051 ms
    Bun, Fetch0.070 ms0.048 ms
    Node, stdio0.033 ms
    Bun, stdio0.028 ms

    64 KiB binary echo, Node over Express

    Payload MiB per second in both directions with eight calls in flight; longer is faster.

    Typed client, compact214 MiB/s
    Binary tool, base64130 MiB/s
    Typed client, DSON27 MiB/s
    defuss-rpc, DSON31 MiB/s
    Data
    CasePayload MiB/s, eight in flight
    Typed client, compact214 MiB/s
    Binary tool, base64130 MiB/s
    Typed client, DSON27 MiB/s
    defuss-rpc, DSON31 MiB/s

    Fresh process: import index and HTTP entries

    Median milliseconds over eight alternating rounds against v0.4.0; shorter is faster. A Fetch host loads no Node adapter.

    Node.js38.9 ms50.4 ms
    Bun31.2 ms43.9 ms
    Data
    Casev0.6.0v0.4.0
    Node.js38.9 ms50.4 ms
    Bun31.2 ms43.9 ms

    The raw samples, the full matrix and the paired release comparison ship in the release archive under validation/. The verification notes describe sampling and limits.

    Install

    #Pick a transport layer

    ESM, CommonJS and TypeScript declarations for Node.js 22.19 or newer and Bun. Five runtime dependencies: the official MCP server SDK and its Node adapter, Ajv with its formats, and defuss-dson.

    A Fetch handler serves Streamable HTTP. The same endpoint works in any router that passes a Request.

    // server.ts, run with: bun server.ts
    import { createMcpApi } from 'defuss-mcp';
    import { createMcpHttp } from 'defuss-mcp/http';
    export const api = createMcpApi(
      { name: 'greeter', version: '1.0.0' },
      { greet(name: string) { return 'Hello, ' + name; } },
      { metadata: { greet: { title: 'Greet', annotations: { readOnlyHint: true } } } },
    );
    const endpoint = createMcpHttp(api);
    Bun.serve({ hostname: '127.0.0.1', port: 3000, fetch: (request) => endpoint.fetch(request) });
    // client.ts: the official SDK client with typed functions
    import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
    import { getMcpClient } from 'defuss-mcp/client';
    import type { api } from './server.ts';
    const sdk = new Client({ name: 'caller', version: '1.0.0' });
    await sdk.connect(new StreamableHTTPClientTransport(new URL('http://127.0.0.1:3000/mcp')));
    const { tools } = await getMcpClient<typeof api>(sdk);
    console.log(await tools.greet('Ada')); // "Hello, Ada", typed as string
    API

    #One small API covers every MCP protocol

    The same registry answers the two newest MCP revisions: 2026-07-28, which clients find through server/discover, and 2025-11-25 with its initialize handshake. It serves them over stdio and Streamable HTTP, with JSON, SSE or automatic replies. With automatic negotiation, the official TypeScript client selects 2026-07-28.

    ImportCallWhat it does
    defuss-mcpcreateMcpApi(identity, functions, options)Registers an object or tuple of functions; options set the schema compiler, the error sink and per-tool metadata.
    defuss-mcp.json, .dson, .binary, .groupAdds tools with a hand-written schema, a DSON graph, base64 bytes, or a staged batch that publishes atomically.
    defuss-mcp.observeCalls, .processCallsReceives start and finish events with durations, or transforms decoded inputs and results.
    defuss-mcp/httpcreateMcpHttp(registry, options)Returns fetch, middleware and close with host, origin, size and authorization checks.
    defuss-mcp/stdioserveMcpStdio(registry, options?)Serves the catalog on the process pipes of a child launched by the client. Reads stdin in linear time; maxMessageBytes bounds one message.
    defuss-mcp/clientgetMcpClient<typeof api>(sdk)Discovers the catalog once and returns typed remote functions over your connected SDK client.
    defuss-mcp/validationajvValidator()Compiles JSON Schema 2020-12 and draft-07 with formats; failures become pointer-based corrections.
    defuss-mcp/rpcexposeRpc(registry, rpcRoute, options)Publishes defuss-rpc methods as Namespace.method tools and dispatches through the RPC route and its guards.

    Give your agents access to all services

    Read the source, the architecture notes and the verification evidence, or hand llms.txt to your coding agent.