skills/plugins/document-navigator/docs/devtools/tooling/mcp

@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.

License

MIT — © Suaveplan Team.