fib-mcp

MCP (Model Context Protocol) SDK for the fibjs ecosystem.

McpServer and McpClient extend @modelcontextprotocol/sdk directly. fib-mcp adds fibjs-native server transports (sse, ws, http), a fibjs-native client transport for sse, and handler methods for mounting server transports into your own http.Server.

TypeScript runs directly on fibjs; no compile step is required.

Features

McpServer extends sdk.McpServer — all SDK methods available as-is
McpClient extends sdk.Client — all SDK methods available as-is
fibjs-native server transports: sse, ws, http
client transports: SDK ws, SDK Streamable HTTP, fibjs-native sse
HTTP client uses the SDK Streamable HTTP transport
SSE automatic endpoint discovery (standard MCP SSE protocol)
Designed to be mounted into user-managed http.Server routes

Installation

fibjs --install fib-mcp

Quick Start

Server - HTTP

import http from 'http';
import { McpServer } from 'fib-mcp';

const server = new McpServer({ name: 'demo-server', version: '1.0.0' });

server.tool('ping', {}, async () => ({
  content: [{ type: 'text', text: 'pong' }],
}));

const svr = new http.Server(3000, {
  '/mcp': server.httpHandler(),
});
svr.start();

Client — HTTP

import { McpClient } from 'fib-mcp';

const client = new McpClient({ name: 'demo-client', version: '1.0.0' });
await client.connect({ transport: 'streamable-http', url: 'http://127.0.0.1:3000/mcp' });

const { tools } = await client.listTools();
const result = await client.callTool({ name: 'ping', arguments: {} });
console.log(result.content[0].text);

await client.close();

Server — WebSocket

import http from 'http';
import { McpServer } from 'fib-mcp';

const server = new McpServer({ name: 'demo-server', version: '1.0.0' });

server.tool('ping', {}, async () => ({
  content: [{ type: 'text', text: 'pong' }],
}));

const svr = new http.Server(3000, {
  '/mcp': server.wsHandler(),
});
svr.start();

Client — WebSocket

import { McpClient } from 'fib-mcp';

const client = new McpClient({ name: 'demo-client', version: '1.0.0' });
await client.connect({ transport: 'ws', url: 'ws://127.0.0.1:3000/mcp' });

const result = await client.callTool({ name: 'ping', arguments: {} });
await client.close();

Server — SSE

import http from 'http';
import { McpServer } from 'fib-mcp';

const server = new McpServer({ name: 'demo-server', version: '1.0.0' });

server.tool('ping', {}, async () => ({
  content: [{ type: 'text', text: 'pong' }],
}));

const svr = new http.Server(3000, {
  '/mcp': server.sseHandlers(),
});
svr.start();

Client — SSE

import { McpClient } from 'fib-mcp';

const client = new McpClient({ name: 'demo-client', version: '1.0.0' });

// messageUrl auto-discovered from server's `endpoint` event:
await client.connect({ transport: 'sse', url: 'http://127.0.0.1:3000/mcp/sse' });

// Or with an explicit messageUrl:
// await client.connect({ transport: 'sse', url: 'http://127.0.0.1:3000/mcp/sse', messageUrl: 'http://127.0.0.1:3000/mcp/message' });

const result = await client.callTool({ name: 'ping', arguments: {} });
await client.close();

Server — stdio

import { McpServer } from 'fib-mcp';

const server = new McpServer({ name: 'demo-server', version: '1.0.0' });

server.tool('ping', {}, async () => ({
  content: [{ type: 'text', text: 'pong' }],
}));

await server.listenStdio();

Client — stdio

import { McpClient } from 'fib-mcp';

const client = new McpClient({ name: 'demo-client', version: '1.0.0' });

// Spawn an MCP server script via stdio:
await client.connect({ transport: 'stdio', path: './my_mcp_server.ts' });

// Or connect to an explicit command:
// await client.connect({ transport: 'stdio', command: 'fibjs', args: ['my_mcp_server.ts'] });

const result = await client.callTool({ name: 'ping', arguments: {} });
await client.close();

API Reference

McpServer

Extends @modelcontextprotocol/sdk McpServer. All SDK methods (tool, resource, prompt, registerTool, connect, close, etc.) are inherited unchanged.

fib-mcp adds the following fibjs-native transport methods:

tool vs registerTool

Both are valid, and both register MCP tools.

tool(...): high-level helper API; concise and preferred for most examples.
registerTool(...): lower-level SDK API; useful when you want explicit control over registration shape (for example, full schema objects and custom handler wiring).

Why the repository has both styles:

README quick examples use tool(...) for readability.
Some production paths use registerTool(...) because those handlers need the lower-level control surface.

This is expected behavior, not a protocol mismatch.

Note: a single McpServer instance should bind only one network transport (ws, sse, or http). If you need multiple network protocols, create separate McpServer instances.

