@mcp-ts/sdk 2.3.3 → 2.4.0

package/README.md

@@ -31,45 +31,79 @@
 
 <br />
 
-## 📖 Table of Contents
-
-- [✨ Features](#-features)
-- [📦 Packages](#-packages)
-- [🛠️ SDK Setup (@mcp-ts/sdk)](#️-sdk-setup-mcp-tssdk)
-  - [📦 Installation](#-installation)
-  - [🚀 Quick Start](#-quick-start)
-- [🐍 Gateway Setup (mcpassistant-gateway)](#-gateway-setup-mcpassistant-gateway)
-  - [📦 Installation](#-installation-1)
-  - [🚀 Usage](#-usage)
-- [🏗️ Architecture](#️-architecture)
-- [📚 Documentation](#-documentation)
-- [⚙️ Environment Setup](#️-environment-setup)
-- [🧪 Examples](#-examples)
-- [💡 Inspiration](#-inspiration)
+## Why does `mcp-ts or toolkit` even exist?
+
+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()`.
+
+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).
+
+`mcp-ts/toolkit` 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).
+
+It gives you a practical foundation for building MCP-native apps:
+
+- Have multiple users using your application
+- Already using AI SDK, LangChain, Mastra, and AG-UI Protocol where handling oauth, tokens management for mcp clients seems overhead
+- Reduce large model context with on-demand tool discovery through `ToolRouter`
+- Render interactive MCP Apps in your application.
+- Run programmatic tool calling inside a secure sandbox with `CodeMode`
+
+In short: the official MCP SDK gives you the protocol building blocks. `mcp-ts/toolkit` gives you the application layer for building MCP applications around them.
+
+### When you may not need it
+
+If you already use a managed service/platform such as Smithery, Strata, Composio, or a similar SDK, you may not need `mcp-ts/toolkit`.
+
+---
+
+## 📑 Table of Contents
+
+- [Features](#features)
+- [Packages](#packages)
+- [SDK Setup (@mcp-ts/sdk)](#sdk-setup-mcp-tssdk)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start)
+- [Gateway Setup (mcpassistant-gateway)](#gateway-setup-mcpassistant-gateway)
+  - [Installation](#installation-1)
+  - [Usage](#usage)
+- [Documentation](#documentation)
+- [Environment Setup](#environment-setup)
+- [Architecture](#architecture)
+- [Examples](#examples)
+- [Inspiration](#inspiration)
+- [Contributing](#contributing)
 
 ---
 
+<a id="packages"></a>
+
 ## 📦 Packages
 
 | Package | Description | Install |
 | :--- | :--- | :--- |
-| **[@mcp-ts/sdk](src)** | TypeScript/JavaScript SDK for clients & servers. | `npm i @mcp-ts/sdk` |
-| **[mcpassistant-gateway](packages/mcp-local-agent)** | Python bridge for local MCP support in remote apps. | `pip install mcpassistant-gateway` |
+| **[@mcp-ts/sdk](src)** | Core TypeScript/JavaScript SDK for client applications. | `npm i @mcp-ts/sdk` |
+| **[@mcp-ts/tool-router](packages/tool-router)** | ToolRouter for dynamic tool discovery across many MCP servers. | `npm i @mcp-ts/tool-router` |
+| **[@mcp-ts/codemode](packages/code-mode)** | CodeMode: sandboxed program execution for tool calling. | `npm i @mcp-ts/codemode` |
+| **[mcpassistant-gateway](packages/local-gateway)** | Python bridge for local MCP support in remote apps. | `pip install mcpassistant-gateway` |
 
 ---
 
+<a id="features"></a>
+
 ## ✨ Features
 
 Most features are available out-of-the-box in the **TypeScript SDK**:
 
-- **SSE** - Server-Sent Events for connection state and observability updates
-- **Flexible Storage** - Redis, SQLite, File System, or In-Memory backends
+- **Storage Backends** - Redis, SQLite, File System, or In-Memory backends
 - **Serverless** - Works in serverless environments (Vercel, AWS Lambda, etc.)
 - **React Hook** - `useMcp` hook for easy React integration
 - **Vue Composable** - `useMcp` composable for Vue applications
+- **SSE** - Server-Sent Events for connection state and observability updates
 - **MCP Protocol** - Support for tools, prompts, and resources
 - **Agent Adapters** - Built-in adapters for AI SDK, LangChain, Mastra, and AG-UI
 - **MCP Apps Extension (SEP-1865)** - Interactive UI-driven tool interfaces
+- **ToolRouter** - Discover tools on-demand across multiple MCP servers (reduces context bloat)
+
+<a id="examples"></a>
 
 ## 🧪 Examples
 
@@ -91,9 +125,11 @@ Check out working examples demonstrating the MCP Apps extension and agent integr
   <p><em>Interactive UIs for MCP tools</em></p>
 </div>
 
+<a id="inspiration"></a>
+
 ## 💡 Inspiration
 
-> I got the idea for `@mcp-ts` while working on 🌐 **[MCP Assistant](https://mcp-assistant.in)**.
+> I got the idea for `@mcp-ts` while working on **[MCP Assistant](https://mcp-assistant.in)**.
 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.
 So with that idea in mind, I built this SDK to make setup easier and keep the user experience smooth.
 That’s how `@mcp-ts` started.
@@ -106,6 +142,8 @@ That’s how `@mcp-ts` started.
 
 <br/>
 
+<a id="sdk-setup-mcp-tssdk"></a>
+
 ## 🛠️ SDK Setup (@mcp-ts/sdk)
 
 ### 📦 Installation
@@ -122,7 +160,10 @@ The SDK supports multiple storage backends out of the box:
 
 ### 🚀 Quick Start
 
-#### 🖥️ Server-Side (Next.js)
+Working reference: [examples/next](examples/next)
+
+<details>
+<summary><strong>Server-Side (Next.js)</strong></summary>
 
 ```typescript
 // app/api/mcp/route.ts
@@ -138,7 +179,10 @@ export const { GET, POST } = createNextMcpHandler({
 });
 ```
 
-### 🎯 Client-Side (React)
+</details>
+
+<details>
+<summary><strong>Client-Side (React)</strong></summary>
 
 ```typescript
 'use client';
@@ -177,6 +221,36 @@ function App() {
 }
 ```
 
+</details>
+
+### 🌐 MCP Endpoint (Hosted)
+
+- **Endpoint**: `https://api.mcp-assistant.in/mcp`
+
+#### Antigravity
+
+```json
+{
+  "mcpServers": {
+    "mcp-assistant": {
+      "url": "https://api.mcp-assistant.in/mcp"
+    }
+  }
+}
+```
+
+#### VS Code
+
+```json
+{
+  "mcpServers": {
+    "mcp-assistant": {
+      "url": "https://api.mcp-assistant.in/mcp"
+    }
+  }
+}
+```
+
 ### 🔌 Adapters
 
 Integrating with agent frameworks is simple using built-in adapters.
@@ -314,11 +388,13 @@ export function ToolRenderer() {
 
 </details>
 
+<a id="documentation"></a>
+
 ## 📚 Documentation
 
 Full documentation is available at: **[Docs](https://docs.mcp-assistant.in/)**
 
-### 🗂️ Topics Covered:
+### 🗂️ Topics Covered
 
 - **[Getting Started](https://docs.mcp-assistant.in/get-started)** - Quick setup and overview
 - **[Installation](https://docs.mcp-assistant.in/install)** - Detailed installation guide
@@ -327,6 +403,8 @@ Full documentation is available at: **[Docs](https://docs.mcp-assistant.in/)**
 - **[React Hook Guide](https://docs.mcp-assistant.in/react)** - Using the useMcp hook
 - **[API Reference](https://docs.mcp-assistant.in/api-reference/server)** - Complete API documentation
 
+<a id="environment-setup"></a>
+
 ## ⚙️ Environment Setup
 
 The library supports multiple storage backends. You can explicitly select one using `MCP_TS_STORAGE_TYPE` or rely on automatic detection.
@@ -335,13 +413,13 @@ The library supports multiple storage backends. You can explicitly select one us
 
 ### 🧷 Configuration Examples
 
-1.  **<img src="docs/images/storage-backend/redis.svg" width="20" height="20" align="center" /> Redis** (Recommended for production)
+1.  **Redis** (Recommended for production)
     ```bash
     MCP_TS_STORAGE_TYPE=redis
     REDIS_URL=redis://localhost:6379
     ```
 
-2.  **<img src="docs/images/storage-backend/sqlite.svg" width="20" height="20" align="center" /> SQLite** (Fast & Persistent)
+2.  **SQLite** (Fast & Persistent)
     ```bash
     MCP_TS_STORAGE_TYPE=sqlite
     # Optional path
@@ -354,19 +432,21 @@ The library supports multiple storage backends. You can explicitly select one us
     NEON_DATABASE_URL=postgresql://user:password@host.neon.tech/dbname?sslmode=verify-full&channel_binding=require
     ```
 
-4.  **<img src="docs/images/storage-backend/filesystem.svg" width="20" height="20" align="center" /> File System** (Great for local dev)
+4.  **File System** (Great for local dev)
     ```bash
     MCP_TS_STORAGE_TYPE=file
     MCP_TS_STORAGE_FILE=./sessions.json
     ```
 
-5.  **<img src="docs/images/storage-backend/memory.svg" width="20" height="20" align="center" /> In-Memory** (Default for testing)
+5.  **In-Memory** (Default for testing)
     ```bash
     MCP_TS_STORAGE_TYPE=memory
     ```
 
 ---
 
+<a id="gateway-setup-mcpassistant-gateway"></a>
+
 ## 🐍 Gateway Setup (mcpassistant-gateway)
 
 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.
@@ -391,6 +471,8 @@ uvx mcpassistant-gateway run --name "local-files"
 
 ---
 
+<a id="architecture"></a>
+
 ## 🏗️ Architecture
 
 The MCP Toolkit supports two common runtime topologies:
@@ -434,7 +516,7 @@ graph LR
 > [!NOTE]
 > 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.
 > 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.
-> 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.
+> 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.
 
 For more details, refer to the documentation and follow the **installation guide for each adapter or storage backend**.
 
@@ -444,6 +526,8 @@ For more details, refer to the documentation and follow the **installation guide
 - [Redis Storage Installation Guide](https://docs.mcp-assistant.in/storage/redis)
 
 
+<a id="contributing"></a>
+
 ## 🤝 Contributing
 
 Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute.
@@ -452,7 +536,6 @@ Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for
 <br />
 
 <p align="center">
-  <em> Thanks for visiting ✨ @mcp-ts!</em><br><br>
-  <img src="https://visitor-badge.laobi.icu/badge?page_id=zonlabs.mcp-ts&style=for-the-badge&color=00d4ff" alt="Views">
+  <em>Thanks for visiting @mcp-ts!</em>
 </p>
 

package/dist/adapters/agui-adapter.d.mts

@@ -1,10 +1,10 @@
-import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-DYNe6az3.mjs';
-import { d as ToolRouter } from '../tool-router-BhHsvBfP.mjs';
+import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-CIMUGF8S.mjs';
+import { d as ToolRouter } from '../tool-router-CuApsDiV.mjs';
 import '../events-CK3N--3g.mjs';
 import '@modelcontextprotocol/sdk/types.js';
 import '@modelcontextprotocol/sdk/client/auth.js';
 import '@modelcontextprotocol/sdk/shared/auth.js';
-import '../types-CxFaaZrM.mjs';
+import '../types-DCk_IF4L.mjs';
 
 /**
  * MCP Adapter for AG-UI Integration

package/dist/adapters/agui-adapter.d.ts

@@ -1,10 +1,10 @@
-import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-BYtguGJm.js';
-import { d as ToolRouter } from '../tool-router-BMzhoNYt.js';
+import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-CnvZEGPY.js';
+import { d as ToolRouter } from '../tool-router-CZMrOG8J.js';
 import '../events-CK3N--3g.js';
 import '@modelcontextprotocol/sdk/types.js';
 import '@modelcontextprotocol/sdk/client/auth.js';
 import '@modelcontextprotocol/sdk/shared/auth.js';
-import '../types-CxFaaZrM.js';
+import '../types-DCk_IF4L.js';
 
 /**
  * MCP Adapter for AG-UI Integration

package/dist/adapters/agui-middleware.d.mts

@@ -2,13 +2,13 @@ import { Observable } from 'rxjs';
 import { Middleware, RunAgentInput, AbstractAgent, BaseEvent } from '@ag-ui/client';
 export { AbstractAgent, BaseEvent, EventType, Middleware, RunAgentInput, Tool, ToolCallEndEvent } from '@ag-ui/client';
 import { AguiTool } from './agui-adapter.mjs';
-import '../multi-session-client-DYNe6az3.mjs';
+import '../multi-session-client-CIMUGF8S.mjs';
 import '../events-CK3N--3g.mjs';
 import '@modelcontextprotocol/sdk/types.js';
 import '@modelcontextprotocol/sdk/client/auth.js';
 import '@modelcontextprotocol/sdk/shared/auth.js';
-import '../tool-router-BhHsvBfP.mjs';
-import '../types-CxFaaZrM.mjs';
+import '../tool-router-CuApsDiV.mjs';
+import '../types-DCk_IF4L.mjs';
 
 /**
  * AG-UI Middleware for MCP Tool Execution

package/dist/adapters/agui-middleware.d.ts

@@ -2,13 +2,13 @@ import { Observable } from 'rxjs';
 import { Middleware, RunAgentInput, AbstractAgent, BaseEvent } from '@ag-ui/client';
 export { AbstractAgent, BaseEvent, EventType, Middleware, RunAgentInput, Tool, ToolCallEndEvent } from '@ag-ui/client';
 import { AguiTool } from './agui-adapter.js';
-import '../multi-session-client-BYtguGJm.js';
+import '../multi-session-client-CnvZEGPY.js';
 import '../events-CK3N--3g.js';
 import '@modelcontextprotocol/sdk/types.js';
 import '@modelcontextprotocol/sdk/client/auth.js';
 import '@modelcontextprotocol/sdk/shared/auth.js';
-import '../tool-router-BMzhoNYt.js';
-import '../types-CxFaaZrM.js';
+import '../tool-router-CZMrOG8J.js';
+import '../types-DCk_IF4L.js';
 
 /**
  * AG-UI Middleware for MCP Tool Execution

package/dist/adapters/ai-adapter.d.mts

@@ -1,11 +1,11 @@
-import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-DYNe6az3.mjs';
+import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-CIMUGF8S.mjs';
 import { ToolSet } from 'ai';
-import { d as ToolRouter } from '../tool-router-BhHsvBfP.mjs';
+import { d as ToolRouter } from '../tool-router-CuApsDiV.mjs';
 import '../events-CK3N--3g.mjs';
 import '@modelcontextprotocol/sdk/types.js';
 import '@modelcontextprotocol/sdk/client/auth.js';
 import '@modelcontextprotocol/sdk/shared/auth.js';
-import '../types-CxFaaZrM.mjs';
+import '../types-DCk_IF4L.mjs';
 
 interface AIAdapterOptions {
     /**

package/dist/adapters/ai-adapter.d.ts

@@ -1,11 +1,11 @@
-import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-BYtguGJm.js';
+import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-CnvZEGPY.js';
 import { ToolSet } from 'ai';
-import { d as ToolRouter } from '../tool-router-BMzhoNYt.js';
+import { d as ToolRouter } from '../tool-router-CZMrOG8J.js';
 import '../events-CK3N--3g.js';
 import '@modelcontextprotocol/sdk/types.js';
 import '@modelcontextprotocol/sdk/client/auth.js';
 import '@modelcontextprotocol/sdk/shared/auth.js';
-import '../types-CxFaaZrM.js';
+import '../types-DCk_IF4L.js';
 
 interface AIAdapterOptions {
     /**

package/dist/adapters/langchain-adapter.d.mts

@@ -1,11 +1,11 @@
-import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-DYNe6az3.mjs';
+import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-CIMUGF8S.mjs';
 import { StructuredTool } from '@langchain/core/tools';
-import { d as ToolRouter } from '../tool-router-BhHsvBfP.mjs';
+import { d as ToolRouter } from '../tool-router-CuApsDiV.mjs';
 import '../events-CK3N--3g.mjs';
 import '@modelcontextprotocol/sdk/types.js';
 import '@modelcontextprotocol/sdk/client/auth.js';
 import '@modelcontextprotocol/sdk/shared/auth.js';
-import '../types-CxFaaZrM.mjs';
+import '../types-DCk_IF4L.mjs';
 
 interface LangChainAdapterOptions {
     /**

package/dist/adapters/langchain-adapter.d.ts

@@ -1,11 +1,11 @@
-import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-BYtguGJm.js';
+import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-CnvZEGPY.js';
 import { StructuredTool } from '@langchain/core/tools';
-import { d as ToolRouter } from '../tool-router-BMzhoNYt.js';
+import { d as ToolRouter } from '../tool-router-CZMrOG8J.js';
 import '../events-CK3N--3g.js';
 import '@modelcontextprotocol/sdk/types.js';
 import '@modelcontextprotocol/sdk/client/auth.js';
 import '@modelcontextprotocol/sdk/shared/auth.js';
-import '../types-CxFaaZrM.js';
+import '../types-DCk_IF4L.js';
 
 interface LangChainAdapterOptions {
     /**

package/dist/adapters/mastra-adapter.d.mts

@@ -1,4 +1,4 @@
-import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-DYNe6az3.mjs';
+import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-CIMUGF8S.mjs';
 import { z } from 'zod';
 import '../events-CK3N--3g.mjs';
 import '@modelcontextprotocol/sdk/types.js';

package/dist/adapters/mastra-adapter.d.ts

@@ -1,4 +1,4 @@
-import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-BYtguGJm.js';
+import { M as MCPClient, a as MultiSessionClient } from '../multi-session-client-CnvZEGPY.js';
 import { z } from 'zod';
 import '../events-CK3N--3g.js';
 import '@modelcontextprotocol/sdk/types.js';

package/dist/client/index.d.mts

@@ -1,5 +1,5 @@
-export { A as APP_HOST_DEFAULTS, a as AppHost, D as DEFAULT_MCP_APP_CSP, S as SANDBOX_PROXY_READY_METHOD, b as SANDBOX_RESOURCE_READY_METHOD, c as SSEClient, d as SSEClientOptions } from '../index-Cfjsme-a.mjs';
+export { A as APP_HOST_DEFAULTS, a as AppHost, D as DEFAULT_MCP_APP_CSP, S as SANDBOX_PROXY_READY_METHOD, b as SANDBOX_RESOURCE_READY_METHOD, c as SSEClient, d as SSEClientOptions } from '../index-ByIjEReo.mjs';
 export { D as Disposable, a as DisposableStore, E as Emitter, b as Event, M as McpConnectionEvent, c as McpConnectionState, d as McpObservabilityEvent } from '../events-CK3N--3g.mjs';
-export { q as McpRpcRequest, r as McpRpcResponse, v as ToolInfo } from '../types-CxFaaZrM.mjs';
+export { q as McpRpcRequest, r as McpRpcResponse, v as ToolInfo } from '../types-DCk_IF4L.mjs';
 import '@modelcontextprotocol/ext-apps/app-bridge';
 import '@modelcontextprotocol/sdk/types.js';

package/dist/client/index.d.ts

@@ -1,5 +1,5 @@
-export { A as APP_HOST_DEFAULTS, a as AppHost, D as DEFAULT_MCP_APP_CSP, S as SANDBOX_PROXY_READY_METHOD, b as SANDBOX_RESOURCE_READY_METHOD, c as SSEClient, d as SSEClientOptions } from '../index-CmjMd2ac.js';
+export { A as APP_HOST_DEFAULTS, a as AppHost, D as DEFAULT_MCP_APP_CSP, S as SANDBOX_PROXY_READY_METHOD, b as SANDBOX_RESOURCE_READY_METHOD, c as SSEClient, d as SSEClientOptions } from '../index-CtXvKl8N.js';
 export { D as Disposable, a as DisposableStore, E as Emitter, b as Event, M as McpConnectionEvent, c as McpConnectionState, d as McpObservabilityEvent } from '../events-CK3N--3g.js';
-export { q as McpRpcRequest, r as McpRpcResponse, v as ToolInfo } from '../types-CxFaaZrM.js';
+export { q as McpRpcRequest, r as McpRpcResponse, v as ToolInfo } from '../types-DCk_IF4L.js';
 import '@modelcontextprotocol/ext-apps/app-bridge';
 import '@modelcontextprotocol/sdk/types.js';

package/dist/client/index.js

@@ -48,8 +48,8 @@ var SSEClient = class {
   async getSession(sessionId) {
     return this.sendRequest("getSession", { sessionId });
   }
-  async finishAuth(sessionId, code) {
-    return this.sendRequest("finishAuth", { sessionId, code });
+  async finishAuth(state, code) {
+    return this.sendRequest("finishAuth", { state, code });
   }
   async listPrompts(sessionId) {
     return this.sendRequest("listPrompts", { sessionId });