@mcp-ts/sdk 2.5.2 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/README.md +3 -574
  2. package/dist/adapters/agui-adapter.d.mts +4 -4
  3. package/dist/adapters/agui-adapter.d.ts +4 -4
  4. package/dist/adapters/agui-middleware.d.mts +4 -4
  5. package/dist/adapters/agui-middleware.d.ts +4 -4
  6. package/dist/adapters/ai-adapter.d.mts +4 -4
  7. package/dist/adapters/ai-adapter.d.ts +4 -4
  8. package/dist/adapters/langchain-adapter.d.mts +4 -4
  9. package/dist/adapters/langchain-adapter.d.ts +4 -4
  10. package/dist/adapters/mastra-adapter.d.mts +3 -3
  11. package/dist/adapters/mastra-adapter.d.ts +3 -3
  12. package/dist/client/index.d.mts +2 -2
  13. package/dist/client/index.d.ts +2 -2
  14. package/dist/client/index.js +3 -0
  15. package/dist/client/index.js.map +1 -1
  16. package/dist/client/index.mjs +3 -0
  17. package/dist/client/index.mjs.map +1 -1
  18. package/dist/client/react.d.mts +10 -18
  19. package/dist/client/react.d.ts +10 -18
  20. package/dist/client/react.js +17 -0
  21. package/dist/client/react.js.map +1 -1
  22. package/dist/client/react.mjs +17 -0
  23. package/dist/client/react.mjs.map +1 -1
  24. package/dist/client/vue.d.mts +4 -4
  25. package/dist/client/vue.d.ts +4 -4
  26. package/dist/client/vue.js +3 -0
  27. package/dist/client/vue.js.map +1 -1
  28. package/dist/client/vue.mjs +3 -0
  29. package/dist/client/vue.mjs.map +1 -1
  30. package/dist/{index-B3GPsPsi.d.mts → index-BrDkbut5.d.ts} +2 -1
  31. package/dist/{index-gNdSQTSz.d.ts → index-DHQvlx4K.d.mts} +2 -1
  32. package/dist/index.d.mts +5 -5
  33. package/dist/index.d.ts +5 -5
  34. package/dist/index.js +1056 -863
  35. package/dist/index.js.map +1 -1
  36. package/dist/index.mjs +1048 -858
  37. package/dist/index.mjs.map +1 -1
  38. package/dist/{multi-session-client-CB4oDrQX.d.ts → multi-session-client-CQzymvHl.d.ts} +183 -227
  39. package/dist/{multi-session-client-xj3iQIv6.d.mts → multi-session-client-C_Ja2TuV.d.mts} +183 -227
  40. package/dist/server/index.d.mts +338 -88
  41. package/dist/server/index.d.ts +338 -88
  42. package/dist/server/index.js +1054 -864
  43. package/dist/server/index.js.map +1 -1
  44. package/dist/server/index.mjs +1046 -859
  45. package/dist/server/index.mjs.map +1 -1
  46. package/dist/shared/index.d.mts +4 -4
  47. package/dist/shared/index.d.ts +4 -4
  48. package/dist/shared/index.js.map +1 -1
  49. package/dist/shared/index.mjs.map +1 -1
  50. package/dist/{tool-router-CsKVXbQB.d.mts → tool-router-C1n7OXbl.d.mts} +1 -1
  51. package/dist/{tool-router-C-Mw1_BQ.d.ts → tool-router-CBIawFnt.d.ts} +1 -1
  52. package/dist/{types-6SmXege4.d.mts → types-DX71u9gR.d.mts} +11 -3
  53. package/dist/{types-6SmXege4.d.ts → types-DX71u9gR.d.ts} +11 -3
  54. package/migrations/neon/20260513010000_install_mcp_sessions.sql +4 -34
  55. package/migrations/supabase/20260330195700_install_mcp_sessions.sql +5 -62
  56. package/package.json +2 -1
  57. package/src/client/core/sse-client.ts +5 -0
  58. package/src/client/react/use-mcp.ts +27 -28
  59. package/src/server/handlers/sse-handler.ts +671 -629
  60. package/src/server/index.ts +2 -1
  61. package/src/server/mcp/multi-session-client.ts +34 -10
  62. package/src/server/mcp/oauth-client.ts +197 -205
  63. package/src/server/mcp/storage-oauth-provider.ts +149 -29
  64. package/src/server/mcp/tool-policy-gateway.ts +11 -1
  65. package/src/server/storage/file-backend.ts +25 -21
  66. package/src/server/storage/index.ts +71 -0
  67. package/src/server/storage/memory-backend.ts +24 -12
  68. package/src/server/storage/neon-backend.ts +70 -72
  69. package/src/server/storage/redis-backend.ts +26 -36
  70. package/src/server/storage/sqlite-backend.ts +25 -39
  71. package/src/server/storage/supabase-backend.ts +45 -54
  72. package/src/server/storage/types.ts +22 -2
  73. package/src/shared/types.ts +13 -1