`listenStdio(): Promise<void>`

Connect to stdio. Used when the server is spawned by an MCP host.

`wsHandler(): Handler`

Returns a fibjs WebSocket upgrade handler for use in a route map.

const svr = new http.Server(3000, { '/mcp': server.wsHandler() });

`sseHandlers(): Record<string, Handler>`

Returns SSE route handlers for nested fibjs routing (SSE GET + POST message endpoint).

const svr = new http.Server(3000, { '/mcp': server.sseHandlers() });

The server automatically sends an endpoint event on connect, so clients can discover the POST URL without it being pre-configured.

`httpHandler(options?): Handler`

Returns an HTTP POST handler for mounting at a route chosen by your outer router.

const svr = new http.Server(3000, { '/mcp': server.httpHandler() });

Options:

timeoutMs?: request timeout in ms (default: 30000)

`httpHandlers(options?): Record<string, Handler>`

Returns a flat fibjs route map for JSON-RPC over HTTP POST.

const svr = new http.Server(3000, server.httpHandlers({ path: '/mcp' }));

Options:

path?: route path (default: /mcp)
timeoutMs?: request timeout in ms (default: 30000)

McpClient

Extends @modelcontextprotocol/sdk Client. All SDK methods (callTool, listTools, readResource, listResources, getPrompt, listPrompts, listResourceTemplates, ping, complete, connect, close, etc.) are inherited unchanged with identical signatures and return types.

fib-mcp adds the following transport connection methods:

`connect(config | transport): Promise<void>`

Unified client entry point.

Use transport descriptor objects aligned with MCP Registry transport style:

{ transport: 'streamable-http', url, options? }
{ transport: 'sse', url, messageUrl?, options? }
{ transport: 'ws' | 'websocket', url }
{ transport: 'stdio', path, options? }
{ transport: 'stdio', command, args?, options? }

Passing a transport object still works and is forwarded to the SDK connect(transport).

SSE notes:

If messageUrl is omitted, the client waits for the server's endpoint SSE event and discovers the POST URL automatically (standard MCP SSE protocol).

Options:

headers?: extra request headers
method?: POST method override (default: POST)

Transport Notes

Transport	Client	Server
stdio	SDK	SDK
http	SDK Streamable HTTP	fibjs-native
sse	fibjs-native	fibjs-native
ws	SDK	fibjs-native

Bidirectional Session

BidirectionalSession provides transport-agnostic bidirectional MCP over one connection:

Forward calls: local side calls peer tools
Reverse calls: peer calls local tools through ctx.client
Session-scoped capability negotiation for reverse channel
Backward compatible with plain MCP clients
Hides internal server implementation details from the public API

Constructor (New API)

BidirectionalSession now uses a single options object.

import { BidirectionalSession } from 'fib-mcp';

const session = new BidirectionalSession({
  serverInfo: { name: 'my-server', version: '1.0.0' },
  clientInfo: { name: 'my-client', version: '1.0.0' },
  clientOptions: {},
  serverOptions: {},
});

Options:

serverInfo (required): local server identity
clientInfo (optional): local client identity, default bidirectional-client/1.0.0
clientOptions (optional): forwarded to internal McpClient
serverOptions (optional): forwarded to internal McpServer

Tool Callback Context

BidirectionalSession.tool(...) is the bidirectional wrapper and is the recommended path for reverse-call handlers. Internally it delegates to the underlying MCP server tool registration and injects ctx.client.

If you need MCP standard registration APIs, call them directly on BidirectionalSession (registerTool, registerResource, registerPrompt, etc.).

session.tool('server.proxy', {}, async (_args, ctx) => {
  const nested = await ctx.client.callTool({ name: 'peer.echo', arguments: {} });
  return {
    content: [{ type: 'text', text: nested.content[0].text }],
  };
});

Handler context:

ctx.client: peer client bound to current session
ctx.extra: MCP request metadata (includes sessionId)

Connection APIs

WebSocket convenience:

wsHandler() for server route mounting
connect({ transport: 'ws', url }) for active side over websocket

Stdio convenience:

connect({ transport: 'stdio', path, options? }) for active side stdio script launch
connect({ transport: 'stdio', command, args?, options? }) for active side stdio command launch
listenStdio() for passive side stdio accept

Generic transport:

connect(config) or connect(transport) active side
accept(transport) passive side

Both return BidirectionalConnection:

connection.sessionId
connection.callTool(...)
connection.listTools(...)
connection.readResource(...)
connection.listResources(...)
connection.listPrompts(...)
connection.getPrompt(...)
connection.close()

Note: internal client/server instances are intentionally hidden from the public API.

Forwarding Gateway

ForwardingGateway is a client/app/server gateway that proxies MCP over WebSocket:

