{"id":49370722,"url":"https://github.com/zonlabs/mcp-ts","last_synced_at":"2026-05-17T21:16:03.658Z","repository":{"id":334108890,"uuid":"1139819534","full_name":"zonlabs/mcp-ts","owner":"zonlabs","description":"Where agents meet their full potential. Together with MCP.","archived":false,"fork":false,"pushed_at":"2026-04-27T17:47:09.000Z","size":57581,"stargazers_count":5,"open_issues_count":26,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T19:29:19.712Z","etag":null,"topics":["ag-ui-protocol","agents","mcp-app","mcp-client","modelcontextprotocol","python","redis","supabase","typescript"],"latest_commit_sha":null,"homepage":"https://docs.mcp-assistant.in","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zonlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-22T13:09:09.000Z","updated_at":"2026-04-26T14:49:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"672b0f09-ce35-441c-a734-c9b94e0da3eb","html_url":"https://github.com/zonlabs/mcp-ts","commit_stats":null,"previous_names":["ashen-dusk/mcp-redis","oxolabs/mcp-ts","zonlabs/mcp-ts"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/zonlabs/mcp-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zonlabs%2Fmcp-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zonlabs%2Fmcp-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zonlabs%2Fmcp-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zonlabs%2Fmcp-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zonlabs","download_url":"https://codeload.github.com/zonlabs/mcp-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zonlabs%2Fmcp-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32358509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T20:07:02.737Z","status":"ssl_error","status_checked_at":"2026-04-27T20:07:00.910Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ag-ui-protocol","agents","mcp-app","mcp-client","modelcontextprotocol","python","redis","supabase","typescript"],"created_at":"2026-04-27T23:00:59.947Z","updated_at":"2026-05-17T21:16:03.651Z","avatar_url":"https://github.com/zonlabs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/zonlabs/mcp-ts\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/images/logo-dark.png\"\u003e\n      \u003cimg src=\"docs/images/logo-light.png\" alt=\"mcp toolkit\" width=\"400\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003eEvery resource is context for your AI\u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://mcp-assistant.in/\"\u003e🌐 Website\u003c/a\u003e\n    \u0026nbsp;\u0026nbsp;|\u0026nbsp;\u0026nbsp;\n    \u003ca href=\"https://docs.mcp-assistant.in/\"\u003e📚 Documentation\u003c/a\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@mcp-ts/sdk\"\u003e\n      \u003cimg src=\"https://img.shields.io/npm/v/@mcp-ts/sdk?color=dc2626\u0026label=npm\u0026logo=npm\u0026style=flat-square\" alt=\"npm version\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/mcpassistant-gateway/\"\u003e\n      \u003cimg src=\"https://img.shields.io/pypi/v/mcpassistant-gateway?color=3776ab\u0026label=pypi\u0026logo=pypi\u0026style=flat-square\" alt=\"pypi version\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/license-MIT-84cc16?style=flat-square\" alt=\"License: MIT\" /\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n## 📖 Table of Contents\n\n- [✨ Features](#-features)\n- [📦 Packages](#-packages)\n- [🛠️ SDK Setup (@mcp-ts/sdk)](#️-sdk-setup-mcp-tssdk)\n  - [📦 Installation](#-installation)\n  - [🚀 Quick Start](#-quick-start)\n- [🐍 Gateway Setup (mcpassistant-gateway)](#-gateway-setup-mcpassistant-gateway)\n  - [📦 Installation](#-installation-1)\n  - [🚀 Usage](#-usage)\n- [🏗️ Architecture](#️-architecture)\n- [📚 Documentation](#-documentation)\n- [⚙️ Environment Setup](#️-environment-setup)\n- [🧪 Examples](#-examples)\n- [💡 Inspiration](#-inspiration)\n\n---\n\n## 📦 Packages\n\n| Package | Description | Install |\n| :--- | :--- | :--- |\n| **[@mcp-ts/sdk](src)** | TypeScript/JavaScript SDK for clients \u0026 servers. | `npm i @mcp-ts/sdk` |\n| **[mcpassistant-gateway](packages/mcp-local-agent)** | Python bridge for local MCP support in remote apps. | `pip install mcpassistant-gateway` |\n\n---\n\n## ✨ Features\n\nMost features are available out-of-the-box in the **TypeScript SDK**:\n\n- **SSE** - Server-Sent Events for connection state and observability updates\n- **Flexible Storage** - Redis, SQLite, File System, or In-Memory backends\n- **Serverless** - Works in serverless environments (Vercel, AWS Lambda, etc.)\n- **React Hook** - `useMcp` hook for easy React integration\n- **Vue Composable** - `useMcp` composable for Vue applications\n- **MCP Protocol** - Support for tools, prompts, and resources\n- **Agent Adapters** - Built-in adapters for AI SDK, LangChain, Mastra, and AG-UI\n- **MCP Apps Extension (SEP-1865)** - Interactive UI-driven tool interfaces\n\n## 🧪 Examples\n\nCheck out working examples demonstrating the MCP Apps extension and agent integrations in the [examples/agents](examples/agents) directory.\n\n\u003e Examples MCP Apps referred from [modelcontextprotocol/ext-apps](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples)\n\n\u003cdiv align=\"center\"\u003e\n  \u003ctable cellspacing=\"5\" cellpadding=\"0\"\u003e\n    \u003ctr\u003e\n      \u003ctd width=\"50%\"\u003e\n        \u003cimg src=\"docs/images/mcp-apps-img-1.png\" alt=\"MCP Apps 1\" width=\"100%\" /\u003e\n      \u003c/td\u003e\n      \u003ctd width=\"50%\"\u003e\n        \u003cimg src=\"docs/images/mcp-apps-img-2.png\" alt=\"MCP Apps 2\" width=\"100%\" /\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n  \u003cp\u003e\u003cem\u003eInteractive UIs for MCP tools\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n## 💡 Inspiration\n\n\u003e I got the idea for `@mcp-ts` while working on 🌐 **[MCP Assistant](https://mcp-assistant.in)**.\nAs 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.\nSo with that idea in mind, I built this SDK to make setup easier and keep the user experience smooth.\nThat’s how `@mcp-ts` started.\n\n\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/images/mcp-assistant.png\" alt=\"MCP Assistant\" width=\"100%\" /\u003e\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n## 🛠️ SDK Setup (@mcp-ts/sdk)\n\n### 📦 Installation\n\n```bash\nnpm install @mcp-ts/sdk\n```\n\nThe SDK supports multiple storage backends out of the box:\n- **Memory** (default, no setup required)\n- **File** (local persistence)\n- **SQLite** (fast local persistence, requires `npm install better-sqlite3`)\n- **Redis** (production-ready, requires `npm install ioredis`)\n\n### 🚀 Quick Start\n\n#### 🖥️ Server-Side (Next.js)\n\n```typescript\n// app/api/mcp/route.ts\nimport { createNextMcpHandler } from '@mcp-ts/sdk/server';\n\nexport const dynamic = 'force-dynamic';\nexport const runtime = 'nodejs';\n\nexport const { GET, POST } = createNextMcpHandler({\n  authenticate: () =\u003e {\n    //  your logic here\n  }\n});\n```\n\n### 🎯 Client-Side (React)\n\n```typescript\n'use client';\n\nimport { useMcp } from '@mcp-ts/sdk/client/react';\n\nfunction App() {\n  const { connections, connect } = useMcp({\n    url: '/api/mcp',\n    userId: 'user-123',\n  });\n\n  return (\n    \u003cdiv className=\"flex flex-col items-center gap-4\"\u003e\n      \u003cbutton\n        onClick={() =\u003e\n          connect({\n            serverId: 'my-server',\n            serverName: 'My MCP Server',\n            serverUrl: 'https://mcp.example.com',\n            callbackUrl: `${window.location.origin}/callback`,\n          })\n        }\n      \u003e\n        Connect\n      \u003c/button\u003e\n      {connections.map((conn) =\u003e (\n        \u003cdiv key={conn.sessionId}\u003e\n          \u003ch3\u003e{conn.serverName}\u003c/h3\u003e\n          \u003cp\u003eState: {conn.state}\u003c/p\u003e\n          \u003cp\u003eTools: {conn.tools.length}\u003c/p\u003e\n        \u003c/div\u003e\n      ))}\n    \u003c/div\u003e\n  );\n}\n```\n\n### 🔌 Adapters\n\nIntegrating with agent frameworks is simple using built-in adapters.\n\n\u003cdetails\u003e\n\u003csummary\u003eVercel AI SDK\u003c/summary\u003e\n\n```typescript\n// app/api/chat/route.ts\nimport { MultiSessionClient } from '@mcp-ts/sdk/server';\nimport { AIAdapter } from '@mcp-ts/sdk/adapters/ai';\nimport { streamText } from 'ai';\nimport { openai } from '@ai-sdk/openai';\n\nexport async function POST(req: Request) {\n  const { messages, userId } = await req.json();\n  const client = new MultiSessionClient(userId);\n\n  try {\n    await client.connect();\n    const tools = await AIAdapter.getTools(client);\n    const result = streamText({\n      model: openai('gpt-4'),\n      messages,\n      tools,\n      onFinish: async () =\u003e {\n        await client.disconnect();\n      }\n    });\n    return result.toDataStreamResponse();\n  } catch (error) {\n    await client.disconnect();\n    throw error;\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAgui Adapter\u003c/summary\u003e\n\n```typescript\nimport { MultiSessionClient } from '@mcp-ts/sdk/server';\nimport { AguiAdapter } from '@mcp-ts/sdk/adapters/agui-adapter';\n\nconst client = new MultiSessionClient(\"user_123\");\nawait client.connect();\n\nconst adapter = new AguiAdapter(client);\nconst tools = await adapter.getTools();\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMastra Adapter\u003c/summary\u003e\n\n```typescript\nimport { MultiSessionClient } from '@mcp-ts/sdk/server';\nimport { MastraAdapter } from '@mcp-ts/sdk/adapters/mastra-adapter';\n\nconst client = new MultiSessionClient(\"user_123\");\nawait client.connect();\n\nconst tools = await MastraAdapter.getTools(client);\n```\n\n\u003c/details\u003e\n\n### 🧩 AG-UI Middleware\n\nExecute MCP tools server-side when using remote agents (LangGraph, AutoGen, etc.):\n\n\u003cdetails\u003e\n\u003csummary\u003eView AG-UI (Agent Middleware)\u003c/summary\u003e\n\n```typescript\nimport { HttpAgent } from \"@ag-ui/client\";\nimport { AguiAdapter } from \"@mcp-ts/sdk/adapters/agui-adapter\";\nimport { createMcpMiddleware } from \"@mcp-ts/sdk/adapters/agui-middleware\";\n\n// Connect to MCP servers\nconst { MultiSessionClient } = await import(\"@mcp-ts/sdk/server\");\nconst client = new MultiSessionClient(\"user_123\");\nawait client.connect();\n\n// Create adapter and get tools\nconst adapter = new AguiAdapter(client);\nconst mcpTools = await adapter.getTools();\n\n// Create agent with middleware\nconst agent = new HttpAgent({ url: \"http://localhost:8000/agent\" });\nagent.use(createMcpMiddleware({\n  toolPrefix: 'server-',\n  tools: mcpTools,\n}));\n```\n\n\u003c/details\u003e\n\nThe middleware intercepts tool calls from remote agents, executes MCP tools server-side, and returns results back to the agent.\n\n### 🛠️ MCP Apps (SEP-1865)\n\nRender interactive UIs for your tools using the `useMcpApps` hook.\n\n\u003cdetails\u003e\n\u003csummary\u003eView MCP Apps\u003c/summary\u003e\n\n```typescript\nimport { useRenderToolCall } from \"@copilotkit/react-core\";\nimport { useMcpApps } from \"@mcp-ts/sdk/client/react\";\nimport { useMcpContext } from \"./mcp\";\n\nexport function ToolRenderer() {\n  const { mcpClient } = useMcpContext();\n  const { McpAppRenderer } = useMcpApps(mcpClient);\n\n  useRenderToolCall({\n    name: \"*\",\n    render: ({ name, args, result, status }) =\u003e (\n      \u003cMcpAppRenderer\n        name={name}\n        input={args}\n        result={result}\n        status={status}\n      /\u003e\n    ),\n  });\n\n  return null;\n}\n```\n\n\u003c/details\u003e\n\n## 📚 Documentation\n\nFull documentation is available at: **[Docs](https://docs.mcp-assistant.in/)**\n\n### 🗂️ Topics Covered:\n\n- **[Getting Started](https://docs.mcp-assistant.in/get-started)** - Quick setup and overview\n- **[Installation](https://docs.mcp-assistant.in/install)** - Detailed installation guide\n- **[Storage Backends](https://docs.mcp-assistant.in/storage/overview)** - Redis, File, Memory options\n- **[Next.js Integration](https://docs.mcp-assistant.in/nextjs)** - Complete Next.js examples\n- **[React Hook Guide](https://docs.mcp-assistant.in/react)** - Using the useMcp hook\n- **[API Reference](https://docs.mcp-assistant.in/api-reference/server)** - Complete API documentation\n\n## ⚙️ Environment Setup\n\nThe library supports multiple storage backends. You can explicitly select one using `MCP_TS_STORAGE_TYPE` or rely on automatic detection.\n\n**Supported Types:** `redis`, `supabase`, `neon`, `sqlite`, `file`, `memory`.\n\n### 🧷 Configuration Examples\n\n1.  **\u003cimg src=\"docs/images/storage-backend/redis.svg\" width=\"20\" height=\"20\" align=\"center\" /\u003e Redis** (Recommended for production)\n    ```bash\n    MCP_TS_STORAGE_TYPE=redis\n    REDIS_URL=redis://localhost:6379\n    ```\n\n2.  **\u003cimg src=\"docs/images/storage-backend/sqlite.svg\" width=\"20\" height=\"20\" align=\"center\" /\u003e SQLite** (Fast \u0026 Persistent)\n    ```bash\n    MCP_TS_STORAGE_TYPE=sqlite\n    # Optional path\n    MCP_TS_STORAGE_SQLITE_PATH=./sessions.db\n    ```\n\n3.  **Neon** (Serverless Postgres)\n    ```bash\n    MCP_TS_STORAGE_TYPE=neon\n    NEON_DATABASE_URL=postgresql://user:password@host.neon.tech/dbname?sslmode=verify-full\u0026channel_binding=require\n    ```\n\n4.  **\u003cimg src=\"docs/images/storage-backend/filesystem.svg\" width=\"20\" height=\"20\" align=\"center\" /\u003e File System** (Great for local dev)\n    ```bash\n    MCP_TS_STORAGE_TYPE=file\n    MCP_TS_STORAGE_FILE=./sessions.json\n    ```\n\n5.  **\u003cimg src=\"docs/images/storage-backend/memory.svg\" width=\"20\" height=\"20\" align=\"center\" /\u003e In-Memory** (Default for testing)\n    ```bash\n    MCP_TS_STORAGE_TYPE=memory\n    ```\n\n---\n\n## 🐍 Gateway Setup (mcpassistant-gateway)\n\nThe **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.\n\n### 📦 Installation\n\n```bash\npip install mcpassistant-gateway\n```\n\n### 🚀 Usage\n\nYou can run the gateway using `uvx` or `pip`:\n\n```bash\n# Run the interactive menu\nuvx mcpassistant-gateway menu\n\n# Run the bridge directly\nuvx mcpassistant-gateway run --name \"local-files\"\n```\n\n---\n\n## 🏗️ Architecture\n\nThe MCP Toolkit supports two common runtime topologies:\n\n```mermaid\ngraph LR\n    subgraph Direct[\"Direct SDK Flow (TypeScript)\"]\n        UI[Browser UI]\n        Hook[useMcp Hook]\n        API[Next.js /api/mcp]\n        Mgr[MultiSessionClient]\n        Store[(Redis/File/Memory)]\n        MCP[MCP Servers]\n\n        UI \u003c--\u003e Hook\n        Hook -- \"HTTP RPC\" --\u003e API\n        API --\u003e Mgr\n        Mgr -- \"SSE events\" --\u003e Hook\n        Mgr \u003c--\u003e Store\n        Mgr \u003c--\u003e MCP\n    end\n\n    subgraph Bridge[\"Remote Bridge Flow (Python)\"]\n        direction TB\n        Spacer[\" \"]\n        Agent[mcpassistant-gateway]\n        Remote[Remote Bridge Server]\n        LocalMcp[Local MCP Servers]\n\n        Spacer --- Agent\n        Agent -- \"WSS /connect (outbound)\" --\u003e Remote\n        Agent \u003c--\u003e LocalMcp\n        style Spacer fill:transparent,stroke:transparent,color:transparent\n    end\n```\n\n- **Direct SDK flow**: Browser clients use `useMcp` over HTTP + SSE to a server route backed by `MultiSessionClient`.\n- **Bridge flow**: `mcpassistant-gateway` keeps an outbound authenticated WebSocket to a remote bridge and forwards tool calls to local MCP servers.\n- **Storage**: Session state and connection metadata persist in Redis, File, SQLite, or Memory backends.\n\n\u003e [!NOTE]\n\u003e 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.\n\u003e 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.\n\u003e 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.\n\nFor more details, refer to the documentation and follow the **installation guide for each adapter or storage backend**.\n\n- [AI SDK Installation Guide](https://docs.mcp-assistant.in/adapters/ai-sdk)\n- [Mastra Installation Guide](https://docs.mcp-assistant.in/adapters/mastra)\n- [LangChain Installation Guide](https://docs.mcp-assistant.in/adapters/langchain)\n- [Redis Storage Installation Guide](https://docs.mcp-assistant.in/storage/redis)\n\n\n## 🤝 Contributing\n\nContributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute.\n\n\n\u003cbr /\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e Thanks for visiting ✨ @mcp-ts!\u003c/em\u003e\u003cbr\u003e\u003cbr\u003e\n  \u003cimg src=\"https://visitor-badge.laobi.icu/badge?page_id=zonlabs.mcp-ts\u0026style=for-the-badge\u0026color=00d4ff\" alt=\"Views\"\u003e\n\u003c/p\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzonlabs%2Fmcp-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzonlabs%2Fmcp-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzonlabs%2Fmcp-ts/lists"}