@oobe-protocol-labs/synapse-client-sdk 1.2.2 → 2.0.2

package/dist/docs/media/11_MCP.md

@@ -0,0 +1,459 @@
+# 11 — MCP: Model Context Protocol Server & Client
+
+> **Import**: `@…/synapse-client-sdk/ai/mcp`
+> **Source**: `src/ai/mcp/`
+> **Prerequisites**: [10_PLUGINS.md](./10_PLUGINS.md) (SynapseAgentKit + plugins)
+
+---
+
+## Overview
+
+The MCP module implements the full [Model Context Protocol](https://modelcontextprotocol.io/) (spec 2024-11-05) with **zero external MCP dependencies**. It works in both directions:
+
+| Direction | Class | What it does |
+|-----------|-------|-------------|
+| **Server** | `SynapseMcpServer` | Exposes any `SynapseAgentKit` as an MCP server — works with Claude Desktop, Cursor, VS Code, Cline, and any MCP client |
+| **Client** | `McpClientBridge` | Connects to external MCP servers (GitHub, Postgres, filesystem, etc.) and imports their tools into the SDK |
+
+```
+┌──────────────────┐            ┌──────────────────────┐
+│  Claude Desktop  │◄── stdio ─►│  SynapseMcpServer    │
+│  Cursor          │            │  (your 110+ tools)   │
+│  VS Code         │            └──────────┬───────────┘
+│  Any MCP Client  │                       │
+└──────────────────┘               SynapseAgentKit
+                                    .use(TokenPlugin)
+                                    .use(DeFiPlugin)
+                                    .use(...)
+
+┌──────────────────┐            ┌──────────────────────┐
+│  GitHub MCP      │◄── stdio ─►│  McpClientBridge     │
+│  Postgres MCP    │            │  (imports tools)     │
+│  Filesystem MCP  │◄── sse ──►│                      │
+│  Any MCP Server  │            └──────────┬───────────┘
+└──────────────────┘                       │
+                                    kit.use(bridge.toPlugin())
+```
+
+---
+
+## MCP Server
+
+### stdio transport (Claude Desktop, Cursor)
+
+stdio is the primary transport. The server reads JSON-RPC messages from `stdin` and writes responses to `stdout`, one per line.
+
+```ts
+import { SynapseAgentKit, TokenPlugin, DeFiPlugin } from '@oobe-protocol-labs/synapse-client-sdk/ai/plugins';
+import { SynapseMcpServer } from '@oobe-protocol-labs/synapse-client-sdk/ai/mcp';
+
+const kit = new SynapseAgentKit({ rpcUrl: process.env.RPC_URL! })
+  .use(TokenPlugin)
+  .use(DeFiPlugin);
+
+const server = new SynapseMcpServer(kit, {
+  name: 'synapse-solana',
+  version: '2.0.0',
+  instructions: 'Solana blockchain tools for AI agents — tokens, DeFi, and more.',
+});
+
+await server.start(); // Reads from stdin, writes to stdout
+```
+
+#### Claude Desktop config
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "synapse-solana": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/your/mcp-server.ts"],
+      "env": {
+        "RPC_URL": "https://rpc.synapse.com"
+      }
+    }
+  }
+}
+```
+
+#### Cursor config
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "synapse-solana": {
+      "command": "npx",
+      "args": ["tsx", "./mcp-server.ts"],
+      "env": {
+        "RPC_URL": "https://rpc.synapse.com"
+      }
+    }
+  }
+}
+```
+
+### SSE transport (web clients)
+
+For browser-based or HTTP-based MCP clients:
+
+```ts
+const server = new SynapseMcpServer(kit, {
+  name: 'synapse-solana',
+  version: '2.0.0',
+});
+
+await server.startSse({ port: 3001 });
+// HTTP endpoints:
+//   GET  /mcp/sse       — EventSource stream
+//   POST /mcp/message   — JSON-RPC messages
+//   GET  /mcp/health    — health check
+```
+
+Connect with any SSE-compatible MCP client:
+
+```ts
+const eventSource = new EventSource('http://localhost:3001/mcp/sse');
+eventSource.onmessage = (event) => {
+  const response = JSON.parse(event.data);
+  console.log(response);
+};
+```
+
+### What the server exposes
+
+The server automatically exposes all tools, resources, and prompts from the `SynapseAgentKit`:
+
+| MCP Method | What happens |
+|------------|-------------|
+| `initialize` | Returns server info, capabilities, protocol version |
+| `tools/list` | Lists all plugin tools with JSON Schema input schemas |
+| `tools/call` | Executes a tool by name with validated input |
+| `resources/list` | Lists protocol-level resources |
+| `resources/read` | Reads a specific resource by URI |
+| `resources/templates/list` | Lists URI template patterns |
+| `prompts/list` | Lists available prompt templates |
+| `prompts/get` | Returns a specific prompt with messages |
+| `ping` | Health check (returns empty result) |
+| `completion/complete` | Auto-completion for tool/resource names |
+| `logging/setLevel` | Set server log level |
+
+### Zod → JSON Schema conversion
+
+The server includes a deep Zod-to-JSON-Schema converter that handles all Zod types used in plugin schemas:
+
+| Zod Type | JSON Schema |
+|----------|-------------|
+| `z.string()` | `{ type: 'string' }` with minLength, maxLength, pattern |
+| `z.number()` | `{ type: 'number' }` with minimum, maximum |
+| `z.boolean()` | `{ type: 'boolean' }` |
+| `z.array(T)` | `{ type: 'array', items: T }` |
+| `z.object({})` | `{ type: 'object', properties, required }` |
+| `z.enum([])` | `{ type: 'string', enum: [...] }` |
+| `z.optional(T)` | Removes key from `required` |
+| `z.default(T)` | Adds `default` to schema |
+| `z.nullable(T)` | `{ oneOf: [T, { type: 'null' }] }` |
+| `z.record(K, V)` | `{ type: 'object', additionalProperties: V }` |
+| `z.tuple([...])` | `{ type: 'array', prefixItems: [...] }` |
+| `z.union([...])` | `{ oneOf: [...] }` |
+| `z.literal(v)` | `{ const: v }` |
+
+### Server introspection
+
+```ts
+const info = server.info();
+// {
+//   name: 'synapse-solana',
+//   version: '2.0.0',
+//   toolCount: 65,
+//   resourceCount: 2,
+//   promptCount: 0,
+//   transport: 'stdio'
+// }
+```
+
+---
+
+## MCP Client Bridge
+
+The `McpClientBridge` connects to any external MCP server and imports its tools into your SDK workflow. This is how you access tools from GitHub, Postgres, filesystem, and any other MCP server.
+
+### Connect to MCP servers
+
+```ts
+import { McpClientBridge } from '@oobe-protocol-labs/synapse-client-sdk/ai/mcp';
+
+const bridge = new McpClientBridge({ debug: true });
+
+// ── stdio servers ──────────────────────────────────────────────
+await bridge.connect({
+  id: 'github',
+  name: 'GitHub',
+  transport: 'stdio',
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-github'],
+  env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN! },
+  toolPrefix: 'github_',
+});
+
+await bridge.connect({
+  id: 'postgres',
+  name: 'PostgreSQL',
+  transport: 'stdio',
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-postgres', process.env.DATABASE_URL!],
+  toolPrefix: 'pg_',
+});
+
+await bridge.connect({
+  id: 'filesystem',
+  name: 'Filesystem',
+  transport: 'stdio',
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/allowed/dir'],
+  toolPrefix: 'fs_',
+});
+
+// ── SSE servers ────────────────────────────────────────────────
+await bridge.connect({
+  id: 'custom',
+  name: 'Custom MCP Server',
+  transport: 'sse',
+  url: 'https://my-mcp-server.com/mcp/sse',
+  headers: { Authorization: 'Bearer sk-...' },
+  toolPrefix: 'custom_',
+});
+```
+
+### Get LangChain tools
+
+```ts
+// All tools from all connected servers
+const remoteTools = bridge.getTools();
+// → StructuredTool[] with prefixed names (github_create_issue, pg_query, etc.)
+
+// Tools from a specific server
+const githubTools = bridge.getServerTools('github');
+```
+
+### Call tools directly
+
+```ts
+const result = await bridge.callTool('github', 'create_issue', {
+  owner: 'my-org',
+  repo: 'my-repo',
+  title: 'Bug report from AI agent',
+  body: 'Automatically detected issue...',
+});
+```
+
+### Read resources
+
+```ts
+const resource = await bridge.readResource('postgres', 'postgres://table/users');
+```
+
+### Convert to plugin
+
+The bridge can be converted to a `SynapsePlugin` for seamless integration with `SynapseAgentKit`:
+
+```ts
+import { SynapseAgentKit, TokenPlugin } from '@oobe-protocol-labs/synapse-client-sdk/ai/plugins';
+
+const kit = new SynapseAgentKit({ rpcUrl })
+  .use(TokenPlugin)           // 22 Solana token tools
+  .use(bridge.toPlugin());    // + all remote MCP tools
+
+const allTools = kit.getTools();
+// → Token tools + GitHub tools + Postgres tools + filesystem tools
+```
+
+### Connection management
+
+```ts
+// Check status
+const status = bridge.getStatus('github');
+// {
+//   id: 'github',
+//   name: 'GitHub',
+//   status: 'connected',
+//   toolCount: 25,
+//   resourceCount: 0,
+//   serverInfo: { name: 'github-mcp-server', version: '1.0.0' },
+//   connectedAt: 1709712000000
+// }
+
+// All statuses
+const all = bridge.getAllStatuses();
+
+// All tool definitions with server IDs
+const defs = bridge.getAllToolDefinitions();
+// → [{ name, description, inputSchema, serverId }, ...]
+
+// Disconnect one server
+await bridge.disconnect('postgres');
+
+// Disconnect all
+await bridge.disconnectAll();
+```
+
+---
+
+## Combined: Server + Client
+
+Expose your Solana tools **and** external MCP tools as a single MCP server:
+
+```ts
+import { SynapseAgentKit, TokenPlugin, DeFiPlugin } from '@oobe-protocol-labs/synapse-client-sdk/ai/plugins';
+import { SynapseMcpServer, McpClientBridge } from '@oobe-protocol-labs/synapse-client-sdk/ai/mcp';
+
+// 1. Set up the bridge with external servers
+const bridge = new McpClientBridge();
+await bridge.connect({
+  id: 'github',
+  name: 'GitHub',
+  transport: 'stdio',
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-github'],
+  env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN! },
+});
+
+// 2. Build the kit with plugins + bridge
+const kit = new SynapseAgentKit({ rpcUrl: process.env.RPC_URL! })
+  .use(TokenPlugin)
+  .use(DeFiPlugin)
+  .use(bridge.toPlugin());
+
+// 3. Expose everything as a single MCP server
+const server = new SynapseMcpServer(kit, {
+  name: 'synapse-full-stack',
+  version: '2.0.0',
+  instructions: 'Solana tools + GitHub integration for AI agents.',
+});
+
+await server.start();
+// Claude Desktop now sees: Token tools + DeFi tools + GitHub tools
+```
+
+---
+
+## McpExternalServerConfig
+
+```ts
+interface McpExternalServerConfig {
+  /** Unique identifier for this connection */
+  id: string;
+
+  /** Human-readable server name */
+  name: string;
+
+  /** Transport type */
+  transport: 'stdio' | 'sse';
+
+  // ── stdio only ────────────────────────────
+  /** Command to spawn (e.g. 'npx', 'node') */
+  command?: string;
+
+  /** Command arguments */
+  args?: string[];
+
+  /** Environment variables for the child process */
+  env?: Record<string, string>;
+
+  // ── SSE only ──────────────────────────────
+  /** SSE endpoint URL */
+  url?: string;
+
+  /** HTTP headers for SSE connection */
+  headers?: Record<string, string>;
+
+  // ── Shared ────────────────────────────────
+  /** Prefix for imported tool names (e.g. 'github_') */
+  toolPrefix?: string;
+
+  /** Request timeout in ms (default: 30000) */
+  timeout?: number;
+}
+```
+
+---
+
+## McpServerConfig
+
+```ts
+interface McpServerConfig {
+  /** Server name (shown in MCP client UIs) */
+  name: string;
+
+  /** Server version */
+  version: string;
+
+  /** Instructions for AI agents using this server */
+  instructions?: string;
+
+  /** Additional prompts to expose */
+  prompts?: McpPromptDefinition[];
+
+  /** Additional resources to expose */
+  resources?: McpResourceDefinition[];
+
+  /** Resource URI templates */
+  resourceTemplates?: McpResourceTemplate[];
+}
+```
+
+---
+
+## JSON Schema → Zod (Runtime)
+
+The client bridge includes a runtime JSON Schema → Zod converter. When connecting to an external MCP server, tool input schemas (JSON Schema) are automatically converted to Zod schemas so they work with LangChain and the plugin system:
+
+```
+External MCP Server
+    │
+    │── tools/list → { name, description, inputSchema: JSONSchema }
+    │
+    ▼
+McpClientBridge
+    │
+    │── jsonSchemaToZod(inputSchema) → z.ZodTypeAny
+    │── tool(name, description, zodSchema, execFn) → StructuredTool
+    │
+    ▼
+LangChain StructuredTool[]    (ready for any agent)
+```
+
+Supported JSON Schema types:
+
+| JSON Schema | Zod Type |
+|-------------|----------|
+| `{ type: 'object', properties, required }` | `z.object({})` |
+| `{ type: 'string' }` | `z.string()` |
+| `{ type: 'string', enum: [...] }` | `z.enum([...])` |
+| `{ type: 'number' }` / `{ type: 'integer' }` | `z.number()` / `z.number().int()` |
+| `{ type: 'boolean' }` | `z.boolean()` |
+| `{ type: 'array', items }` | `z.array(T)` |
+| No matching type | `z.unknown()` |
+
+---
+
+## Protocol
+
+The implementation follows MCP spec **2024-11-05**:
+
+- **JSON-RPC 2.0** message framing
+- **Capabilities** negotiation on `initialize`
+- **Notifications** (`notifications/initialized`)
+- **Error codes** (-32700 Parse error, -32600 Invalid request, -32601 Method not found, -32602 Invalid params, -32603 Internal error)
+
+The SDK implements the protocol from scratch with zero external MCP dependencies. The full `@modelcontextprotocol/sdk` is **not** required — but if you already use it, both can coexist.
+
+---
+
+## Next
+
+- [09_PIPELINES.md](./09_PIPELINES.md) — Full end-to-end integration patterns.
+- [10_PLUGINS.md](./10_PLUGINS.md) — Plugin system details and custom plugin creation.

