@mcp-ts/sdk 1.0.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/LICENSE +21 -0
- package/README.md +297 -0
- package/dist/adapters/agui-adapter.d.mts +119 -0
- package/dist/adapters/agui-adapter.d.ts +119 -0
- package/dist/adapters/agui-adapter.js +109 -0
- package/dist/adapters/agui-adapter.js.map +1 -0
- package/dist/adapters/agui-adapter.mjs +107 -0
- package/dist/adapters/agui-adapter.mjs.map +1 -0
- package/dist/adapters/agui-middleware.d.mts +171 -0
- package/dist/adapters/agui-middleware.d.ts +171 -0
- package/dist/adapters/agui-middleware.js +429 -0
- package/dist/adapters/agui-middleware.js.map +1 -0
- package/dist/adapters/agui-middleware.mjs +417 -0
- package/dist/adapters/agui-middleware.mjs.map +1 -0
- package/dist/adapters/ai-adapter.d.mts +38 -0
- package/dist/adapters/ai-adapter.d.ts +38 -0
- package/dist/adapters/ai-adapter.js +82 -0
- package/dist/adapters/ai-adapter.js.map +1 -0
- package/dist/adapters/ai-adapter.mjs +80 -0
- package/dist/adapters/ai-adapter.mjs.map +1 -0
- package/dist/adapters/langchain-adapter.d.mts +46 -0
- package/dist/adapters/langchain-adapter.d.ts +46 -0
- package/dist/adapters/langchain-adapter.js +102 -0
- package/dist/adapters/langchain-adapter.js.map +1 -0
- package/dist/adapters/langchain-adapter.mjs +100 -0
- package/dist/adapters/langchain-adapter.mjs.map +1 -0
- package/dist/adapters/mastra-adapter.d.mts +49 -0
- package/dist/adapters/mastra-adapter.d.ts +49 -0
- package/dist/adapters/mastra-adapter.js +95 -0
- package/dist/adapters/mastra-adapter.js.map +1 -0
- package/dist/adapters/mastra-adapter.mjs +93 -0
- package/dist/adapters/mastra-adapter.mjs.map +1 -0
- package/dist/client/index.d.mts +119 -0
- package/dist/client/index.d.ts +119 -0
- package/dist/client/index.js +225 -0
- package/dist/client/index.js.map +1 -0
- package/dist/client/index.mjs +223 -0
- package/dist/client/index.mjs.map +1 -0
- package/dist/client/react.d.mts +151 -0
- package/dist/client/react.d.ts +151 -0
- package/dist/client/react.js +492 -0
- package/dist/client/react.js.map +1 -0
- package/dist/client/react.mjs +489 -0
- package/dist/client/react.mjs.map +1 -0
- package/dist/client/vue.d.mts +157 -0
- package/dist/client/vue.d.ts +157 -0
- package/dist/client/vue.js +474 -0
- package/dist/client/vue.js.map +1 -0
- package/dist/client/vue.mjs +471 -0
- package/dist/client/vue.mjs.map +1 -0
- package/dist/events-BP6WyRNh.d.mts +110 -0
- package/dist/events-BP6WyRNh.d.ts +110 -0
- package/dist/index.d.mts +10 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +2784 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +2723 -0
- package/dist/index.mjs.map +1 -0
- package/dist/multi-session-client-BOFgPypS.d.ts +389 -0
- package/dist/multi-session-client-DMF3ED2O.d.mts +389 -0
- package/dist/server/index.d.mts +269 -0
- package/dist/server/index.d.ts +269 -0
- package/dist/server/index.js +2444 -0
- package/dist/server/index.js.map +1 -0
- package/dist/server/index.mjs +2414 -0
- package/dist/server/index.mjs.map +1 -0
- package/dist/shared/index.d.mts +24 -0
- package/dist/shared/index.d.ts +24 -0
- package/dist/shared/index.js +223 -0
- package/dist/shared/index.js.map +1 -0
- package/dist/shared/index.mjs +190 -0
- package/dist/shared/index.mjs.map +1 -0
- package/dist/types-SbDlA2VX.d.mts +153 -0
- package/dist/types-SbDlA2VX.d.ts +153 -0
- package/dist/utils-0qmYrqoa.d.mts +92 -0
- package/dist/utils-0qmYrqoa.d.ts +92 -0
- package/package.json +165 -0
- package/src/adapters/agui-adapter.ts +210 -0
- package/src/adapters/agui-middleware.ts +512 -0
- package/src/adapters/ai-adapter.ts +115 -0
- package/src/adapters/langchain-adapter.ts +127 -0
- package/src/adapters/mastra-adapter.ts +126 -0
- package/src/client/core/sse-client.ts +340 -0
- package/src/client/index.ts +26 -0
- package/src/client/react/index.ts +10 -0
- package/src/client/react/useMcp.ts +558 -0
- package/src/client/vue/index.ts +10 -0
- package/src/client/vue/useMcp.ts +542 -0
- package/src/index.ts +11 -0
- package/src/server/handlers/nextjs-handler.ts +216 -0
- package/src/server/handlers/sse-handler.ts +699 -0
- package/src/server/index.ts +57 -0
- package/src/server/mcp/multi-session-client.ts +132 -0
- package/src/server/mcp/oauth-client.ts +1168 -0
- package/src/server/mcp/storage-oauth-provider.ts +239 -0
- package/src/server/storage/file-backend.ts +169 -0
- package/src/server/storage/index.ts +115 -0
- package/src/server/storage/memory-backend.ts +132 -0
- package/src/server/storage/redis-backend.ts +210 -0
- package/src/server/storage/redis.ts +160 -0
- package/src/server/storage/types.ts +109 -0
- package/src/shared/constants.ts +29 -0
- package/src/shared/errors.ts +133 -0
- package/src/shared/events.ts +166 -0
- package/src/shared/index.ts +70 -0
- package/src/shared/types.ts +274 -0
- package/src/shared/utils.ts +16 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 MCP Assistant
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<a href="https://github.com/zonlabs/mcp-ts">
|
|
3
|
+
<img src="docs/static/img/logo.svg" alt="mcp-ts Logo" width="80" height="80" />
|
|
4
|
+
</a>
|
|
5
|
+
<h1 align="center">@mcp-ts</h1>
|
|
6
|
+
<p>A Lightweight MCP (Model Context Protocol) client library with integrated persistence.</p>
|
|
7
|
+
</div>
|
|
8
|
+
|
|
9
|
+
<div align="center">
|
|
10
|
+
<a href="https://github.com/zonlabs/mcp-ts/raw/main/docs/static/vid/mcp-ts.mp4">
|
|
11
|
+
<em>Click to watch demo video</em>
|
|
12
|
+
</a>
|
|
13
|
+
</div>
|
|
14
|
+
<br />
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
<div align="center">
|
|
18
|
+
|
|
19
|
+
| *Supported Frameworks* | *Agent Frameworks and Protocol* | *Storage Backends* |
|
|
20
|
+
| :---: | :---: | :---: |
|
|
21
|
+
| <img src="docs/static/img/framework/next.svg" width="35" height="35" /> <img src="docs/static/img/framework/node.svg" width="35" height="35" /> <img src="docs/static/img/framework/react.svg" width="35" height="35" /> <img src="docs/static/img/framework/vue.svg" width="35" height="35" /> <img src="docs/static/img/framework/express.svg" width="35" height="35" /> | <img src="docs/static/img/framework/vercel.svg" width="35" height="35" /> <img src="docs/static/img/agent-framework/langchain.svg" width="35" height="35" /> <img src="docs/static/img/agent-framework/mastra.svg" width="35" height="35" /> <img src="docs/static/img/agent-framework/agui.webp" width="35" height="35" /> | <img src="docs/static/img/storage-backend/redis.svg" width="35" height="35" /> <img src="docs/static/img/storage-backend/filesystem.svg" width="35" height="35" /> <img src="docs/static/img/storage-backend/memory.svg" width="35" height="35" /> |
|
|
22
|
+
|
|
23
|
+
</div>
|
|
24
|
+
|
|
25
|
+
<p align="center">
|
|
26
|
+
<a href="https://www.npmjs.com/package/@mcp-ts/sdk">
|
|
27
|
+
<img src="https://badge.fury.io/js/@mcp-ts%2Fcore.svg" alt="npm version" />
|
|
28
|
+
</a>
|
|
29
|
+
<a href="https://opensource.org/licenses/MIT">
|
|
30
|
+
<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" />
|
|
31
|
+
</a>
|
|
32
|
+
</p>
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
## Features
|
|
37
|
+
|
|
38
|
+
- **Real-Time SSE** - Server-Sent Events for live connection and observability updates
|
|
39
|
+
- **Flexible Storage** - Redis, File System, or In-Memory backends
|
|
40
|
+
- **Serverless-Ready** - Works in serverless environments (Vercel, AWS Lambda, etc.)
|
|
41
|
+
- **React Hook** - `useMcp` hook for easy React integration
|
|
42
|
+
- **Vue Composable** - `useMcp` composable for Vue applications
|
|
43
|
+
- **Full MCP Protocol** - Support for tools, prompts, and resources
|
|
44
|
+
- **TypeScript** - Complete type safety with exported types
|
|
45
|
+
- **Agent Adapters** - Built-in adapters for AI SDK, LangChain, Mastra, and AG-UI
|
|
46
|
+
|
|
47
|
+
## Inspiration
|
|
48
|
+
|
|
49
|
+
> [!NOTE]
|
|
50
|
+
> I got the idea for `@mcp-ts` while working on 🌐 **[MCP Assistant](https://mcp-assistant.in)**.
|
|
51
|
+
While building custom storage for persistence, managing the flow became harder than it should have been.
|
|
52
|
+
So I built this client to handle the heavy lifting of client applications and make agent interactions easier.
|
|
53
|
+
That’s how `@mcp-ts` started.
|
|
54
|
+
|
|
55
|
+
<br/>
|
|
56
|
+
|
|
57
|
+
<div align="center">
|
|
58
|
+
<img src="docs/static/img/mcp-assistant.png" alt="MCP Assistant" width="100%" />
|
|
59
|
+
</div>
|
|
60
|
+
|
|
61
|
+
<br/>
|
|
62
|
+
|
|
63
|
+
## Installation
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npm install @mcp-ts/sdk
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The package supports multiple storage backends out of the box:
|
|
70
|
+
- **Memory** (default, no setup required)
|
|
71
|
+
- **File** (local persistence)
|
|
72
|
+
- **Redis** (production-ready, requires `npm install ioredis`)
|
|
73
|
+
|
|
74
|
+
## Quick Start
|
|
75
|
+
|
|
76
|
+
### Server-Side (Next.js)
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
// app/api/mcp/route.ts
|
|
80
|
+
import { createNextMcpHandler } from '@mcp-ts/sdk/server';
|
|
81
|
+
|
|
82
|
+
export const dynamic = 'force-dynamic';
|
|
83
|
+
export const runtime = 'nodejs';
|
|
84
|
+
|
|
85
|
+
export const { GET, POST } = createNextMcpHandler({
|
|
86
|
+
authenticate: () => {
|
|
87
|
+
// your logic here
|
|
88
|
+
}
|
|
89
|
+
});
|
|
90
|
+
});
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Using with Vercel AI SDK
|
|
94
|
+
|
|
95
|
+
For advanced usage with `ai` SDK (e.g., `streamText`), use `MultiSessionClient` to aggregate tools from multiple servers.
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
// app/api/chat/route.ts
|
|
99
|
+
import { MultiSessionClient } from '@mcp-ts/sdk/server';
|
|
100
|
+
import { AIAdapter } from '@mcp-ts/sdk/adapters/ai';
|
|
101
|
+
import { streamText } from 'ai';
|
|
102
|
+
import { openai } from '@ai-sdk/openai';
|
|
103
|
+
|
|
104
|
+
export async function POST(req: Request) {
|
|
105
|
+
const { messages, identity } = await req.json();
|
|
106
|
+
|
|
107
|
+
const client = new MultiSessionClient(identity);
|
|
108
|
+
|
|
109
|
+
try {
|
|
110
|
+
await client.connect();
|
|
111
|
+
|
|
112
|
+
const tools = await AIAdapter.getTools(client);
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
const result = streamText({
|
|
116
|
+
model: openai('gpt-4'),
|
|
117
|
+
messages,
|
|
118
|
+
tools,
|
|
119
|
+
onFinish: async () => {
|
|
120
|
+
await mcp.disconnect();
|
|
121
|
+
}
|
|
122
|
+
});
|
|
123
|
+
|
|
124
|
+
return result.toDataStreamResponse();
|
|
125
|
+
} catch (error) {
|
|
126
|
+
await mcp.disconnect();
|
|
127
|
+
throw error;
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Client-Side (React)
|
|
133
|
+
|
|
134
|
+
```typescript
|
|
135
|
+
'use client';
|
|
136
|
+
import { useMcp } from '@mcp-ts/sdk/client';
|
|
137
|
+
|
|
138
|
+
function App() {
|
|
139
|
+
const { connections, connect, status } = useMcp({
|
|
140
|
+
url: '/api/mcp',
|
|
141
|
+
identity: 'user-123',
|
|
142
|
+
});
|
|
143
|
+
|
|
144
|
+
return (
|
|
145
|
+
<div>
|
|
146
|
+
<p>Status: {status}</p>
|
|
147
|
+
<button onClick={() => connect({
|
|
148
|
+
serverId: 'my-server',
|
|
149
|
+
serverName: 'My MCP Server',
|
|
150
|
+
serverUrl: 'https://mcp.example.com',
|
|
151
|
+
callbackUrl: window.location.origin + '/callback',
|
|
152
|
+
})}>
|
|
153
|
+
Connect
|
|
154
|
+
</button>
|
|
155
|
+
|
|
156
|
+
{connections.map(conn => (
|
|
157
|
+
<div key={conn.sessionId}>
|
|
158
|
+
<h3>{conn.serverName}</h3>
|
|
159
|
+
<p>State: {conn.state}</p>
|
|
160
|
+
<p>Tools: {conn.tools.length}</p>
|
|
161
|
+
</div>
|
|
162
|
+
))}
|
|
163
|
+
</div>
|
|
164
|
+
);
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### <img src="docs/static/img/agent-framework/agui.webp" width="20" height="20" align="center" /> AG-UI Middleware
|
|
169
|
+
|
|
170
|
+
Execute MCP tools server-side when using remote agents (LangGraph, AutoGen, etc.):
|
|
171
|
+
|
|
172
|
+
```typescript
|
|
173
|
+
import { HttpAgent } from "@ag-ui/client";
|
|
174
|
+
import { AguiAdapter } from "@mcp-ts/sdk/adapters/agui-adapter";
|
|
175
|
+
import { createMcpMiddleware } from "@mcp-ts/sdk/adapters/agui-middleware";
|
|
176
|
+
|
|
177
|
+
// Connect to MCP servers
|
|
178
|
+
const { MultiSessionClient } = await import("@mcp-ts/sdk/server");
|
|
179
|
+
const client = new MultiSessionClient("user_123");
|
|
180
|
+
await client.connect();
|
|
181
|
+
|
|
182
|
+
// Create adapter and get tools
|
|
183
|
+
const adapter = new AguiAdapter(client);
|
|
184
|
+
const mcpTools = await adapter.getTools();
|
|
185
|
+
|
|
186
|
+
// Create agent with middleware
|
|
187
|
+
const agent = new HttpAgent({ url: "http://localhost:8000/agent" });
|
|
188
|
+
agent.use(createMcpMiddleware(client, {
|
|
189
|
+
toolPrefix: 'server-',
|
|
190
|
+
tools: mcpTools,
|
|
191
|
+
}));
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
The middleware intercepts tool calls from remote agents, executes MCP tools server-side, and returns results back to the agent.
|
|
195
|
+
|
|
196
|
+
## Documentation
|
|
197
|
+
|
|
198
|
+
Full documentation is available at: **[Docs](https://zonlabs.github.io/mcp-ts/)**
|
|
199
|
+
|
|
200
|
+
### Topics Covered:
|
|
201
|
+
|
|
202
|
+
- **[Getting Started](https://zonlabs.github.io/mcp-ts/docs/)** - Quick setup and overview
|
|
203
|
+
- **[Installation](https://zonlabs.github.io/mcp-ts/docs/installation)** - Detailed installation guide
|
|
204
|
+
- **[Storage Backends](https://zonlabs.github.io/mcp-ts/docs/storage-backends)** - Redis, File, Memory options
|
|
205
|
+
- **[Next.js Integration](https://zonlabs.github.io/mcp-ts/docs/nextjs)** - Complete Next.js examples
|
|
206
|
+
- **[React Hook Guide](https://zonlabs.github.io/mcp-ts/docs/react-hook)** - Using the useMcp hook
|
|
207
|
+
- **[API Reference](https://zonlabs.github.io/mcp-ts/docs/api-reference)** - Complete API documentation
|
|
208
|
+
|
|
209
|
+
## Environment Setup
|
|
210
|
+
|
|
211
|
+
The library supports multiple storage backends. You can explicitly select one using `MCP_TS_STORAGE_TYPE` or rely on automatic detection.
|
|
212
|
+
|
|
213
|
+
**Supported Types:** `redis`, `file`, `memory`.
|
|
214
|
+
|
|
215
|
+
### Configuration Examples
|
|
216
|
+
|
|
217
|
+
1. **<img src="docs/static/img/storage-backend/redis.svg" width="20" height="20" align="center" /> Redis** (Recommended for production)
|
|
218
|
+
```bash
|
|
219
|
+
MCP_TS_STORAGE_TYPE=redis
|
|
220
|
+
REDIS_URL=redis://localhost:6379
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
2. **<img src="docs/static/img/storage-backend/filesystem.svg" width="20" height="20" align="center" /> File System** (Great for local dev)
|
|
224
|
+
```bash
|
|
225
|
+
MCP_TS_STORAGE_TYPE=file
|
|
226
|
+
MCP_TS_STORAGE_FILE=./sessions.json
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
3. **<img src="docs/static/img/storage-backend/memory.svg" width="20" height="20" align="center" /> In-Memory** (Default for testing)
|
|
230
|
+
```bash
|
|
231
|
+
MCP_TS_STORAGE_TYPE=memory
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
## Architecture
|
|
235
|
+
|
|
236
|
+
This package uses **Server-Sent Events (SSE)** instead of WebSockets:
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
```mermaid
|
|
240
|
+
graph TD
|
|
241
|
+
subgraph Client ["Browser (React)"]
|
|
242
|
+
UI[UI Components]
|
|
243
|
+
Hook[useMcp Hook]
|
|
244
|
+
UI <--> Hook
|
|
245
|
+
end
|
|
246
|
+
|
|
247
|
+
subgraph Server ["Next.js Server (Node.js)"]
|
|
248
|
+
API[API Route /api/mcp]
|
|
249
|
+
SSE[SSE Handler]
|
|
250
|
+
ClientMgr[MCP Client Manager]
|
|
251
|
+
|
|
252
|
+
API <--> ClientMgr
|
|
253
|
+
ClientMgr --> SSE
|
|
254
|
+
end
|
|
255
|
+
|
|
256
|
+
subgraph Infrastructure
|
|
257
|
+
Redis[(Redis Session Store)]
|
|
258
|
+
end
|
|
259
|
+
|
|
260
|
+
subgraph External ["External MCP Servers"]
|
|
261
|
+
TargetServer[Target MCP Server]
|
|
262
|
+
end
|
|
263
|
+
|
|
264
|
+
Hook -- "HTTP POST (RPC)" --> API
|
|
265
|
+
SSE -- "Server-Sent Events" --> Hook
|
|
266
|
+
ClientMgr -- "Persist State" <--> Redis
|
|
267
|
+
ClientMgr -- "MCP Protocol" <--> TargetServer
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
- **Browser**: React application using the `useMcp` hook for state management.
|
|
271
|
+
- **Next.js Server**: Acts as a bridge, maintaining connections to external MCP servers.
|
|
272
|
+
- **Storage**: Persists session state, OAuth tokens, and connection details (Redis, File, or Memory).
|
|
273
|
+
- **SSE**: Delivers real-time updates (logs, tool list changes) to the client.
|
|
274
|
+
|
|
275
|
+
> [!NOTE]
|
|
276
|
+
> 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.
|
|
277
|
+
> 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.
|
|
278
|
+
> 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.
|
|
279
|
+
|
|
280
|
+
For more details, refer to the documentation and follow the **installation guide for each adapter or storage backend**.
|
|
281
|
+
|
|
282
|
+
- [AI SDK Installation Guide](https://zonlabs.github.io/mcp-ts/docs/adapters#installation)
|
|
283
|
+
- [Mastra Installation Guide](https://zonlabs.github.io/mcp-ts/docs/adapters#installation)
|
|
284
|
+
- [LangChain Installation Guide](https://zonlabs.github.io/mcp-ts/docs/adapters#installation)
|
|
285
|
+
- [Redis Storage Installation Guide](https://zonlabs.github.io/mcp-ts/docs/storage-backends#-redis-production)
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
## Contributing
|
|
289
|
+
|
|
290
|
+
Contributions are welcome! Please read [CLAUDE.md](./CLAUDE.md) for development guidelines.
|
|
291
|
+
|
|
292
|
+
## License
|
|
293
|
+
|
|
294
|
+
MIT © MCP Assistant
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-DMF3ED2O.mjs';
|
|
2
|
+
import '../events-BP6WyRNh.mjs';
|
|
3
|
+
import '@modelcontextprotocol/sdk/types.js';
|
|
4
|
+
import '@modelcontextprotocol/sdk/shared/auth.js';
|
|
5
|
+
import '@modelcontextprotocol/sdk/client/auth.js';
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* MCP Adapter for AG-UI Integration
|
|
9
|
+
*
|
|
10
|
+
* This adapter transforms MCP tools into formats compatible with AG-UI agents.
|
|
11
|
+
* It provides tools with handlers for server-side execution and tool definitions
|
|
12
|
+
* in JSON Schema format for passing to remote agents.
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* ```typescript
|
|
16
|
+
* import { MultiSessionClient } from '@mcp-ts/sdk/server';
|
|
17
|
+
* import { AguiAdapter } from '@mcp-ts/sdk/adapters/mcp-adapter';
|
|
18
|
+
* import { createMcpMiddleware } from '@mcp-ts/sdk/adapters/agui-middleware';
|
|
19
|
+
* import { HttpAgent } from '@ag-ui/client';
|
|
20
|
+
*
|
|
21
|
+
* // Create MCP client
|
|
22
|
+
* const mcpClient = new MultiSessionClient('user_123');
|
|
23
|
+
* await mcpClient.connect();
|
|
24
|
+
*
|
|
25
|
+
* // Create adapter and get tools
|
|
26
|
+
* const adapter = new AguiAdapter(mcpClient);
|
|
27
|
+
* const tools = await adapter.getTools();
|
|
28
|
+
*
|
|
29
|
+
* // Use with AG-UI middleware
|
|
30
|
+
* const agent = new HttpAgent({ url: 'http://localhost:8000/agent' });
|
|
31
|
+
* agent.use(createMcpMiddleware(mcpClient, { tools }));
|
|
32
|
+
* ```
|
|
33
|
+
*/
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Configuration options for AguiAdapter
|
|
37
|
+
*/
|
|
38
|
+
interface AguiAdapterOptions {
|
|
39
|
+
/**
|
|
40
|
+
* Prefix for tool names to avoid collision with other tools.
|
|
41
|
+
* @default serverId or 'mcp'
|
|
42
|
+
*/
|
|
43
|
+
prefix?: string;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* AG-UI Tool with handler for server-side execution.
|
|
47
|
+
*
|
|
48
|
+
* Tools contain:
|
|
49
|
+
* - `name`: Unique identifier (prefixed with server ID)
|
|
50
|
+
* - `description`: Human-readable description for the LLM
|
|
51
|
+
* - `parameters`: JSON Schema defining the input format
|
|
52
|
+
* - `handler`: Function that executes the tool via MCP client
|
|
53
|
+
*/
|
|
54
|
+
interface AguiTool {
|
|
55
|
+
/** Unique tool name (e.g., "server-abc_get_weather") */
|
|
56
|
+
name: string;
|
|
57
|
+
/** Human-readable description for the LLM */
|
|
58
|
+
description: string;
|
|
59
|
+
/** JSON Schema format parameters */
|
|
60
|
+
parameters?: Record<string, any>;
|
|
61
|
+
/** Handler function that executes the MCP tool */
|
|
62
|
+
handler?: (args: any) => any | Promise<any>;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Tool definition format for passing to remote agents (without handler).
|
|
66
|
+
* Compatible with OpenAI's function calling API.
|
|
67
|
+
*/
|
|
68
|
+
interface AguiToolDefinition {
|
|
69
|
+
/** Tool name (e.g., "server-abc_get_weather") */
|
|
70
|
+
name: string;
|
|
71
|
+
/** Human-readable description */
|
|
72
|
+
description: string;
|
|
73
|
+
/** JSON Schema format parameters */
|
|
74
|
+
parameters: Record<string, any>;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Adapter that transforms MCP tools into AG-UI compatible formats.
|
|
78
|
+
*
|
|
79
|
+
* This adapter provides two main outputs:
|
|
80
|
+
* - `getTools()`: Returns tools with handlers for server-side execution
|
|
81
|
+
* - `getToolDefinitions()`: Returns tool definitions in JSON Schema format for remote agents
|
|
82
|
+
*/
|
|
83
|
+
declare class AguiAdapter {
|
|
84
|
+
private client;
|
|
85
|
+
private options;
|
|
86
|
+
constructor(client: MCPClient | MultiSessionClient, options?: AguiAdapterOptions);
|
|
87
|
+
/**
|
|
88
|
+
* Get tools with handlers for MCP tool execution.
|
|
89
|
+
*
|
|
90
|
+
* Each tool includes a handler function that:
|
|
91
|
+
* 1. Calls the MCP tool via the client
|
|
92
|
+
* 2. Extracts text content from the result
|
|
93
|
+
* 3. Returns the result as a string or JSON
|
|
94
|
+
*
|
|
95
|
+
* @returns Array of AguiTool objects
|
|
96
|
+
*/
|
|
97
|
+
getTools(): Promise<AguiTool[]>;
|
|
98
|
+
private transformTools;
|
|
99
|
+
/**
|
|
100
|
+
* Get tools as a function (for dynamic loading).
|
|
101
|
+
*
|
|
102
|
+
* @returns Function that returns a Promise of tools
|
|
103
|
+
*/
|
|
104
|
+
getToolsFunction(): () => Promise<AguiTool[]>;
|
|
105
|
+
/**
|
|
106
|
+
* Get tool definitions in JSON Schema format for passing to remote agents.
|
|
107
|
+
*
|
|
108
|
+
* This format is compatible with:
|
|
109
|
+
* - OpenAI's function calling API
|
|
110
|
+
* - AG-UI input.tools format
|
|
111
|
+
* - Most LLM tool/function calling implementations
|
|
112
|
+
*
|
|
113
|
+
* @returns Array of AguiToolDefinition objects
|
|
114
|
+
*/
|
|
115
|
+
getToolDefinitions(): Promise<AguiToolDefinition[]>;
|
|
116
|
+
private transformToolDefinitions;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
export { AguiAdapter, type AguiAdapterOptions, type AguiTool, type AguiToolDefinition };
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-BOFgPypS.js';
|
|
2
|
+
import '../events-BP6WyRNh.js';
|
|
3
|
+
import '@modelcontextprotocol/sdk/types.js';
|
|
4
|
+
import '@modelcontextprotocol/sdk/shared/auth.js';
|
|
5
|
+
import '@modelcontextprotocol/sdk/client/auth.js';
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* MCP Adapter for AG-UI Integration
|
|
9
|
+
*
|
|
10
|
+
* This adapter transforms MCP tools into formats compatible with AG-UI agents.
|
|
11
|
+
* It provides tools with handlers for server-side execution and tool definitions
|
|
12
|
+
* in JSON Schema format for passing to remote agents.
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* ```typescript
|
|
16
|
+
* import { MultiSessionClient } from '@mcp-ts/sdk/server';
|
|
17
|
+
* import { AguiAdapter } from '@mcp-ts/sdk/adapters/mcp-adapter';
|
|
18
|
+
* import { createMcpMiddleware } from '@mcp-ts/sdk/adapters/agui-middleware';
|
|
19
|
+
* import { HttpAgent } from '@ag-ui/client';
|
|
20
|
+
*
|
|
21
|
+
* // Create MCP client
|
|
22
|
+
* const mcpClient = new MultiSessionClient('user_123');
|
|
23
|
+
* await mcpClient.connect();
|
|
24
|
+
*
|
|
25
|
+
* // Create adapter and get tools
|
|
26
|
+
* const adapter = new AguiAdapter(mcpClient);
|
|
27
|
+
* const tools = await adapter.getTools();
|
|
28
|
+
*
|
|
29
|
+
* // Use with AG-UI middleware
|
|
30
|
+
* const agent = new HttpAgent({ url: 'http://localhost:8000/agent' });
|
|
31
|
+
* agent.use(createMcpMiddleware(mcpClient, { tools }));
|
|
32
|
+
* ```
|
|
33
|
+
*/
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Configuration options for AguiAdapter
|
|
37
|
+
*/
|
|
38
|
+
interface AguiAdapterOptions {
|
|
39
|
+
/**
|
|
40
|
+
* Prefix for tool names to avoid collision with other tools.
|
|
41
|
+
* @default serverId or 'mcp'
|
|
42
|
+
*/
|
|
43
|
+
prefix?: string;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* AG-UI Tool with handler for server-side execution.
|
|
47
|
+
*
|
|
48
|
+
* Tools contain:
|
|
49
|
+
* - `name`: Unique identifier (prefixed with server ID)
|
|
50
|
+
* - `description`: Human-readable description for the LLM
|
|
51
|
+
* - `parameters`: JSON Schema defining the input format
|
|
52
|
+
* - `handler`: Function that executes the tool via MCP client
|
|
53
|
+
*/
|
|
54
|
+
interface AguiTool {
|
|
55
|
+
/** Unique tool name (e.g., "server-abc_get_weather") */
|
|
56
|
+
name: string;
|
|
57
|
+
/** Human-readable description for the LLM */
|
|
58
|
+
description: string;
|
|
59
|
+
/** JSON Schema format parameters */
|
|
60
|
+
parameters?: Record<string, any>;
|
|
61
|
+
/** Handler function that executes the MCP tool */
|
|
62
|
+
handler?: (args: any) => any | Promise<any>;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Tool definition format for passing to remote agents (without handler).
|
|
66
|
+
* Compatible with OpenAI's function calling API.
|
|
67
|
+
*/
|
|
68
|
+
interface AguiToolDefinition {
|
|
69
|
+
/** Tool name (e.g., "server-abc_get_weather") */
|
|
70
|
+
name: string;
|
|
71
|
+
/** Human-readable description */
|
|
72
|
+
description: string;
|
|
73
|
+
/** JSON Schema format parameters */
|
|
74
|
+
parameters: Record<string, any>;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Adapter that transforms MCP tools into AG-UI compatible formats.
|
|
78
|
+
*
|
|
79
|
+
* This adapter provides two main outputs:
|
|
80
|
+
* - `getTools()`: Returns tools with handlers for server-side execution
|
|
81
|
+
* - `getToolDefinitions()`: Returns tool definitions in JSON Schema format for remote agents
|
|
82
|
+
*/
|
|
83
|
+
declare class AguiAdapter {
|
|
84
|
+
private client;
|
|
85
|
+
private options;
|
|
86
|
+
constructor(client: MCPClient | MultiSessionClient, options?: AguiAdapterOptions);
|
|
87
|
+
/**
|
|
88
|
+
* Get tools with handlers for MCP tool execution.
|
|
89
|
+
*
|
|
90
|
+
* Each tool includes a handler function that:
|
|
91
|
+
* 1. Calls the MCP tool via the client
|
|
92
|
+
* 2. Extracts text content from the result
|
|
93
|
+
* 3. Returns the result as a string or JSON
|
|
94
|
+
*
|
|
95
|
+
* @returns Array of AguiTool objects
|
|
96
|
+
*/
|
|
97
|
+
getTools(): Promise<AguiTool[]>;
|
|
98
|
+
private transformTools;
|
|
99
|
+
/**
|
|
100
|
+
* Get tools as a function (for dynamic loading).
|
|
101
|
+
*
|
|
102
|
+
* @returns Function that returns a Promise of tools
|
|
103
|
+
*/
|
|
104
|
+
getToolsFunction(): () => Promise<AguiTool[]>;
|
|
105
|
+
/**
|
|
106
|
+
* Get tool definitions in JSON Schema format for passing to remote agents.
|
|
107
|
+
*
|
|
108
|
+
* This format is compatible with:
|
|
109
|
+
* - OpenAI's function calling API
|
|
110
|
+
* - AG-UI input.tools format
|
|
111
|
+
* - Most LLM tool/function calling implementations
|
|
112
|
+
*
|
|
113
|
+
* @returns Array of AguiToolDefinition objects
|
|
114
|
+
*/
|
|
115
|
+
getToolDefinitions(): Promise<AguiToolDefinition[]>;
|
|
116
|
+
private transformToolDefinitions;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
export { AguiAdapter, type AguiAdapterOptions, type AguiTool, type AguiToolDefinition };
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// src/adapters/agui-adapter.ts
|
|
4
|
+
var AguiAdapter = class {
|
|
5
|
+
constructor(client, options = {}) {
|
|
6
|
+
this.client = client;
|
|
7
|
+
this.options = options;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Get tools with handlers for MCP tool execution.
|
|
11
|
+
*
|
|
12
|
+
* Each tool includes a handler function that:
|
|
13
|
+
* 1. Calls the MCP tool via the client
|
|
14
|
+
* 2. Extracts text content from the result
|
|
15
|
+
* 3. Returns the result as a string or JSON
|
|
16
|
+
*
|
|
17
|
+
* @returns Array of AguiTool objects
|
|
18
|
+
*/
|
|
19
|
+
async getTools() {
|
|
20
|
+
const isMultiSession = typeof this.client.getClients === "function";
|
|
21
|
+
if (isMultiSession) {
|
|
22
|
+
const clients = this.client.getClients();
|
|
23
|
+
const allTools = [];
|
|
24
|
+
for (const client of clients) {
|
|
25
|
+
const tools = await this.transformTools(client);
|
|
26
|
+
allTools.push(...tools);
|
|
27
|
+
}
|
|
28
|
+
return allTools;
|
|
29
|
+
}
|
|
30
|
+
return this.transformTools(this.client);
|
|
31
|
+
}
|
|
32
|
+
async transformTools(client) {
|
|
33
|
+
if (!client.isConnected()) {
|
|
34
|
+
return [];
|
|
35
|
+
}
|
|
36
|
+
const result = await client.listTools();
|
|
37
|
+
const prefix = this.options.prefix ?? client.getServerId() ?? "mcp";
|
|
38
|
+
const tools = [];
|
|
39
|
+
for (const tool of result.tools) {
|
|
40
|
+
const toolName = `${prefix}_${tool.name}`;
|
|
41
|
+
tools.push({
|
|
42
|
+
name: toolName,
|
|
43
|
+
description: tool.description || `Execute ${tool.name}`,
|
|
44
|
+
parameters: tool.inputSchema || { type: "object", properties: {} },
|
|
45
|
+
handler: async (args) => {
|
|
46
|
+
console.log(`[AguiAdapter] Executing MCP tool: ${tool.name}`, args);
|
|
47
|
+
const result2 = await client.callTool(tool.name, args);
|
|
48
|
+
if (result2.content && Array.isArray(result2.content)) {
|
|
49
|
+
const textContent = result2.content.filter((c) => c.type === "text").map((c) => c.text).join("\n");
|
|
50
|
+
return textContent || result2;
|
|
51
|
+
}
|
|
52
|
+
return result2;
|
|
53
|
+
}
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
return tools;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Get tools as a function (for dynamic loading).
|
|
60
|
+
*
|
|
61
|
+
* @returns Function that returns a Promise of tools
|
|
62
|
+
*/
|
|
63
|
+
getToolsFunction() {
|
|
64
|
+
return async () => this.getTools();
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Get tool definitions in JSON Schema format for passing to remote agents.
|
|
68
|
+
*
|
|
69
|
+
* This format is compatible with:
|
|
70
|
+
* - OpenAI's function calling API
|
|
71
|
+
* - AG-UI input.tools format
|
|
72
|
+
* - Most LLM tool/function calling implementations
|
|
73
|
+
*
|
|
74
|
+
* @returns Array of AguiToolDefinition objects
|
|
75
|
+
*/
|
|
76
|
+
async getToolDefinitions() {
|
|
77
|
+
const isMultiSession = typeof this.client.getClients === "function";
|
|
78
|
+
if (isMultiSession) {
|
|
79
|
+
const clients = this.client.getClients();
|
|
80
|
+
const allTools = [];
|
|
81
|
+
for (const client of clients) {
|
|
82
|
+
const tools = await this.transformToolDefinitions(client);
|
|
83
|
+
allTools.push(...tools);
|
|
84
|
+
}
|
|
85
|
+
return allTools;
|
|
86
|
+
}
|
|
87
|
+
return this.transformToolDefinitions(this.client);
|
|
88
|
+
}
|
|
89
|
+
async transformToolDefinitions(client) {
|
|
90
|
+
if (!client.isConnected()) {
|
|
91
|
+
return [];
|
|
92
|
+
}
|
|
93
|
+
const result = await client.listTools();
|
|
94
|
+
const prefix = this.options.prefix ?? client.getServerId() ?? "mcp";
|
|
95
|
+
const tools = [];
|
|
96
|
+
for (const tool of result.tools) {
|
|
97
|
+
tools.push({
|
|
98
|
+
name: `${prefix}_${tool.name}`,
|
|
99
|
+
description: tool.description || `Execute ${tool.name}`,
|
|
100
|
+
parameters: tool.inputSchema || { type: "object", properties: {} }
|
|
101
|
+
});
|
|
102
|
+
}
|
|
103
|
+
return tools;
|
|
104
|
+
}
|
|
105
|
+
};
|
|
106
|
+
|
|
107
|
+
exports.AguiAdapter = AguiAdapter;
|
|
108
|
+
//# sourceMappingURL=agui-adapter.js.map
|
|
109
|
+
//# sourceMappingURL=agui-adapter.js.map
|