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

package/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

package/README.md

@@ -2,12 +2,13 @@
 
 Typed Solana RPC gateway SDK for Node.js and the browser.
 Covers JSON-RPC, WebSocket PubSub, gRPC/Geyser streaming, DAS (Digital Asset Standard),
-AI agent tooling (LangChain + Zod), and the x402 HTTP payment protocol --
+AI agent tooling (LangChain + Zod), a modular plugin system (110+ on-chain tools),
+MCP (Model Context Protocol) server & client bridge, and the x402 HTTP payment protocol —
 all behind a single `SynapseClient` entry point.
 
 | | |
 |-|-|
-| **Version** | 1.0.1 |
+| **Version** | 2.0.0 |
 | **License** | MIT |
 | **Node** | >= 18.0.0 |
 | **TypeScript** | >= 5.0 |
@@ -35,12 +36,14 @@ all behind a single `SynapseClient` entry point.
    - [Protocol Tools (Jupiter, Raydium, Metaplex)](#protocol-tools)
    - [Agent Commerce Gateway](#agent-commerce-gateway)
    - [x402 Payment Protocol](#x402-payment-protocol)
-8. [Testing](#testing)
-9. [Build and Development](#build-and-development)
-10. [Package Exports](#package-exports)
-11. [Documentation](#documentation)
-12. [Contributing](#contributing)
-13. [License](#license)
+8. [Plugin System (SynapseAgentKit)](#plugin-system-synapseagentkit)
+9. [MCP (Model Context Protocol)](#mcp-model-context-protocol)
+10. [Testing](#testing)
+11. [Build and Development](#build-and-development)
+12. [Package Exports](#package-exports)
+13. [Documentation](#documentation)
+14. [Contributing](#contributing)
+15. [License](#license)
 
 ---
 
@@ -112,14 +115,34 @@ const client = SynapseClient.fromEndpoint({
 ```
 SynapseClient
  |
- |-- .rpc        SolanaRpc          53 JSON-RPC methods (lazy-loaded)
- |-- .das        DasClient          11 DAS/Metaplex Read API methods
- |-- .ws         WsClient           WebSocket PubSub subscriptions
- |-- .grpc       GrpcTransport      gRPC unary calls + Geyser parser
+ |-- .rpc           SolanaRpc          53 JSON-RPC methods (lazy-loaded)
+ |-- .das           DasClient          11 DAS/Metaplex Read API methods
+ |-- .ws            WsClient           WebSocket PubSub subscriptions
+ |-- .grpc          GrpcTransport      gRPC unary calls + Geyser parser
  |
- |-- call()      Raw JSON-RPC call
- |-- batch()     Batched JSON-RPC calls
- |-- destroy()   Tear down all connections
+ |-- call()         Raw JSON-RPC call
+ |-- batch()        Batched JSON-RPC calls
+ |-- destroy()      Tear down all connections
+
+SynapseAgentKit                         ← Plugin system (v2)
+ |
+ |-- .use(Plugin)   Chainable plugin loader
+ |-- .getTools()    LangChain StructuredTool[] (all plugins)
+ |-- .getVercelAITools()   Vercel AI SDK tools
+ |-- .getMcpToolDescriptors()  MCP-shaped descriptors
+ |
+ |-- Plugins:       Token (22) · NFT (19) · DeFi (43) · Misc (20) · Blinks (6)
+
+SynapseMcpServer                        ← MCP server
+ |
+ |-- start()        stdio transport (Claude Desktop, Cursor)
+ |-- startSse()     SSE transport (web clients)
+
+McpClientBridge                         ← MCP client
+ |
+ |-- connect()      Connect to external MCP servers
+ |-- getTools()     LangChain tools from remote servers
+ |-- toPlugin()     Convert to .use()-able plugin
 ```
 
 Sub-clients are initialized on first property access.
@@ -199,7 +222,7 @@ Requires `@grpc/grpc-js` and `@grpc/proto-loader` as optional peer dependencies.
 
 ### ai/
 
-AI agent commerce layer. Zod schemas, LangChain tools, protocol integrations, gateway, x402.
+AI agent layer. Zod schemas, LangChain tools, protocol integrations, gateway, x402, plugin system, MCP.
 
 | File | Purpose |
 |------|---------|
@@ -221,6 +244,16 @@ AI agent commerce layer. Zod schemas, LangChain tools, protocol integrations, ga
 | `src/ai/gateway/x402/client.ts` | `X402BuyerClient` -- buyer-side payment header construction. |
 | `src/ai/gateway/x402/facilitator.ts` | `FacilitatorClient` -- on-chain settlement verification. |
 | `src/ai/gateway/x402/registry.ts` | `FACILITATOR_REGISTRY` -- pre-configured endpoints for known facilitators (PayAI, Dexter, RelAI, CDP). |
+| `src/ai/plugins/types.ts` | Plugin system core types: `SynapsePlugin`, `PluginMeta`, `PluginProtocol`, `PluginContext`, `PluginExecutor`. |
+| `src/ai/plugins/registry.ts` | `SynapseAgentKit` class — chainable `.use()`, multi-format tool export (LangChain, Vercel AI, MCP). |
+| `src/ai/plugins/token/` | Token plugin: 22 methods (SPL tokens, staking, bridging). |
+| `src/ai/plugins/nft/` | NFT plugin: 19 methods (Metaplex, 3Land, DAS). |
+| `src/ai/plugins/defi/` | DeFi plugin: 43 methods (Pump, Raydium, Orca, Manifest, Meteora, OpenBook, Drift, Adrena, Lulo, Jito). |
+| `src/ai/plugins/misc/` | Misc plugin: 20 methods (SNS, AllDomains, Pyth, CoinGecko, GibWork, Send Arcade). |
+| `src/ai/plugins/blinks/` | Blinks plugin: 6 methods (Solana Actions spec). |
+| `src/ai/mcp/types.ts` | MCP protocol types (JSON-RPC, tools, resources, prompts, transports). |
+| `src/ai/mcp/server.ts` | `SynapseMcpServer` — expose SynapseAgentKit as MCP server (stdio + SSE). |
+| `src/ai/mcp/client.ts` | `McpClientBridge` — connect to external MCP servers, import tools. |
 
 ### utils/
 
@@ -375,6 +408,143 @@ const solanaFacilitators = findFacilitatorsByNetwork('solana:5eykt4UsFv8P8NJdTRE
 
 ---
 
+## Plugin System (SynapseAgentKit)
+
+The v2 plugin system provides **110 Solana-native tools** across 5 plugins and 18 protocols, all composable via a chainable `.use()` API:
+
+```ts
+import {
+  SynapseAgentKit,
+  TokenPlugin, NFTPlugin, DeFiPlugin, MiscPlugin, BlinksPlugin,
+} from '@oobe-protocol-labs/synapse-client-sdk/ai/plugins';
+
+const kit = new SynapseAgentKit({ rpcUrl: process.env.RPC_URL! })
+  .use(TokenPlugin)
+  .use(NFTPlugin)
+  .use(DeFiPlugin)
+  .use(MiscPlugin)
+  .use(BlinksPlugin);
+
+// LangChain
+const tools = kit.getTools();            // StructuredTool[] (110 tools)
+
+// Vercel AI SDK
+const vercelTools = kit.getVercelAITools();
+
+// MCP descriptors
+const mcpTools = kit.getMcpToolDescriptors();
+
+// Introspection
+console.log(kit.summary());
+// → { plugins: 5, protocols: 18, tools: 110, resources: [...] }
+```
+
+### Plugin catalog
+
+| Plugin | Protocols | Tools | Coverage |
+|--------|-----------|-------|----------|
+| **TokenPlugin** | `spl-token`, `staking`, `bridging` | 22 | Deploy, transfer, mint, burn, freeze, stake (SOL/JupSOL/Solayer), bridge (Wormhole/deBridge) |
+| **NFTPlugin** | `metaplex-nft`, `3land`, `das` | 19 | Deploy collections, mint, update metadata, verify, 3Land marketplace, DAS queries |
+| **DeFiPlugin** | `pump`, `raydium-pools`, `orca`, `manifest`, `meteora`, `openbook`, `drift`, `adrena`, `lulo`, `jito` | 43 | AMM/CLMM pools, swaps, limit orders, perps, lending, MEV bundles |
+| **MiscPlugin** | `sns`, `alldomains`, `pyth`, `coingecko`, `gibwork`, `send-arcade` | 20 | Domain resolution (SNS/AllDomains), oracle prices, market data, bounties, gaming |
+| **BlinksPlugin** | `blinks` | 6 | Solana Actions spec: GET/POST actions, resolve dial.to, validate actions.json |
+
+### Custom plugins
+
+```ts
+import { SynapsePlugin, PluginContext } from '@oobe-protocol-labs/synapse-client-sdk/ai/plugins';
+import { createMethodRegistry } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+import { z } from 'zod';
+
+const MyPlugin: SynapsePlugin = {
+  meta: { id: 'my-plugin', name: 'My Plugin', version: '1.0.0' },
+  protocols: [{
+    id: 'my-protocol',
+    name: 'My Protocol',
+    methods: createMethodRegistry('my-protocol').methods,
+    requiresClient: true,
+  }],
+  install(context: PluginContext) {
+    return {
+      executor: async (method, input) => {
+        const transport = context.client.transport;
+        return transport.request(method.name, [input]);
+      },
+    };
+  },
+};
+
+kit.use(MyPlugin);
+```
+
+See [10_PLUGINS.md](./docs_md/10_PLUGINS.md) for the full plugin guide.
+
+---
+
+## MCP (Model Context Protocol)
+
+The SDK is a fully spec-compliant MCP server and client — zero external MCP dependencies.
+
+### Expose tools as MCP server
+
+```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);
+
+// stdio transport — Claude Desktop, Cursor, VS Code
+const server = new SynapseMcpServer(kit, {
+  name: 'synapse-solana',
+  version: '2.0.0',
+});
+await server.start();
+
+// OR SSE transport — web-based MCP clients
+await server.startSse({ port: 3001 });
+```
+
+### Connect to external MCP servers
+
+```ts
+import { McpClientBridge } from '@oobe-protocol-labs/synapse-client-sdk/ai/mcp';
+
+const bridge = new McpClientBridge();
+
+// Connect to GitHub MCP server
+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_',
+});
+
+// Connect to Postgres MCP server
+await bridge.connect({
+  id: 'postgres',
+  name: 'PostgreSQL',
+  transport: 'stdio',
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-postgres', process.env.DATABASE_URL!],
+  toolPrefix: 'pg_',
+});
+
+// Get LangChain tools from all connected servers
+const remoteTools = bridge.getTools();
+
+// Or add as a plugin to SynapseAgentKit
+kit.use(bridge.toPlugin());
+```
+
+See [11_MCP.md](./docs_md/11_MCP.md) for the full MCP guide.
+
+---
+
 ## Testing
 
 The project uses [Vitest](https://vitest.dev/) with 378 tests across 10 suites.
@@ -455,7 +625,14 @@ The package exposes granular entry points for consumers that need only a subset:
   "./grpc":       "GrpcTransport + Geyser parser",
   "./das":        "DasClient + 11 DAS method functions",
   "./websocket":  "WsClient + subscription types",
-  "./utils":      "Helpers + endpoint resolution"
+  "./utils":      "Helpers + endpoint resolution",
+  "./ai/plugins": "SynapseAgentKit + all 5 plugins",
+  "./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":     "MCP server + client bridge"
 }
 ```
 
@@ -473,6 +650,12 @@ import { getBalance } from '@oobe-protocol-labs/synapse-client-sdk/rpc';
 
 // WebSocket only
 import { WsClient } from '@oobe-protocol-labs/synapse-client-sdk/websocket';
+
+// Plugin system (110 Solana-native tools)
+import { SynapseAgentKit, TokenPlugin, DeFiPlugin } from '@oobe-protocol-labs/synapse-client-sdk/ai/plugins';
+
+// MCP server + client
+import { SynapseMcpServer, McpClientBridge } from '@oobe-protocol-labs/synapse-client-sdk/ai/mcp';
 ```
 
 ---
@@ -485,8 +668,26 @@ import { WsClient } from '@oobe-protocol-labs/synapse-client-sdk/websocket';
 | Changelog | [CHANGELOG.md](./CHANGELOG.md) |
 | Contributing guide | [CONTRIBUTING.md](./CONTRIBUTING.md) |
 | AI skill guides | `src/ai/skills/` (10 markdown files) |
+| Architecture guides | `docs_md/` (11 markdown files) |
 | Example scripts | `examples/` |
 
+Architecture guides (in `docs_md/`):
+
+| File | Topic |
+|------|-------|
+| `00_SYNAPSE_CLIENT_SDK.md` | SDK overview and design philosophy |
+| `01_CORE.md` | Core client, transport, branded types |
+| `02_RPC.md` | 53 Solana JSON-RPC methods |
+| `03_AI_TOOLS.md` | LangChain tools + protocol factories |
+| `04_AI_GATEWAY.md` | Agent commerce, sessions, x402 payments |
+| `05_SAP.md` | Synapse Anchor Protocol |
+| `06_INTENTS.md` | Cross-protocol intent resolver |
+| `07_ACTIONS_BLINKS.md` | Solana Actions server + Blink generator |
+| `08_PERSISTENCE.md` | State persistence layer |
+| `09_PIPELINES.md` | End-to-end integration patterns |
+| `10_PLUGINS.md` | Plugin system (SynapseAgentKit) |
+| `11_MCP.md` | MCP server + client bridge |
+
 Skill guides (in `src/ai/skills/`):
 
 | File | Topic |
@@ -558,6 +759,18 @@ src/
         client.ts                 Buyer-side client
         facilitator.ts            Settlement verification
         registry.ts               Known facilitators
+    plugins/
+      types.ts                    Plugin system core types
+      registry.ts                 SynapseAgentKit (.use() chainable)
+      token/                      Token plugin (22 methods)
+      nft/                        NFT plugin (19 methods)
+      defi/                       DeFi plugin (43 methods, 10 protocols)
+      misc/                       Misc plugin (20 methods, 6 protocols)
+      blinks/                     Blinks plugin (6 methods)
+    mcp/
+      types.ts                    MCP protocol types (JSON-RPC 2.0)
+      server.ts                   SynapseMcpServer (stdio + SSE)
+      client.ts                   McpClientBridge (external servers)
     skills/                       10 markdown skill guides
   utils/
     helpers.ts                    lamportsToSol, sleep, chunk, retry