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

<!-- begin:auto-docs -->
## Documentation tree

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

## Quick start

```ts
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.