@oobe-protocol-labs/synapse-client-sdk 1.2.1 → 2.0.0

package/CHANGELOG.md

@@ -7,6 +7,253 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.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
+
+- **`toJsonSafe()` & `bigIntReplacer()`** — Recursive BigInt→string serializer and
+  `JSON.stringify` replacer. Eliminates the "Do not know how to serialize a BigInt"
+  crash in Next.js API Routes and Express handlers.
+  (`import { toJsonSafe, bigIntReplacer } from '…/utils'`)
+
+- **`createSingleton()`** — HMR-safe singleton factory using `globalThis.__synapse_singletons`.
+  Survives Next.js / Vite hot-module reloads in development. Supports `version` option
+  for cache invalidation.
+  (`import { createSingleton } from '…/utils'`)
+
+- **`client.getTransport()`** — Public accessor for the underlying `HttpTransport`,
+  replacing the `(client as any)._transport` pattern.
+
+- **`gateway.snapshot(depth?)`** — JSON-safe serialization of the entire AgentGateway
+  state with three depth levels: `'minimal'`, `'standard'`, `'full'`.
+  Also adds `gateway.toJSON()` enabling `JSON.stringify(gateway)`.
+
+- **`gateway.createPaymentIntent(opts)`** — Builder for `PaymentIntent` objects with
+  auto-generated nonce, timestamp, token. Accepts buyer as `AgentId`, string, or
+  `AgentGateway` instance.
+
+- **Retry on `gateway.execute()`** — Configurable retry with exponential backoff via
+  `RetryConfig`. Supports per-call overrides, transient error detection, and optional
+  fallback to direct RPC on the last attempt. Emits `call:retry` events.
+
+- **x402 pipeline hooks & observability** — `executeWithX402()` now emits granular
+  `x402:pipeline:*` events for each pipeline step (paywall → verify → execute → settle).
+  Accepts `onStep` callback and returns full pipeline trace with per-step timing.
+
+- **`AgentRegistry`** — Multi-agent lifecycle manager with CRUD, `filter()`,
+  `searchMarketplace()`, `getAggregateMetrics()`, `snapshot()`, pluggable persistence
+  via `PersistenceAdapter`, and `[Symbol.iterator]` support.
+
+- **`FacilitatorDiscovery`** — Runtime-aware facilitator discovery wrapping the static
+  `FACILITATOR_REGISTRY`. Adds `filter()`, `query()`, `healthCheck()`, and `findBest()`
+  with optional health-check-based selection and gas-sponsoring preference.
+
+- **Persistence module (`ai/persistence`)** — Full long-term storage layer for agent
+  gateway data:
+  - `MemoryStore` — in-process, for testing and dev
+  - `RedisPersistence` — Redis/Valkey adapter (ioredis, node-redis, @upstash/redis)
+  - `PostgresPersistence` — PostgreSQL adapter with auto-migration (pg, @vercel/postgres,
+    @neondatabase/serverless)
+  - Universal `PersistenceStore` interface covering agents, sessions, receipts, metrics,
+    and generic key-value with TTL
+  - All adapters implement `PersistenceAdapter` for drop-in use with `AgentRegistry`
+  - Helpers: `serialize()`, `deserialize()`, `buildKey()`, `buildSchema()` (DDL generator)
+  - New optional peer deps: `ioredis >=5.0.0`, `pg >=8.0.0`
+
+- **Next.js integration (`./next`)** — Drop-in helpers for App Router:
+  - `synapseResponse(data)` — BigInt-safe `Response` factory
+  - `withSynapseError(handler)` — API Route error boundary
+  - `createSynapseProvider(config)` — HMR-safe SynapseClient singleton
+  - `createGatewayProvider(clientProvider, configFactory)` — HMR-safe AgentGateway singleton
+
+### New types
+
+- `RetryConfig`, `SnapshotDepth`, `GatewaySnapshot`, `X402PipelineStep`
+- `SessionRecord`, `ReceiptRecord`, `MetricPoint`, `PersistenceStore`
+- `RedisLike`, `PgLike`, `RedisStoreConfig`, `PostgresStoreConfig`, `MemoryStoreConfig`
+- `FacilitatorHealthResult`, `FindBestOptions`, `AgentRegistryConfig`
+- `SynapseResponseInit`, `SingletonOptions`
+
+### New subpath exports
+
+- `@oobe-protocol-labs/synapse-client-sdk/next`
+- `@oobe-protocol-labs/synapse-client-sdk/ai/persistence`
+
+---
+
 ## [1.2.1] — 2025-07-22
 
 ### Fixed
@@ -425,6 +672,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