95 lines
7.9 KiB
Markdown
95 lines
7.9 KiB
Markdown
# @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.
|
|
|