client -> gateway: normal MCP over WebSocket (any MCP client — browser, CLI, etc.)
gateway -> server: raw JSON-RPC request / notification relay over one bidirectional session
server -> gateway: reverse MCP handled locally by app tools through ReverseMcpEndpoint

Default behavior:

client-side initialize is terminated locally by the gateway
client → server requests are forwarded as raw JSON-RPC requests
client → server notifications are forwarded as raw JSON-RPC notifications
server → client notifications are forwarded by the gateway default path
server → gateway reverse MCP calls use gateway-local tools via ctx.client

Minimal shape:

import http from 'http';
import { ForwardingGateway } from 'fib-mcp';

const gateway = new ForwardingGateway({
  appInfo: { name: 'app-gateway', version: '1.0.0' },
  connectServer: async () => ({ transport: 'ws', url: 'ws://127.0.0.1:9001/mcp' }),
});

gateway.tool('app.greet', {}, async () => ({
  content: [{ type: 'text', text: 'hello-from-app' }],
}));

const svr = new http.Server(3000, {
  '/mcp': gateway.wsHandler(),
});
svr.start();

Hooks — Middleware API

All three hooks use the same (ctx, next) middleware signature:

Call next() — execute the default behavior (forward the original message)
Call next(modifiedMessage) — execute the default behavior with a rewritten message
Return without calling next() — suppress the default behavior entirely
Throw an error — send a JSON-RPC error response (attach a numeric .code property)

`onClientRequest(ctx, next)`

Intercepts JSON-RPC requests arriving from the downstream MCP client.

ctx fields:

ctx.session — current session state (includes serverConnection, authContext, etc.)
ctx.message — the raw JSON-RPC request message
ctx.reply(result) — respond locally without forwarding; alternative to next()

const gateway = new ForwardingGateway({
  appInfo: { name: 'app-gateway', version: '1.0.0' },
  connectServer: async () => ({ transport: 'ws', url: 'ws://127.0.0.1:9001/mcp' }),
  onClientRequest: async (ctx, next) => {
    // Auth check: only allow certain methods
    if ((ctx.message as any).method === 'tools/call') {
      const allowed = checkPermission(ctx.session.authContext);
      if (!allowed) {
        const err: any = new Error('forbidden');
        err.code = -32001;
        throw err;
      }
    }
    return next(); // continue with default forwarding
  },
});

Rewrite a request before forwarding:

onClientRequest: async (ctx, next) => {
  const msg = ctx.message as any;
  if (msg.method === 'agent.session.open') {
    return next({
      ...ctx.message,
      params: { ...msg.params, agentId: resolveAgentId(ctx.session.authContext) },
    } as any);
  }
  return next();
},

Respond locally without touching the upstream server:

onClientRequest: async (ctx, next) => {
  if ((ctx.message as any).method === 'local.ping') {
    return ctx.reply({ pong: true });
  }
  return next();
},

`onClientNotification(ctx, next)`

Intercepts JSON-RPC notifications arriving from the downstream MCP client.

onClientNotification: async (ctx, next) => {
  // log and pass through
  console.log('client notification:', (ctx.message as any).method);
  return next();
},

Suppress forwarding by not calling next():

onClientNotification: async (_ctx, _next) => {
  // drop all client notifications
},

`onServerNotification(ctx, next)`

Intercepts JSON-RPC notifications arriving from the upstream MCP server.

onServerNotification: async (ctx, next) => {
  // Inject an extra field before forwarding to the client
  const msg = ctx.message as any;
  return next({
    ...ctx.message,
    params: { ...msg.params, _gatewayId: 'my-app' },
  } as any);
},

`onClientDisconnect(session)`

Called when a downstream client disconnects. Use for cleanup (e.g. releasing local state keyed on session.clientSessionId).

onClientDisconnect: (session) => {
  releaseResources(session.clientSessionId);
},

Authentication

Use authenticate to validate the connection and attach context:

const gateway = new ForwardingGateway({
  appInfo: { name: 'app-gateway', version: '1.0.0' },
  authenticate: async ({ request, initializeRequest }) => {
    const token = request?.headers?.['authorization'];
    const user = await verifyToken(token);
    if (!user) throw new Error('unauthorized');
    return { user };
  },
  connectServer: async ({ authContext }) => ({
    transport: 'ws',
    url: `ws://127.0.0.1:9001/mcp`,
    headers: { 'x-user-id': authContext.user.id },
  }),
});

The resolved authContext is available on ctx.session.authContext in all hook callbacks.

Options Reference