package/dist/docs/media/CHANGELOG.md

@@ -7,6 +7,228 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.0.2] — 2026-03-09
+
+### 🧹 Maintainability
+
+- **chore: remove 42 unused imports, variables & type annotations** — CodeQL flagged 42 instances of
+  unused variables, imports, functions or classes across 25 files (`src/`, `tests/`, `scripts/`).
+  Every unused item has been removed. Zero API surface changes.
+  ([CodeQL js/unused-local-variable](https://codeql.github.com/codeql-query-help/javascript/js-unused-local-variable/))
+
+- **fix(docs): sanitize malformed HTML `id` attributes** — Two `id` attributes in the TypeDoc-generated
+  `pipe.html` contained spaces and colons (`id="Example: Basic"`). Replaced with valid kebab-case
+  identifiers to ensure consistent cross-browser anchor behaviour.
+  ([CodeQL js/malformed-id-attribute](https://codeql.github.com/codeql-query-help/javascript/js-malformed-id-attribute/))
+
+### ⚙️ CI / Tooling
+
+- **chore: add Dependabot configuration** — `.github/dependabot.yml` now enables weekly npm and
+  GitHub Actions dependency updates with scoped commit prefixes (`chore(deps)`, `ci`).
+
+No API changes — drop-in replacement for 2.0.1.
+
+---
+
+## [2.0.1] — 2026-03-09
+
+### 🔒 Security
+
+- **fix(protocols): replace polynomial regex with iterative strip** — `ProtocolHttpClient` constructor
+  used `/\/+$/` to trim trailing slashes from `baseUrl`. CodeQL flagged this as a polynomial ReDoS
+  vector (proportional to `n²` on strings of repeated `/`). Replaced with a safe `while (url.endsWith('/'))` loop.
+  ([CodeQL js/polynomial-redos](https://codeql.github.com/codeql-query-help/javascript/js-polynomial-redos/))
+
+- **fix(actions): prevent stack-trace leakage in error responses** — `ActionsServer.handleRequest()` catch
+  block returned raw `err.message` for all exceptions, potentially exposing internal details.
+  Now only `ActionServerError` messages are forwarded; unexpected errors return a generic
+  `"Internal server error"`.
+  ([CodeQL js/stack-trace-exposure](https://codeql.github.com/codeql-query-help/javascript/js-stack-trace-exposure/))
+
+- **fix(next): sanitize error output in `withSynapseError`** — The Next.js error wrapper exposed
+  `err.message` from arbitrary exceptions. Now only SDK errors (those carrying a `code` property)
+  have their message forwarded; all other errors return `"Internal server error"`.
+  ([CodeQL js/stack-trace-exposure](https://codeql.github.com/codeql-query-help/javascript/js-stack-trace-exposure/))
+
+### Changed
+
+- No API changes — drop-in replacement for 2.0.0.
+
+---
+
+## [2.0.0] — 2026-03-06
+
+### ⚡ Breaking Changes
+
+- **Version bump**: `1.2.2` → `2.0.0`. This is a **major release** due to the introduction of the
+  plugin system (`SynapseAgentKit`) and MCP module which represent a new architecture layer.
+- **`transport.call()` removed from plugins** — All plugin executors now use `transport.request()`,
+  matching the public `HttpTransport` API. If you had custom code using `transport.call()` via
+  the plugin context, update to `transport.request()`.
+- **Registry mock client** — `SynapseAgentKit`'s internal context now exposes the transport as a
+  `.transport` property (matching `SynapseClientLike`) instead of `.getTransport()`.
+
+### Added
+
+#### Plugin System (`src/ai/plugins/`) — 6,469 lines of new code
+
+A fully modular, chainable plugin architecture for Solana-native AI tools. 110 tools across
+5 plugins and 18 protocols, all composable via `.use()`:
+
+```ts
+const kit = new SynapseAgentKit({ rpcUrl })
+  .use(TokenPlugin)
+  .use(NFTPlugin)
+  .use(DeFiPlugin)
+  .use(MiscPlugin)
+  .use(BlinksPlugin);
+
+const tools = kit.getTools();          // 110 LangChain StructuredTool[]
+const vercel = kit.getVercelAITools(); // Vercel AI SDK format
+const mcp = kit.getMcpToolDescriptors(); // MCP descriptors
+```
+
+- **`SynapseAgentKit`** (`src/ai/plugins/registry.ts`, 416 lines) — Core orchestrator with
+  `use()` chaining, multi-format tool export (LangChain, Vercel AI, MCP), `getToolMap()`,
+  `summary()`, `destroy()`. Includes `zodToJsonSchema()` helper for MCP descriptor generation.
+
+- **Plugin types** (`src/ai/plugins/types.ts`, 223 lines) — `SynapsePlugin`, `PluginMeta`,
+  `PluginProtocol`, `PluginContext`, `PluginExecutor`, `PluginInstallResult`, `InstalledPlugin`,
+  `AgentKitConfig`, `McpToolDescriptor`, `McpResourceDescriptor`.
+
+- **TokenPlugin** (`src/ai/plugins/token/`, 636 lines) — 22 methods across 3 protocols:
+  - `spl-token` (11): deployToken, transfer, transferSol, getBalance, getTokenAccounts, mintTo,
+    burn, freezeAccount, thawAccount, closeAccount, rugCheck
+  - `staking` (7): stakeSOL, unstakeSOL, getStakeAccounts, stakeJupSOL, unstakeJupSOL,
+    stakeSolayer, unstakeSolayer
+  - `bridging` (4): bridgeWormhole, bridgeWormholeStatus, bridgeDeBridge, bridgeDeBridgeStatus
+
+- **NFTPlugin** (`src/ai/plugins/nft/`, 481 lines) — 19 methods across 3 protocols:
+  - `metaplex-nft` (9): deployCollection, mintNFT, updateMetadata, verifyCreator,
+    verifyCollection, setAndVerifyCollection, delegateAuthority, revokeAuthority, configureRoyalties
+  - `3land` (5): createCollection, mintAndList, listForSale, cancelListing, buyNFT
+  - `das` (5): getAsset, getAssetsByOwner, getAssetsByCreator, getAssetsByCollection, searchAssets
+
+- **DeFiPlugin** (`src/ai/plugins/defi/`, 1,466 lines) — 43 methods across 10 protocols:
+  - `pump` (2): launchToken, trade
+  - `raydium-pools` (5): createCPMM, createCLMM, createAMMv4, addLiquidity, removeLiquidity
+  - `orca` (5): getWhirlpool, swap, openPosition, closePosition, collectFees
+  - `manifest` (4): createMarket, placeLimitOrder, cancelOrder, getOrderbook
+  - `meteora` (5): createDynamicPool, createDLMMPool, addDLMMLiquidity, removeDLMMLiquidity,
+    createAlphaVault
+  - `openbook` (3): createMarket, placeOrder, cancelOrder
+  - `drift` (7): deposit, withdraw, openPerpPosition, closePerpPosition, getPositions, lend, borrow
+  - `adrena` (5): openPosition, closePosition, addCollateral, removeCollateral, getPositions
+  - `lulo` (4): deposit, withdraw, getBestRates, getPositions
+  - `jito` (3): sendBundle, getBundleStatus, getTipEstimate
+
+- **MiscPlugin** (`src/ai/plugins/misc/`, 1,001 lines) — 20 methods across 6 protocols:
+  - `sns` (3): registerDomain, resolveDomain, reverseLookup — via Bonfida API
+  - `alldomains` (3): registerDomain, resolveDomain, getOwnedDomains
+  - `pyth` (3): getPrice, getPriceHistory, listPriceFeeds — via Hermes API
+  - `coingecko` (6): getTokenPrice, getTrending, getTopGainersLosers, getTokenInfo,
+    getPoolsByToken, getOHLCV — supports free + Pro API key
+  - `gibwork` (3): createBounty, listBounties, submitWork
+  - `send-arcade` (2): listGames, playGame
+
+- **BlinksPlugin** (`src/ai/plugins/blinks/`, 390 lines) — 6 methods (Solana Actions spec):
+  - getAction, executeAction, confirmAction, resolveBlinkUrl, validateActionsJson, buildActionUrl
+  - Pure HTTP executor — no RPC transport needed
+
+#### MCP Module (`src/ai/mcp/`) — 1,810 lines of new code
+
+Full Model Context Protocol (spec 2024-11-05) implementation with **zero external MCP
+dependencies**. Works as both server and client.
+
+- **`SynapseMcpServer`** (`src/ai/mcp/server.ts`, 762 lines) — Exposes any `SynapseAgentKit`
+  as a fully spec-compliant MCP server:
+  - **stdio transport**: Reads newline-delimited JSON-RPC from stdin, writes to stdout.
+    Compatible with Claude Desktop, Cursor, VS Code, Cline.
+  - **SSE transport**: HTTP server with `/mcp/sse` (EventSource), `/mcp/message` (POST),
+    `/mcp/health` (GET) endpoints.
+  - Full MCP spec dispatch: `initialize`, `tools/list`, `tools/call`, `resources/list`,
+    `resources/read`, `resources/templates/list`, `prompts/list`, `prompts/get`, `ping`,
+    `completion/complete`, `logging/setLevel`.
+  - Deep `zodToMcpSchema()` converter: handles ZodString (with checks), ZodNumber, ZodBoolean,
+    ZodArray, ZodObject (with required), ZodEnum, ZodOptional, ZodDefault, ZodNullable,
+    ZodRecord, ZodTuple, ZodLiteral, ZodUnion.
+  - `McpServerError` class for structured JSON-RPC error responses.
+  - `info()` introspection method.
+
+- **`McpClientBridge`** (`src/ai/mcp/client.ts`, 752 lines) — Connects to external MCP servers
+  and imports their tools:
+  - **stdio transport**: Spawns child processes (e.g. `npx -y @modelcontextprotocol/server-github`).
+  - **SSE transport**: Connects to HTTP SSE endpoints with session management.
+  - `connect(config)` / `disconnect(id)` / `disconnectAll()` — lifecycle management.
+  - `getTools()` — Returns LangChain `StructuredTool[]` from all connected servers.
+  - `getServerTools(id)` — Tools from a specific server.
+  - `callTool(serverId, name, args)` / `readResource(serverId, uri)` — direct access.
+  - `toPlugin()` — Converts to `SynapsePlugin` for `.use()` chaining on `SynapseAgentKit`.
+  - Runtime `jsonSchemaToZod()` converter for external tool input schemas.
+  - `getAllStatuses()` / `getAllToolDefinitions()` — introspection.
+
+- **MCP types** (`src/ai/mcp/types.ts`, 256 lines) — Complete protocol type definitions:
+  `JsonRpcRequest`, `JsonRpcResponse`, `JsonRpcNotification`, `McpToolDefinition`,
+  `McpToolCallParams`, `McpToolCallResult`, `McpResourceDefinition`, `McpResourceTemplate`,
+  `McpPromptDefinition`, `McpPromptMessage`, `McpServerInfo`, `McpCapabilities`, `McpTransport`,
+  `McpServerConfig`, `McpExternalServerConfig`, `McpConnectionStatus`.
+
+- **Constants**: `MCP_PROTOCOL_VERSION = '2024-11-05'`, `MCP_JSONRPC_VERSION = '2.0'`.
+
+#### Documentation
+
+- **`docs_md/10_PLUGINS.md`** — Full plugin system guide: quick start (LangChain, Vercel AI),
+  selective loading, complete tool catalog (all 110 methods), architecture diagrams, custom
+  plugin creation, read vs write operations, introspection API.
+- **`docs_md/11_MCP.md`** — Full MCP guide: stdio/SSE server setup, Claude Desktop & Cursor
+  config examples, client bridge (GitHub/Postgres/filesystem), combined server+client pattern,
+  all config interfaces, JSON Schema ↔ Zod conversion.
+- **README.md updated** — Version 2.0.0, new architecture diagram showing plugin system + MCP,
+  two new sections (Plugin System, MCP), updated source map, updated package exports table.
+- **Cross-references** — `00_SYNAPSE_CLIENT_SDK.md`, `03_AI_TOOLS.md`, `09_PIPELINES.md`
+  updated with links to new docs 10 and 11.
+
+### New subpath exports
+
+| Path | What |
+|------|------|
+| `./ai/plugins` | `SynapseAgentKit` + all 5 plugins + types |
+| `./ai/plugins/token` | `TokenPlugin` (22 tools) |
+| `./ai/plugins/nft` | `NFTPlugin` (19 tools) |
+| `./ai/plugins/defi` | `DeFiPlugin` (43 tools) |
+| `./ai/plugins/misc` | `MiscPlugin` (20 tools) |
+| `./ai/plugins/blinks` | `BlinksPlugin` (6 tools) |
+| `./ai/mcp` | `SynapseMcpServer` + `McpClientBridge` + types |
+
+### New types
+
+- Plugin system: `SynapsePlugin`, `PluginMeta`, `PluginProtocol`, `PluginContext`,
+  `PluginExecutor`, `PluginInstallResult`, `InstalledPlugin`, `AgentKitConfig`,
+  `McpToolDescriptor`, `McpResourceDescriptor`
+- MCP: `JsonRpcRequest`, `JsonRpcResponse`, `JsonRpcNotification`, `McpToolDefinition`,
+  `McpToolCallParams`, `McpToolCallResult`, `McpResourceDefinition`, `McpResourceTemplate`,
+  `McpPromptDefinition`, `McpPromptMessage`, `McpServerInfo`, `McpCapabilities`, `McpTransport`,
+  `McpServerConfig`, `McpExternalServerConfig`, `McpConnectionStatus`
+
+### Fixed
+
+- **`transport.call()` → `transport.request()`** — Token, DeFi, and Misc plugin executors
+  were calling `transport.call()` which does not exist on `HttpTransport`. Fixed to use
+  `transport.request()` (9 occurrences across 3 files).
+- **Registry mock client mismatch** — `SynapseAgentKit._context` was exposing the transport
+  via `getTransport()` method, but `SynapseClientLike` (and the NFT plugin) expect a
+  `.transport` property. Fixed to expose both `.transport` and `.getTransport()`.
+
+### Changed
+
+- Package description updated to mention 110+ plugin tools and MCP.
+- `src/ai/index.ts` barrel updated with plugin system + MCP re-exports.
+- Total AI tool count: **86 protocol tools** (from v1.2.0) + **110 plugin tools** + **MCP**
+  = **196+ tools** available to AI agents.
+- Total source files in plugin system + MCP: **17 files**, **6,469 lines**.
+
+---
+
 ## [1.2.2] — 2026-03-02
 
 ### Added
@@ -499,6 +721,9 @@ The following failures are **not SDK bugs** — they require server-side fixes o
 
 ---
 
+[2.0.0]: https://github.com/oobe-protocol-labs/synapse-client-sdk/compare/v1.2.2...v2.0.0
+[1.2.2]: https://github.com/oobe-protocol-labs/synapse-client-sdk/compare/v1.2.1...v1.2.2
+[1.2.1]: https://github.com/oobe-protocol-labs/synapse-client-sdk/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/oobe-protocol-labs/synapse-client-sdk/compare/v1.0.8...v1.2.0
 [1.0.8]: https://github.com/oobe-protocol-labs/synapse-client-sdk/compare/v1.0.7...v1.0.8
 [1.0.7]: https://github.com/oobe-protocol-labs/synapse-client-sdk/compare/v1.0.6...v1.0.7