package/README.md CHANGED
@@ -1,580 +1,9 @@
1
- <p align="center">
2
- <a href="https://github.com/zonlabs/mcp-ts">
3
- <picture>
4
- <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.png">
5
- <img src="docs/images/logo-light.png" alt="mcp toolkit" width="400">
6
- </picture>
7
- </a>
8
- </p>
1
+ # @mcp-ts/sdk
9
2
 
10
- <div align="center">
11
- <p>Every resource is context for your AI</p>
12
-
13
- <p>
14
- <a href="https://mcp-assistant.in/">🌐 Website</a>
15
- &nbsp;&nbsp;|&nbsp;&nbsp;
16
- <a href="https://docs.mcp-assistant.in/">📚 Documentation</a>
17
- </p>
18
-
19
-
20
- <p>
21
- <a href="https://www.npmjs.com/package/@mcp-ts/sdk">
22
- <img src="https://img.shields.io/npm/v/@mcp-ts/sdk?color=dc2626&label=npm&logo=npm&style=flat-square" alt="npm version" />
23
- </a>
24
- <a href="https://pypi.org/project/mcpassistant-gateway/">
25
- <img src="https://img.shields.io/pypi/v/mcpassistant-gateway?color=3776ab&label=pypi&logo=pypi&style=flat-square" alt="pypi version" />
26
- </a>
27
- <a href="https://opensource.org/licenses/MIT">
28
- <img src="https://img.shields.io/badge/license-MIT-84cc16?style=flat-square" alt="License: MIT" />
29
- </a>
30
- </p>
31
- </div>
32
-
33
- <br />
34
-
35
- ## Why does `mcp-ts or toolkit` even exist?
36
-
37
- MCP makes it possible for AI applications to talk to tools, prompts, and resources, but building applications on top of MCP quickly becomes more than calling `listTools()` and `callTool()`.
38
-
39
- You need to manage user sessions, OAuth flows, reconnects, storage, browser updates, framework adapters, and on-demand tool discovery so agents can load and call only what they need instead of flooding the model context, similar to Claude Code's [advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use).
40
-
41
- `mcp-ts` exists to handle that application layer while keeping your MCP data in infrastructure you own or choose. See [storage backends](https://docs.mcp-assistant.in/storage-backends/overview) and [framework adapters](https://docs.mcp-assistant.in/ai-adapters/overview).
42
-
43
- It gives you a practical foundation for building MCP-native apps:
44
-
45
- - Have multiple users using your application
46
- - Already using AI SDK, LangChain, Mastra, and AG-UI Protocol where handling oauth, tokens management for mcp clients seems overhead
47
- - Reduce large model context with on-demand tool discovery through `ToolRouter`
48
- - Render interactive MCP Apps in your application.
49
- - Run programmatic tool calling inside a secure sandbox with `CodeMode`
50
-
51
- In short: the official MCP SDK gives you the protocol building blocks. `mcp-ts` gives you the application layer for building MCP applications around them.
52
-
53
- ## When you may not need it ?
54
-
55
- If you already use a managed service/platform such as Smithery, Klavis Strata, Composio, nango or a similar SDK, you may not need `mcp-ts`.
56
-
57
- ---
58
-
59
- ## 📑 Table of Contents
60
-
61
- - [Features](#features)
62
- - [Packages](#packages)
63
- - [Examples](#examples)
64
- - [Inspiration](#inspiration)
65
- - [SDK Setup (@mcp-ts/sdk)](#sdk-setup-mcp-tssdk)
66
- - [Installation](#installation)
67
- - [Quick Start](#quick-start)
68
- - [MCP Endpoint (Hosted)](#-mcp-endpoint-hosted)
69
- - [Adapters](#-adapters)
70
- - [AG-UI Middleware](#-ag-ui-middleware)
71
- - [MCP Apps (SEP-1865)](#️-mcp-apps-sep-1865)
72
- - [Documentation](#documentation)
73
- - [Topics Covered](#️-topics-covered)
74
- - [Environment Setup](#environment-setup)
75
- - [Configuration Examples](#-configuration-examples)
76
- - [Gateway Setup (mcpassistant-gateway)](#gateway-setup-mcpassistant-gateway)
77
- - [Installation](#installation-1)
78
- - [Usage](#usage)
79
- - [Architecture](#architecture)
80
- - [Contributing](#contributing)
81
-
82
- ---
83
-
84
- <a id="packages"></a>
85
-
86
- ## 📦 Packages
87
-
88
- | Package | Description | Install |
89
- | :--- | :--- | :--- |
90
- | **[@mcp-ts/sdk](src)** | Core TypeScript/JavaScript SDK for client applications. | `npm i @mcp-ts/sdk` |
91
- | **[@mcp-ts/tool-router](packages/tool-router)** | ToolRouter for dynamic tool discovery across many MCP servers. | `npm i @mcp-ts/tool-router` |
92
- | **[@mcp-ts/codemode](packages/code-mode)** | CodeMode: sandboxed program execution for tool calling. | `npm i @mcp-ts/codemode` |
93
- | **[mcpassistant-gateway](packages/local-gateway)** | Python bridge for local MCP support in remote apps. | `pip install mcpassistant-gateway` |
94
-
95
- ---
96
-
97
- <a id="features"></a>
98
-
99
- ## ✨ Features
100
-
101
- Most features are available out-of-the-box in the **TypeScript SDK**:
102
-
103
- - **Storage Backends** - Redis, SQLite, File System, or In-Memory backends
104
- - **Serverless** - Works in serverless environments (Vercel, AWS Lambda, etc.)
105
- - **React Hook** - `useMcp` hook for easy React integration
106
- - **Vue Composable** - `useMcp` composable for Vue applications
107
- - **SSE** - Server-Sent Events for connection state and observability updates
108
- - **MCP Protocol** - Support for tools, prompts, and resources
109
- - **Agent Adapters** - Built-in adapters for AI SDK, LangChain, Mastra, and AG-UI
110
- - **MCP Apps Extension (SEP-1865)** - Interactive UI-driven tool interfaces
111
- - **ToolRouter** - Discover tools on-demand across multiple MCP servers (reduces context bloat)
112
-
113
- <a id="examples"></a>
114
-
115
- ## 🧪 Examples
116
-
117
- Check out working examples demonstrating the MCP Apps extension and agent integrations in the [examples/agents](examples/agents) directory.
118
-
119
- > Examples MCP Apps referred from [modelcontextprotocol/ext-apps](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples)
120
-
121
- <div align="center">
122
- <table cellspacing="5" cellpadding="0">
123
- <tr>
124
- <td width="50%">
125
- <img src="docs/images/mcp-apps-img-1.png" alt="MCP Apps 1" width="100%" />
126
- </td>
127
- <td width="50%">
128
- <img src="docs/images/mcp-apps-img-2.png" alt="MCP Apps 2" width="100%" />
129
- </td>
130
- </tr>
131
- </table>
132
- <p><em>Interactive UIs for MCP tools</em></p>
133
- </div>
134
-
135
- <a id="inspiration"></a>
136
-
137
- ## 💡 Inspiration
138
-
139
- > I got the idea for `@mcp-ts` while working on **[MCP Assistant](https://mcp-assistant.in)**.
140
- As the project grew, I had a few problems: storage, using different AI frameworks like LangGraph and ADK for different use cases, and figuring out how to get progressive SSE updates at each step so I could see what was happening.
141
- So with that idea in mind, I built this SDK to make setup easier and keep the user experience smooth.
142
- That’s how `@mcp-ts` started.
143
-
144
- <br/>
145
-
146
- <div align="center">
147
- <img src="docs/images/mcp-assistant.png" alt="MCP Assistant" width="100%" />
148
- </div>
149
-
150
- <br/>
151
-
152
- <a id="sdk-setup-mcp-tssdk"></a>
153
-
154
- ## 🛠️ SDK Setup (@mcp-ts/sdk)
155
-
156
- ### 📦 Installation
157
-
158
- <a id="installation"></a>
3
+ Core TypeScript SDK for building MCP applications.
159
4
 
160
5
  ```bash
161
6
  npm install @mcp-ts/sdk
162
7
  ```
163
8
 
164
- The SDK supports multiple storage backends out of the box:
165
- - **Memory** (default, no setup required)
166
- - **File** (local persistence)
167
- - **SQLite** (fast local persistence, requires `npm install better-sqlite3`)
168
- - **Redis** (production-ready, requires `npm install ioredis`)
169
-
170
- ### 🚀 Quick Start
171
-
172
- <a id="quick-start"></a>
173
-
174
- Working reference: [examples/next](examples/next)
175
-
176
- <details>
177
- <summary><strong>Server-Side (Next.js)</strong></summary>
178
-
179
- ```typescript
180
- // app/api/mcp/route.ts
181
- import { createNextMcpHandler } from '@mcp-ts/sdk/server';
182
-
183
- export const dynamic = 'force-dynamic';
184
- export const runtime = 'nodejs';
185
-
186
- export const { GET, POST } = createNextMcpHandler({
187
- authenticate: () => {
188
- // your logic here
189
- }
190
- });
191
- ```
192
-
193
- </details>
194
-
195
- <details>
196
- <summary><strong>Client-Side (React)</strong></summary>
197
-
198
- ```typescript
199
- 'use client';
200
-
201
- import { useMcp } from '@mcp-ts/sdk/client/react';
202
-
203
- function App() {
204
- const { connections, connect } = useMcp({
205
- url: '/api/mcp',
206
- userId: 'user-123',
207
- });
208
-
209
- return (
210
- <div className="flex flex-col items-center gap-4">
211
- <button
212
- onClick={() =>
213
- connect({
214
- serverId: 'my-server',
215
- serverName: 'My MCP Server',
216
- serverUrl: 'https://mcp.example.com',
217
- callbackUrl: `${window.location.origin}/callback`,
218
- })
219
- }
220
- >
221
- Connect
222
- </button>
223
- {connections.map((conn) => (
224
- <div key={conn.sessionId}>
225
- <h3>{conn.serverName}</h3>
226
- <p>State: {conn.state}</p>
227
- <p>Tools: {conn.tools.length}</p>
228
- </div>
229
- ))}
230
- </div>
231
- );
232
- }
233
- ```
234
-
235
- </details>
236
-
237
- ### 🌐 MCP Endpoint (Hosted)
238
-
239
- <a id="-mcp-endpoint-hosted"></a>
240
-
241
- #### Documentation MCP
242
-
243
- - **Endpoint**: `https://docs.mcp-assistant.in/mcp`
244
- - Use this endpoint to access `mcp-ts` / toolkit documentation over MCP.
245
-
246
- #### MCP Assistant
247
-
248
- - **Endpoint**: `https://api.mcp-assistant.in/mcp`
249
- - `api.mcp-assistant.in/mcp` is the MCP Assistant server endpoint. It provides access to 100+ MCP servers such as GitHub, Notion, Zapier, and Supabase.
250
- - The MCP Assistant server also exposes meta-tools for dynamic MCP discovery and a `CodeMode` tool that executes programs inside a secure sandbox for programmatic tool calling, workflow execution, and result processing, avoiding expensive LLM tool-calling loops.
251
-
252
- #### Antigravity
253
-
254
- ```json
255
- {
256
- "mcpServers": {
257
- "mcp-assistant": {
258
- "serverUrl": "https://api.mcp-assistant.in/mcp"
259
- }
260
- }
261
- }
262
- ```
263
-
264
- #### VS Code
265
-
266
- ```json
267
- {
268
- "servers": {
269
- "mcp-assistant": {
270
- "type": "http",
271
- "url": "https://api.mcp-assistant.in/mcp"
272
- }
273
- }
274
- }
275
- ```
276
-
277
- ### 🔌 Adapters
278
-
279
- <a id="-adapters"></a>
280
-
281
- Integrating with agent frameworks is simple using built-in adapters.
282
-
283
- <details>
284
- <summary>Vercel AI SDK</summary>
285
-
286
- ```typescript
287
- // app/api/chat/route.ts
288
- import { MultiSessionClient } from '@mcp-ts/sdk/server';
289
- import { AIAdapter } from '@mcp-ts/sdk/adapters/ai';
290
- import { streamText } from 'ai';
291
- import { openai } from '@ai-sdk/openai';
292
-
293
- export async function POST(req: Request) {
294
- const { messages, userId } = await req.json();
295
- const client = new MultiSessionClient(userId);
296
-
297
- try {
298
- await client.connect();
299
- const tools = await AIAdapter.getTools(client);
300
- const result = streamText({
301
- model: openai('gpt-4'),
302
- messages,
303
- tools,
304
- onFinish: async () => {
305
- await client.disconnect();
306
- }
307
- });
308
- return result.toDataStreamResponse();
309
- } catch (error) {
310
- await client.disconnect();
311
- throw error;
312
- }
313
- }
314
- ```
315
-
316
- </details>
317
-
318
- <details>
319
- <summary>Agui Adapter</summary>
320
-
321
- ```typescript
322
- import { MultiSessionClient } from '@mcp-ts/sdk/server';
323
- import { AguiAdapter } from '@mcp-ts/sdk/adapters/agui-adapter';
324
-
325
- const client = new MultiSessionClient("user_123");
326
- await client.connect();
327
-
328
- const adapter = new AguiAdapter(client);
329
- const tools = await adapter.getTools();
330
- ```
331
-
332
- </details>
333
-
334
- <details>
335
- <summary>Mastra Adapter</summary>
336
-
337
- ```typescript
338
- import { MultiSessionClient } from '@mcp-ts/sdk/server';
339
- import { MastraAdapter } from '@mcp-ts/sdk/adapters/mastra-adapter';
340
-
341
- const client = new MultiSessionClient("user_123");
342
- await client.connect();
343
-
344
- const tools = await MastraAdapter.getTools(client);
345
- ```
346
-
347
- </details>
348
-
349
- ### 🧩 AG-UI Middleware
350
-
351
- <a id="-ag-ui-middleware"></a>
352
-
353
- Execute MCP tools server-side when using remote agents (LangGraph, AutoGen, etc.):
354
-
355
- <details>
356
- <summary>View AG-UI (Agent Middleware)</summary>
357
-
358
- ```typescript
359
- import { HttpAgent } from "@ag-ui/client";
360
- import { AguiAdapter } from "@mcp-ts/sdk/adapters/agui-adapter";
361
- import { createMcpMiddleware } from "@mcp-ts/sdk/adapters/agui-middleware";
362
-
363
- // Connect to MCP servers
364
- const { MultiSessionClient } = await import("@mcp-ts/sdk/server");
365
- const client = new MultiSessionClient("user_123");
366
- await client.connect();
367
-
368
- // Create adapter and get tools
369
- const adapter = new AguiAdapter(client);
370
- const mcpTools = await adapter.getTools();
371
-
372
- // Create agent with middleware
373
- const agent = new HttpAgent({ url: "http://localhost:8000/agent" });
374
- agent.use(createMcpMiddleware({
375
- toolPrefix: 'server-',
376
- tools: mcpTools,
377
- }));
378
- ```
379
-
380
- </details>
381
-
382
- The middleware intercepts tool calls from remote agents, executes MCP tools server-side, and returns results back to the agent.
383
-
384
- ### 🛠️ MCP Apps (SEP-1865)
385
-
386
- <a id="mcp-apps-sep-1865"></a>
387
- <a id="-mcp-apps-sep-1865"></a>
388
-
389
- Render interactive UIs for your tools using `McpAppRenderer`.
390
-
391
- <details>
392
- <summary>View MCP Apps</summary>
393
-
394
- ```typescript
395
- import { useRenderToolCall } from "@copilotkit/react-core";
396
- import { McpAppRenderer } from "@mcp-ts/sdk/client/react";
397
- import { useMcpContext } from "./mcp";
398
-
399
- export function ToolRenderer() {
400
- const { mcpClient } = useMcpContext();
401
-
402
- useRenderToolCall({
403
- name: "*",
404
- render: ({ name, args, result, status }) => (
405
- <McpAppRenderer
406
- client={mcpClient}
407
- name={name}
408
- input={args}
409
- result={result}
410
- status={status}
411
- />
412
- ),
413
- });
414
-
415
- return null;
416
- }
417
- ```
418
-
419
- </details>
420
-
421
- <a id="documentation"></a>
422
-
423
- ## 📚 Documentation
424
-
425
- Full documentation is available at: **[Docs](https://docs.mcp-assistant.in/)**
426
-
427
- <a id="topics-covered"></a>
428
- <a id="️-topics-covered"></a>
429
-
430
- ### 🗂️ Topics Covered
431
-
432
- - **[Getting Started](https://docs.mcp-assistant.in/get-started)** - Quick setup and overview
433
- - **[Installation](https://docs.mcp-assistant.in/install)** - Detailed installation guide
434
- - **[Storage Backends](https://docs.mcp-assistant.in/storage-backends/overview)** - Redis, File, SQLite, Supabase, Neon, and Memory options
435
- - **[Next.js Integration](https://docs.mcp-assistant.in/nextjs)** - Complete Next.js examples
436
- - **[React Hook Guide](https://docs.mcp-assistant.in/react)** - Using the useMcp hook
437
- - **[API Reference](https://docs.mcp-assistant.in/reference/server)** - Complete API documentation
438
-
439
- <a id="environment-setup"></a>
440
-
441
- ## ⚙️ Environment Setup
442
-
443
- The library supports multiple storage backends. You can explicitly select one using `MCP_TS_STORAGE_TYPE` or rely on automatic detection.
444
-
445
- **Supported Types:** `redis`, `supabase`, `neon`, `sqlite`, `file`, `memory`.
446
-
447
- <a id="-configuration-examples"></a>
448
-
449
- ### 🧷 Configuration Examples
450
-
451
- 1. **Redis** (Recommended for production)
452
- ```bash
453
- MCP_TS_STORAGE_TYPE=redis
454
- REDIS_URL=redis://localhost:6379
455
- ```
456
-
457
- 2. **SQLite** (Fast & Persistent)
458
- ```bash
459
- MCP_TS_STORAGE_TYPE=sqlite
460
- # Optional path
461
- MCP_TS_STORAGE_SQLITE_PATH=./sessions.db
462
- ```
463
-
464
- 3. **Neon** (Serverless Postgres)
465
- ```bash
466
- MCP_TS_STORAGE_TYPE=neon
467
- NEON_DATABASE_URL=postgresql://user:password@host.neon.tech/dbname?sslmode=verify-full&channel_binding=require
468
- ```
469
-
470
- 4. **File System** (Great for local dev)
471
- ```bash
472
- MCP_TS_STORAGE_TYPE=file
473
- MCP_TS_STORAGE_FILE=./sessions.json
474
- ```
475
-
476
- 5. **In-Memory** (Default for testing)
477
- ```bash
478
- MCP_TS_STORAGE_TYPE=memory
479
- ```
480
-
481
- ---
482
-
483
- <a id="gateway-setup-mcpassistant-gateway"></a>
484
-
485
- ## 🐍 Gateway Setup (mcpassistant-gateway)
486
-
487
- The **MCP Gateway** is a Python-based bridge that allows local MCP servers to be accessed by remote applications via an outbound connection. This is useful for providing local context (like your filesystem) to a hosted AI agent.
488
-
489
- <a id="installation-1"></a>
490
-
491
- ### 📦 Installation
492
-
493
- ```bash
494
- pip install mcpassistant-gateway
495
- ```
496
-
497
- ### 🚀 Usage
498
-
499
- <a id="usage"></a>
500
-
501
- You can run the gateway using `uvx` or `pip`:
502
-
503
- ```bash
504
- # Run the interactive menu
505
- uvx mcpassistant-gateway menu
506
-
507
- # Run the bridge directly
508
- uvx mcpassistant-gateway run --name "local-files"
509
- ```
510
-
511
- ---
512
-
513
- <a id="architecture"></a>
514
-
515
- ## 🏗️ Architecture
516
-
517
- The MCP Toolkit supports two common runtime topologies:
518
-
519
- ```mermaid
520
- graph LR
521
- subgraph Direct["Direct SDK Flow (TypeScript)"]
522
- UI[Browser UI]
523
- Hook[useMcp Hook]
524
- API[Next.js /api/mcp]
525
- Mgr[MultiSessionClient]
526
- Store[(Redis/File/Memory)]
527
- MCP[MCP Servers]
528
-
529
- UI <--> Hook
530
- Hook -- "HTTP RPC" --> API
531
- API --> Mgr
532
- Mgr -- "SSE events" --> Hook
533
- Mgr <--> Store
534
- Mgr <--> MCP
535
- end
536
-
537
- subgraph Bridge["Remote Bridge Flow (Python)"]
538
- direction TB
539
- Spacer[" "]
540
- Agent[mcpassistant-gateway]
541
- Remote[Remote Bridge Server]
542
- LocalMcp[Local MCP Servers]
543
-
544
- Spacer --- Agent
545
- Agent -- "WSS /connect (outbound)" --> Remote
546
- Agent <--> LocalMcp
547
- style Spacer fill:transparent,stroke:transparent,color:transparent
548
- end
549
- ```
550
-
551
- - **Direct SDK flow**: Browser clients use `useMcp` over HTTP + SSE to a server route backed by `MultiSessionClient`.
552
- - **Bridge flow**: `mcpassistant-gateway` keeps an outbound authenticated WebSocket to a remote bridge and forwards tool calls to local MCP servers.
553
- - **Storage**: Session state and connection metadata persist in Redis, File, SQLite, or Memory backends.
554
-
555
- > [!NOTE]
556
- > This package (`@mcp-ts/sdk`) provides a unified MCP client with support for adapters and storage backends such as AI SDK, Mastra, LangChain, and Redis.
557
- > Adapters and storage backends are loaded via **optional peer dependencies** and must be installed independently. This ensures your application only includes the integrations you explicitly choose, keeping bundle size small and avoiding unnecessary dependencies.
558
- > The SDK includes built-in support for **Memory** and **File** storage, while additional backends (such as Redis) and adapters can be added without impacting users who don't need them.
559
-
560
- For more details, refer to the documentation and follow the **installation guide for each adapter or storage backend**.
561
-
562
- - [AI SDK Installation Guide](https://docs.mcp-assistant.in/ai-adapters/ai-sdk)
563
- - [Mastra Installation Guide](https://docs.mcp-assistant.in/ai-adapters/mastra)
564
- - [LangChain Installation Guide](https://docs.mcp-assistant.in/ai-adapters/langchain)
565
- - [Redis Storage Installation Guide](https://docs.mcp-assistant.in/storage-backends/redis)
566
-
567
-
568
- <a id="contributing"></a>
569
-
570
- ## 🤝 Contributing
571
-
572
- Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute.
573
-
574
-
575
- <br />
576
-
577
- <p align="center">
578
- <em>Thanks for visiting @mcp-ts!</em>
579
- </p>
580
-
9
+ See the [main README](https://github.com/zonlabs/mcp-ts) for full documentation, quick start, and architecture details.
@@ -1,9 +1,9 @@
1
- import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-xj3iQIv6.mjs';
2
- import { d as ToolRouter } from '../tool-router-CsKVXbQB.mjs';
3
- import '../types-6SmXege4.mjs';
1
+ import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-C_Ja2TuV.mjs';
2
+ import { d as ToolRouter } from '../tool-router-C1n7OXbl.mjs';
3
+ import '../types-DX71u9gR.mjs';
4
4
  import '@modelcontextprotocol/sdk/types.js';
5
- import '@modelcontextprotocol/sdk/client/auth.js';
6
5
  import '@modelcontextprotocol/sdk/shared/auth.js';
6
+ import '@modelcontextprotocol/sdk/client/auth.js';
7
7
 
8
8
  /**
9
9
  * MCP Adapter for AG-UI Integration
@@ -1,9 +1,9 @@
1
- import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-CB4oDrQX.js';
2
- import { d as ToolRouter } from '../tool-router-C-Mw1_BQ.js';
3
- import '../types-6SmXege4.js';
1
+ import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-CQzymvHl.js';
2
+ import { d as ToolRouter } from '../tool-router-CBIawFnt.js';
3
+ import '../types-DX71u9gR.js';
4
4
  import '@modelcontextprotocol/sdk/types.js';
5
- import '@modelcontextprotocol/sdk/client/auth.js';
6
5
  import '@modelcontextprotocol/sdk/shared/auth.js';
6
+ import '@modelcontextprotocol/sdk/client/auth.js';
7
7
 
8
8
  /**
9
9
  * MCP Adapter for AG-UI Integration
@@ -2,12 +2,12 @@ import { Observable } from 'rxjs';
2
2
  import { Middleware, RunAgentInput, AbstractAgent, BaseEvent } from '@ag-ui/client';
3
3
  export { AbstractAgent, BaseEvent, EventType, Middleware, RunAgentInput, Tool, ToolCallEndEvent } from '@ag-ui/client';
4
4
  import { AguiTool } from './agui-adapter.mjs';
5
- import '../multi-session-client-xj3iQIv6.mjs';
6
- import '../types-6SmXege4.mjs';
5
+ import '../multi-session-client-C_Ja2TuV.mjs';
6
+ import '../types-DX71u9gR.mjs';
7
7
  import '@modelcontextprotocol/sdk/types.js';
8
- import '@modelcontextprotocol/sdk/client/auth.js';
9
8
  import '@modelcontextprotocol/sdk/shared/auth.js';
10
- import '../tool-router-CsKVXbQB.mjs';
9
+ import '@modelcontextprotocol/sdk/client/auth.js';
10
+ import '../tool-router-C1n7OXbl.mjs';
11
11
 
12
12
  /**
13
13
  * AG-UI Middleware for MCP Tool Execution
@@ -2,12 +2,12 @@ import { Observable } from 'rxjs';
2
2
  import { Middleware, RunAgentInput, AbstractAgent, BaseEvent } from '@ag-ui/client';
3
3
  export { AbstractAgent, BaseEvent, EventType, Middleware, RunAgentInput, Tool, ToolCallEndEvent } from '@ag-ui/client';
4
4
  import { AguiTool } from './agui-adapter.js';
5
- import '../multi-session-client-CB4oDrQX.js';
6
- import '../types-6SmXege4.js';
5
+ import '../multi-session-client-CQzymvHl.js';
6
+ import '../types-DX71u9gR.js';
7
7
  import '@modelcontextprotocol/sdk/types.js';
8
- import '@modelcontextprotocol/sdk/client/auth.js';
9
8
  import '@modelcontextprotocol/sdk/shared/auth.js';
10
- import '../tool-router-C-Mw1_BQ.js';
9
+ import '@modelcontextprotocol/sdk/client/auth.js';
10
+ import '../tool-router-CBIawFnt.js';
11
11
 
12
12
  /**
13
13
  * AG-UI Middleware for MCP Tool Execution
@@ -1,10 +1,10 @@
1
- import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-xj3iQIv6.mjs';
1
+ import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-C_Ja2TuV.mjs';
2
2
  import { ToolSet } from 'ai';
3
- import { d as ToolRouter } from '../tool-router-CsKVXbQB.mjs';
4
- import '../types-6SmXege4.mjs';
3
+ import { d as ToolRouter } from '../tool-router-C1n7OXbl.mjs';
4
+ import '../types-DX71u9gR.mjs';
5
5
  import '@modelcontextprotocol/sdk/types.js';
6
- import '@modelcontextprotocol/sdk/client/auth.js';
7
6
  import '@modelcontextprotocol/sdk/shared/auth.js';
7
+ import '@modelcontextprotocol/sdk/client/auth.js';
8
8
 
9
9
  interface AIAdapterOptions {
10
10
  /**
@@ -1,10 +1,10 @@
1
- import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-CB4oDrQX.js';
1
+ import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-CQzymvHl.js';
2
2
  import { ToolSet } from 'ai';
3
- import { d as ToolRouter } from '../tool-router-C-Mw1_BQ.js';
4
- import '../types-6SmXege4.js';
3
+ import { d as ToolRouter } from '../tool-router-CBIawFnt.js';
4
+ import '../types-DX71u9gR.js';
5
5
  import '@modelcontextprotocol/sdk/types.js';
6
- import '@modelcontextprotocol/sdk/client/auth.js';
7
6
  import '@modelcontextprotocol/sdk/shared/auth.js';
7
+ import '@modelcontextprotocol/sdk/client/auth.js';
8
8
 
9
9
  interface AIAdapterOptions {
10
10
  /**