@mcp-ts/sdk 2.5.3 → 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.
- package/README.md +3 -574
- package/dist/adapters/agui-adapter.d.mts +4 -4
- package/dist/adapters/agui-adapter.d.ts +4 -4
- package/dist/adapters/agui-middleware.d.mts +4 -4
- package/dist/adapters/agui-middleware.d.ts +4 -4
- package/dist/adapters/ai-adapter.d.mts +4 -4
- package/dist/adapters/ai-adapter.d.ts +4 -4
- package/dist/adapters/langchain-adapter.d.mts +4 -4
- package/dist/adapters/langchain-adapter.d.ts +4 -4
- package/dist/adapters/mastra-adapter.d.mts +3 -3
- package/dist/adapters/mastra-adapter.d.ts +3 -3
- package/dist/client/index.d.mts +2 -2
- package/dist/client/index.d.ts +2 -2
- package/dist/client/index.js +3 -0
- package/dist/client/index.js.map +1 -1
- package/dist/client/index.mjs +3 -0
- package/dist/client/index.mjs.map +1 -1
- package/dist/client/react.d.mts +10 -18
- package/dist/client/react.d.ts +10 -18
- package/dist/client/react.js +17 -0
- package/dist/client/react.js.map +1 -1
- package/dist/client/react.mjs +17 -0
- package/dist/client/react.mjs.map +1 -1
- package/dist/client/vue.d.mts +4 -4
- package/dist/client/vue.d.ts +4 -4
- package/dist/client/vue.js +3 -0
- package/dist/client/vue.js.map +1 -1
- package/dist/client/vue.mjs +3 -0
- package/dist/client/vue.mjs.map +1 -1
- package/dist/{index-BRZO_JyI.d.mts → index-BrDkbut5.d.ts} +2 -1
- package/dist/{index-C3YGagi2.d.ts → index-DHQvlx4K.d.mts} +2 -1
- package/dist/index.d.mts +5 -5
- package/dist/index.d.ts +5 -5
- package/dist/index.js +1056 -876
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1048 -871
- package/dist/index.mjs.map +1 -1
- package/dist/{multi-session-client-CuacvZaQ.d.ts → multi-session-client-CQzymvHl.d.ts} +183 -227
- package/dist/{multi-session-client-DqzT8Oo7.d.mts → multi-session-client-C_Ja2TuV.d.mts} +183 -227
- package/dist/server/index.d.mts +338 -88
- package/dist/server/index.d.ts +338 -88
- package/dist/server/index.js +1053 -876
- package/dist/server/index.js.map +1 -1
- package/dist/server/index.mjs +1045 -871
- package/dist/server/index.mjs.map +1 -1
- package/dist/shared/index.d.mts +4 -4
- package/dist/shared/index.d.ts +4 -4
- package/dist/shared/index.js.map +1 -1
- package/dist/shared/index.mjs.map +1 -1
- package/dist/{tool-router-B0qpui-V.d.mts → tool-router-C1n7OXbl.d.mts} +1 -1
- package/dist/{tool-router-2qUyZ-cP.d.ts → tool-router-CBIawFnt.d.ts} +1 -1
- package/dist/{types-BkJ_rgzo.d.mts → types-DX71u9gR.d.mts} +11 -5
- package/dist/{types-BkJ_rgzo.d.ts → types-DX71u9gR.d.ts} +11 -5
- package/migrations/neon/20260513010000_install_mcp_sessions.sql +4 -34
- package/migrations/supabase/20260330195700_install_mcp_sessions.sql +5 -62
- package/package.json +2 -1
- package/src/client/core/sse-client.ts +5 -0
- package/src/client/react/use-mcp.ts +27 -28
- package/src/server/handlers/sse-handler.ts +671 -633
- package/src/server/index.ts +2 -1
- package/src/server/mcp/multi-session-client.ts +34 -10
- package/src/server/mcp/oauth-client.ts +197 -205
- package/src/server/mcp/storage-oauth-provider.ts +148 -41
- package/src/server/mcp/tool-policy-gateway.ts +11 -1
- package/src/server/storage/file-backend.ts +25 -21
- package/src/server/storage/index.ts +71 -0
- package/src/server/storage/memory-backend.ts +24 -12
- package/src/server/storage/neon-backend.ts +70 -72
- package/src/server/storage/redis-backend.ts +26 -36
- package/src/server/storage/sqlite-backend.ts +25 -39
- package/src/server/storage/supabase-backend.ts +45 -54
- package/src/server/storage/types.ts +22 -2
- package/src/shared/types.ts +13 -3
package/README.md
CHANGED
|
@@ -1,580 +1,9 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
11
|
-
<p>Every resource is context for your AI</p>
|
|
12
|
-
|
|
13
|
-
<p>
|
|
14
|
-
<a href="https://mcp-assistant.in/">🌐 Website</a>
|
|
15
|
-
|
|
|
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
|
-
|
|
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-
|
|
2
|
-
import { d as ToolRouter } from '../tool-router-
|
|
3
|
-
import '../types-
|
|
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-
|
|
2
|
-
import { d as ToolRouter } from '../tool-router-
|
|
3
|
-
import '../types-
|
|
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-
|
|
6
|
-
import '../types-
|
|
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 '
|
|
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-
|
|
6
|
-
import '../types-
|
|
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 '
|
|
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-
|
|
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-
|
|
4
|
-
import '../types-
|
|
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-
|
|
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-
|
|
4
|
-
import '../types-
|
|
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
|
/**
|