Option	Type	Description
`appInfo`	`ClientInfo`	Gateway identity (`name`, `version`)
`clientCapabilities`	`object?`	Capabilities advertised to downstream clients
`instructions`	`string?`	Instructions string sent in `initialize` response
`authenticate`	`fn?`	Validate connection; return value becomes `session.authContext`
`connectServer`	`fn?`	Return transport config for the upstream server connection
`onClientRequest`	`fn?`	Middleware for client → server requests
`onClientNotification`	`fn?`	Middleware for client → server notifications
`onServerNotification`	`fn?`	Middleware for server → client notifications
`onClientDisconnect`	`fn?`	Called when a client session ends
`serverClientInfo`	`ClientInfo?`	Identity used for the outbound server connection
`serverClientOptions`	`object?`	Options forwarded to the outbound client
`reverseServerOptions`	`object?`	Options for the local reverse-MCP server endpoint

WebSocket Example

import http from 'http';
import { BidirectionalSession } from 'fib-mcp';

const accepted = new BidirectionalSession({
  serverInfo: { name: 'accepted-server', version: '1.0.0' },
  clientInfo: { name: 'accepted-client', version: '1.0.0' },
});

accepted.tool('server.ping', {}, async () => ({
  content: [{ type: 'text', text: 'pong-from-accepted' }],
}));

const host = new http.Server(3000, {
  '/mcp': accepted.wsHandler(),
});
host.start();

const peer = new BidirectionalSession({
  serverInfo: { name: 'peer-server', version: '1.0.0' },
  clientInfo: { name: 'peer-client', version: '1.0.0' },
});

const conn = await peer.connect({ transport: 'ws', url: 'ws://127.0.0.1:3000/mcp' });
const pong = await conn.callTool({ name: 'server.ping', arguments: {} });
console.log(pong.content[0].text);

Stdio Example

import { BidirectionalSession } from 'fib-mcp';

const parent = new BidirectionalSession({
  serverInfo: { name: 'parent-server', version: '1.0.0' },
  clientInfo: { name: 'parent-client', version: '1.0.0' },
});

parent.tool('parent.greet', {}, async () => ({
  content: [{ type: 'text', text: 'hello-from-parent' }],
}));

const conn = await parent.connect({ transport: 'stdio', command: 'fibjs', args: ['./child.ts'] });
const echo = await conn.callTool({ name: 'child.echo', arguments: {} });
console.log(echo.content[0].text);

In-Memory Example

import { BidirectionalSession } from 'fib-mcp';
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';

const left = new BidirectionalSession({
  serverInfo: { name: 'left-server', version: '1.0.0' },
  clientInfo: { name: 'left-client', version: '1.0.0' },
});

const right = new BidirectionalSession({
  serverInfo: { name: 'right-server', version: '1.0.0' },
  clientInfo: { name: 'right-client', version: '1.0.0' },
});

const [leftTransport, rightTransport] = InMemoryTransport.createLinkedPair();
const leftConn = await left.connect(leftTransport);
const rightConn = await right.accept(rightTransport);

Backward Compatibility

Plain MCP clients are supported:

Forward calls work as normal
Reverse calls are blocked if peer does not advertise reverse capability
Mixed plain and bidirectional clients can coexist on the same server

Transport Contract

Custom transport should implement SDK Transport behavior:

start()
send(message, options?)
close()
onmessage(message, extra?)
onerror(error)
onclose()

Notifications

Notification flow works on both normal MCP transports and BidirectionalSession.

Testing

fibjs test/all.test.ts
fibjs --test test/integration_test.ts
fibjs --test test/edge_cases_test.ts
fibjs --test test/bidirectional_provider_test.ts

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
index.ts		index.ts
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

fib-mcp

Features

Installation

Quick Start

Server - HTTP

Client — HTTP

Server — WebSocket

Client — WebSocket

Server — SSE

Client — SSE

Server — stdio

Client — stdio

API Reference

McpServer

tool vs registerTool

listenStdio(): Promise<void>

wsHandler(): Handler

sseHandlers(): Record<string, Handler>

httpHandler(options?): Handler

httpHandlers(options?): Record<string, Handler>

McpClient

connect(config | transport): Promise<void>

Transport Notes

Bidirectional Session

Constructor (New API)

Tool Callback Context

Connection APIs

Forwarding Gateway

Hooks — Middleware API

onClientRequest(ctx, next)

onClientNotification(ctx, next)

onServerNotification(ctx, next)

onClientDisconnect(session)

Authentication

Options Reference

WebSocket Example

Stdio Example

In-Memory Example

Backward Compatibility

Transport Contract

Notifications

Testing

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`listenStdio(): Promise<void>`

`wsHandler(): Handler`

`sseHandlers(): Record<string, Handler>`

`httpHandler(options?): Handler`

`httpHandlers(options?): Record<string, Handler>`

`connect(config | transport): Promise<void>`

`onClientRequest(ctx, next)`

`onClientNotification(ctx, next)`

`onServerNotification(ctx, next)`

`onClientDisconnect(session)`

Packages