@suaveplan/mcp - Universal Model Context Protocol (MCP) server + client with JSON-RPC dispatcher, pluggable transports (in-memory, stdio, HTTP+SSE), AbortSignal cancellation, progress notifications, authorize hook, OTel meter, and Zod-derived wire types.

Universal Model Context Protocol (MCP) server + client with a pluggable transport stack, JSON-RPC dispatcher, AbortSignal cancellation, progress notifications, authorize hook, and OTel meter.

Documentation tree

mcp-client — MCPClient is the consumer-side surface of the Model Context Protocol. connect(transport) performs the MCP initializ…
- mcp-client — MCPClient is the consumer-side surface of the Model Context Protocol. connect(transport) performs the MCP initializ…
error-codes — @suaveplan/mcp raises three typed error classes — MCPError, MCPTransportError, and MCPProtocolError — for every…
- error-codes — @suaveplan/mcp raises three typed error classes — MCPError, MCPTransportError, and MCPProtocolError — for every…
events — events.ts declares MCPEventMap — the typed payload map shared by MCPServer and MCPClient via the `EventBus<MCPE…
- events — events.ts declares MCPEventMap — the typed payload map shared by MCPServer and MCPClient via the `EventBus<MCPE…
dispatcher — JsonRpcDispatcher is the symmetric JSON-RPC 2.0 engine sitting under MCPServer and MCPClient. It owns id allocati…
- dispatcher — JsonRpcDispatcher is the symmetric JSON-RPC 2.0 engine sitting under MCPServer and MCPClient. It owns id allocati…
schemas — schemas.ts is the single source of truth for every wire shape in @suaveplan/mcp. Every public TypeScript type for a…
- schemas — schemas.ts is the single source of truth for every wire shape in @suaveplan/mcp. Every public TypeScript type for a…
mcp-server — MCPServer is the host-side surface of the Model Context Protocol. Owners register tools, resources, prompts, and root…
- mcp-server — MCPServer is the host-side surface of the Model Context Protocol. Owners register tools, resources, prompts, and root…
telemetry — telemetry registers the OpenTelemetry meter @suaveplan/mcp and exposes three instruments (mcp_request_total, `mcp…
- telemetry — telemetry registers the OpenTelemetry meter @suaveplan/mcp and exposes three instruments (mcp_request_total, `mcp…
http-sse — HttpSseTransport rides MCP over a duplex pair: outbound requests via HTTP POST to endpoint and inbound server-pushe…
- http-sse — HttpSseTransport rides MCP over a duplex pair: outbound requests via HTTP POST to endpoint and inbound server-pushe…
in-memory — InMemoryTransport.pair() creates two Transport instances wired head-to-head. A send on one is immediately dispatc…
- in-memory — InMemoryTransport.pair() creates two Transport instances wired head-to-head. A send on one is immediately dispatc…
stdio — StdioTransport frames JSON-RPC messages over a newline-delimited JSON byte stream — the MCP spec default for sub-proc…
- stdio — StdioTransport frames JSON-RPC messages over a newline-delimited JSON byte stream — the MCP spec default for sub-proc…
transport — The Transport interface is the contract that decouples JsonRpcDispatcher from any specific I/O backend. Concrete tr…
- transport — The Transport interface is the contract that decouples JsonRpcDispatcher from any specific I/O backend. Concrete tr…
types — types/types.ts collects the structural / scalar types @suaveplan/mcp uses across modules that are NOT part of the w…
- types — types/types.ts collects the structural / scalar types @suaveplan/mcp uses across modules that are NOT part of the w…

Quick start

import { InMemoryTransport, MCPClient, MCPServer } from "@suaveplan/mcp";

const server = new MCPServer({ info: { name: "demo-server", version: "0.1.0" } });
server.registerTool({
    name: "echo",
    description: "Echo back the input",
    inputSchema: { type: "object", properties: { msg: { type: "string" } } },
    async handler({ msg }) {
        return { content: [{ type: "text", text: String(msg) }] };
    },
});

const client = new MCPClient({ info: { name: "demo-client", version: "0.1.0" } });

const [a, b] = InMemoryTransport.pair();
await server.start(a);
await client.connect(b);

const result = await client.callTool("echo", { msg: "hello" });
console.log(result.content);
await client.disconnect();
await server.stop();

Transport options

Transport	Universal?	Subpath export	Notes
`InMemoryTransport.pair()`	yes	`./transport/in-memory`	In-process bridge; used by tests and embedded hosts.
`createStdioTransport({ readable, writable })`	yes	`./transport/stdio`	Newline-delimited JSON. Caller injects byte streams; no Node imports.
`createHttpSseTransport({ endpoint, fetchImpl, eventSourceImpl })`	yes	`./transport/http-sse`	HTTP POST out, SSE in. Caller injects platform globals or fakes.

The Transport interface is exported so consumers can ship their own (e.g. WebSocket once @suaveplan/network-websockets lands).

Surface

Module	Subpath	Highlights
Errors	`./error-codes`	`MCP_CODES` (15 codes), `MCPError`, `MCPTransportError`, `MCPProtocolError`.
Schemas	`./schemas`	Every wire type as a Zod schema + `z.infer` type.
JSON-RPC	`./jsonrpc`	`JsonRpcDispatcher` — symmetric request/notification engine.
Server	`./server`	`MCPServer` — tool/resource/prompt/root registration, authorize hook, sampling+completion providers, progress, abort.
Client	`./client`	`MCPClient` — initialize handshake, cached lists, `callTool` / `readResource` / `getPrompt` / `complete` / `subscribeResource`.
Telemetry	`./telemetry`	`mcp_request_total` counter, `mcp_notification_total` counter, `mcp_request_duration_ms` histogram.
Events	`./events`	`MCPEventMap` + `createMCPEventBus()`.

MCP methods supported

All host-side methods of the MCP 2024-11-05 spec: initialize, ping, tools/list, tools/call, resources/list, resources/templates/list, resources/read, resources/subscribe, resources/unsubscribe, prompts/list, prompts/get, completion/complete, sampling/createMessage, roots/list, logging/setLevel. All notifications: notifications/initialized, notifications/cancelled, notifications/progress, notifications/message, notifications/resources/updated, notifications/resources/list_changed, notifications/tools/list_changed, notifications/prompts/list_changed, notifications/roots/list_changed.

Error codes

MCP.PROTOCOL_INVALID, MCP.METHOD_NOT_FOUND, MCP.INVALID_PARAMS, MCP.INTERNAL_ERROR, MCP.UNAUTHORIZED, MCP.REQUEST_CANCELLED, MCP.TIMEOUT, MCP.TRANSPORT_CLOSED, MCP.TRANSPORT_ERROR, MCP.NOT_INITIALIZED, MCP.ALREADY_CONNECTED, MCP.DUPLICATE_REGISTRATION, MCP.NOT_FOUND, MCP.PROTOCOL_VERSION_MISMATCH, MCP.HANDLER_FAILED.

7.9 KiB Raw Blame History