@catalyst-team/poly-mcp 0.1.0

package/README.md

@@ -0,0 +1,317 @@
+# @catalyst-team/poly-mcp
+
+A Model Context Protocol (MCP) server that exposes Polymarket functionality to AI agents.
+
+## Installation
+
+### From npm (after publishing)
+
+```bash
+npm install -g @catalyst-team/poly-mcp
+# or
+pnpm add -g @catalyst-team/poly-mcp
+```
+
+### From source
+
+```bash
+# Build the packages
+pnpm -F @catalyst-team/poly-sdk build
+pnpm -F @catalyst-team/poly-mcp build
+```
+
+## Publishing
+
+```bash
+# 1. Build both packages
+pnpm -F @catalyst-team/poly-sdk build
+pnpm -F @catalyst-team/poly-mcp build
+
+# 2. Publish poly-sdk first (poly-mcp depends on it)
+pnpm -F @catalyst-team/poly-sdk publish --access public
+
+# 3. Publish poly-mcp
+pnpm -F @catalyst-team/poly-mcp publish --access public
+```
+
+**Note**: Publishing requires npm 2FA authentication.
+
+## MCP Configuration
+
+### After npm publish (recommended)
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+#### Read-only mode (market data, orderbook, trader analysis)
+
+```json
+{
+  "mcpServers": {
+    "polymarket": {
+      "command": "npx",
+      "args": ["@catalyst-team/poly-mcp"]
+    }
+  }
+}
+```
+
+#### Trading mode (with private key)
+
+```json
+{
+  "mcpServers": {
+    "polymarket": {
+      "command": "npx",
+      "args": ["@catalyst-team/poly-mcp"],
+      "env": {
+        "POLY_PRIVATE_KEY": "your-wallet-private-key"
+      }
+    }
+  }
+}
+```
+
+### Local development
+
+#### Read-only mode
+
+```json
+{
+  "mcpServers": {
+    "polymarket": {
+      "command": "node",
+      "args": ["/path/to/PerdictionRouter/packages/poly-mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+#### Trading mode
+
+```json
+{
+  "mcpServers": {
+    "polymarket": {
+      "command": "node",
+      "args": ["/path/to/PerdictionRouter/packages/poly-mcp/dist/server.js"],
+      "env": {
+        "POLY_PRIVATE_KEY": "your-wallet-private-key"
+      }
+    }
+  }
+}
+```
+
+#### Development mode (with hot reload)
+
+```json
+{
+  "mcpServers": {
+    "polymarket": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/PerdictionRouter/packages/poly-mcp/src/server.ts"],
+      "env": {
+        "POLY_PRIVATE_KEY": "your-wallet-private-key"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `POLY_PRIVATE_KEY` | Wallet private key (with or without 0x prefix) | For trading |
+| `POLY_CHAIN_ID` | Chain ID (137=mainnet, 80002=testnet) | Optional (default: 137) |
+
+**Note**: API credentials are automatically derived from the private key using Polymarket's `createOrDeriveApiKey()`. You only need to provide the wallet private key to enable trading.
+
+## Available Tools
+
+### Trader Tools (public data)
+
+| Tool | Description |
+|------|-------------|
+| `get_trader_positions` | Get current positions for a wallet address |
+| `get_trader_trades` | Get trade history for a wallet |
+| `get_trader_profile` | Get trader profile with PnL and stats |
+| `get_leaderboard` | Get top traders from leaderboard |
+
+### Market Tools (public data)
+
+| Tool | Description |
+|------|-------------|
+| `get_market` | Get market details by slug or conditionId |
+| `search_markets` | Search markets by keyword |
+| `get_trending_markets` | Get trending markets by volume/liquidity |
+| `get_market_trades` | Get recent trades for a market |
+
+### Order Tools (public data)
+
+| Tool | Description |
+|------|-------------|
+| `get_orderbook` | Get orderbook depth for a market outcome |
+| `get_best_prices` | Get best bid/ask prices for both outcomes |
+| `estimate_execution` | Estimate execution price and slippage |
+
+### Trade Tools (requires private key)
+
+| Tool | Description |
+|------|-------------|
+| `place_limit_order` | Place a limit order |
+| `place_market_order` | Place a market order |
+| `cancel_order` | Cancel an existing order |
+| `get_my_orders` | Get your open orders |
+
+### Wallet Tools
+
+| Tool | Description | Requires Key |
+|------|-------------|--------------|
+| `get_supported_deposit_assets` | Get all supported assets and chains for deposits | No |
+| `get_deposit_addresses` | Get deposit addresses (EVM, Solana, Bitcoin) | Yes |
+| `deposit_usdc` | Deposit USDC to Polymarket | Yes |
+| `check_allowances` | Check ERC20 and ERC1155 allowances for trading | Yes |
+| `approve_trading` | Set up all required approvals for trading | Yes |
+| `swap` | Swap tokens on Polygon via QuickSwap V3 | Yes |
+| `swap_and_deposit` | Swap to USDC and deposit in one operation | Yes |
+| `get_token_balances` | Get your wallet token balances | Yes |
+| `get_wallet_balances` | Get any wallet's token balances | No |
+| `get_swap_quote` | Get a swap quote (check route availability) | No |
+| `get_available_pools` | Get available QuickSwap V3 pools | No |
+
+## Tool Examples
+
+### Get Market
+
+```json
+{
+  "name": "get_market",
+  "arguments": {
+    "identifier": "will-bitcoin-hit-100k-in-2024"
+  }
+}
+```
+
+Response:
+```json
+{
+  "market": {
+    "conditionId": "0x...",
+    "question": "Will Bitcoin hit $100k in 2024?",
+    "slug": "will-bitcoin-hit-100k-in-2024"
+  },
+  "prices": {
+    "yes": 0.65,
+    "no": 0.35
+  },
+  "stats": {
+    "volume": 1500000,
+    "liquidity": 250000
+  }
+}
+```
+
+### Get Trader Positions
+
+```json
+{
+  "name": "get_trader_positions",
+  "arguments": {
+    "address": "0x1234..."
+  }
+}
+```
+
+### Get Swap Quote
+
+```json
+{
+  "name": "get_swap_quote",
+  "arguments": {
+    "tokenIn": "MATIC",
+    "tokenOut": "USDC",
+    "amount": "100"
+  }
+}
+```
+
+Response:
+```json
+{
+  "tokenIn": "MATIC",
+  "tokenOut": "USDC",
+  "amountIn": "100",
+  "amountOut": "55.23",
+  "route": "MATIC → WETH → USDC (multi-hop)",
+  "priceImpact": "0.15%"
+}
+```
+
+## Programmatic Usage
+
+```typescript
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
+import { createMcpHandler } from '@catalyst-team/poly-mcp';
+
+const sdk = new PolymarketSDK();
+const handler = createMcpHandler(sdk);
+
+// Call any tool
+const result = await handler('get_market', {
+  identifier: 'btc-100k',
+});
+
+console.log(result);
+```
+
+Or register with an MCP server instance:
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
+import { registerMcpTools } from '@catalyst-team/poly-mcp';
+
+const server = new Server(
+  { name: 'my-server', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+const sdk = new PolymarketSDK();
+registerMcpTools(server, sdk);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## Architecture
+
+```
+packages/poly-mcp/
+├── src/
+│   ├── index.ts          # Main exports and handler factory
+│   ├── server.ts         # Standalone MCP server (CLI entry point)
+│   ├── types.ts          # TypeScript type definitions
+│   ├── errors.ts         # Error handling utilities
+│   └── tools/
+│       ├── index.ts      # Tool exports
+│       ├── trader.ts     # Trader analysis tools
+│       ├── market.ts     # Market discovery tools
+│       ├── order.ts      # Orderbook analysis tools
+│       ├── trade.ts      # Trading execution tools
+│       ├── wallet.ts     # Deposit and authorization tools
+│       └── guide.ts      # Usage guide tool
+├── docs/
+│   └── 01-mcp.md         # Detailed MCP design document
+├── package.json
+└── README.md
+```
+
+## Related Packages
+
+- `@catalyst-team/poly-sdk` - Core SDK for Polymarket APIs (required dependency)
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MCP Error Handling for Polymarket Tools
+ */
+export declare enum ErrorCode {
+    INVALID_ADDRESS = "INVALID_ADDRESS",
+    MARKET_NOT_FOUND = "MARKET_NOT_FOUND",
+    INSUFFICIENT_BALANCE = "INSUFFICIENT_BALANCE",
+    ORDER_REJECTED = "ORDER_REJECTED",
+    RATE_LIMITED = "RATE_LIMITED",
+    AUTH_REQUIRED = "AUTH_REQUIRED",
+    INVALID_INPUT = "INVALID_INPUT",
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+export declare class McpToolError extends Error {
+    code: ErrorCode;
+    details?: Record<string, unknown> | undefined;
+    constructor(code: ErrorCode, message: string, details?: Record<string, unknown> | undefined);
+    toResponse(): {
+        error: {
+            code: ErrorCode;
+            message: string;
+            details: Record<string, unknown> | undefined;
+        };
+    };
+}
+export declare function validateAddress(address: string): void;
+export declare function validateConditionId(conditionId: string): void;
+export declare function validateOutcome(outcome: string): void;
+export declare function validateSide(side: string): void;
+export declare function validatePrice(price: number): void;
+export declare function validatePositiveNumber(value: number, name: string): void;
+export declare function wrapError(err: unknown): McpToolError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,oBAAY,SAAS;IACnB,eAAe,oBAAoB;IACnC,gBAAgB,qBAAqB;IACrC,oBAAoB,yBAAyB;IAC7C,cAAc,mBAAmB;IACjC,YAAY,iBAAiB;IAC7B,aAAa,kBAAkB;IAC/B,aAAa,kBAAkB;IAC/B,cAAc,mBAAmB;CAClC;AAED,qBAAa,YAAa,SAAQ,KAAK;IAE5B,IAAI,EAAE,SAAS;IAEf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjC,IAAI,EAAE,SAAS,EACtB,OAAO,EAAE,MAAM,EACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;IAM1C,UAAU;;;;;;;CASX;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAcrD;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAc7D;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAQrD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQ/C;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAQjD;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAQxE;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAepD"}

package/dist/errors.js

@@ -0,0 +1,86 @@
+/**
+ * MCP Error Handling for Polymarket Tools
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["INVALID_ADDRESS"] = "INVALID_ADDRESS";
+    ErrorCode["MARKET_NOT_FOUND"] = "MARKET_NOT_FOUND";
+    ErrorCode["INSUFFICIENT_BALANCE"] = "INSUFFICIENT_BALANCE";
+    ErrorCode["ORDER_REJECTED"] = "ORDER_REJECTED";
+    ErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    ErrorCode["AUTH_REQUIRED"] = "AUTH_REQUIRED";
+    ErrorCode["INVALID_INPUT"] = "INVALID_INPUT";
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+})(ErrorCode || (ErrorCode = {}));
+export class McpToolError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'McpToolError';
+    }
+    toResponse() {
+        return {
+            error: {
+                code: this.code,
+                message: this.message,
+                details: this.details,
+            },
+        };
+    }
+}
+export function validateAddress(address) {
+    if (!address || typeof address !== 'string') {
+        throw new McpToolError(ErrorCode.INVALID_ADDRESS, 'Address is required');
+    }
+    if (!address.startsWith('0x') || address.length !== 42) {
+        throw new McpToolError(ErrorCode.INVALID_ADDRESS, 'Address must be a valid Ethereum address (0x...)', { address });
+    }
+}
+export function validateConditionId(conditionId) {
+    if (!conditionId || typeof conditionId !== 'string') {
+        throw new McpToolError(ErrorCode.INVALID_INPUT, 'Condition ID is required');
+    }
+    if (!conditionId.startsWith('0x')) {
+        throw new McpToolError(ErrorCode.INVALID_INPUT, 'Condition ID must start with 0x', { conditionId });
+    }
+}
+export function validateOutcome(outcome) {
+    if (!['Yes', 'No'].includes(outcome)) {
+        throw new McpToolError(ErrorCode.INVALID_INPUT, 'Outcome must be "Yes" or "No"', { outcome });
+    }
+}
+export function validateSide(side) {
+    if (!['BUY', 'SELL'].includes(side)) {
+        throw new McpToolError(ErrorCode.INVALID_INPUT, 'Side must be "BUY" or "SELL"', { side });
+    }
+}
+export function validatePrice(price) {
+    if (typeof price !== 'number' || price < 0.001 || price > 0.999) {
+        throw new McpToolError(ErrorCode.INVALID_INPUT, 'Price must be between 0.001 and 0.999', { price });
+    }
+}
+export function validatePositiveNumber(value, name) {
+    if (typeof value !== 'number' || value <= 0) {
+        throw new McpToolError(ErrorCode.INVALID_INPUT, `${name} must be a positive number`, { [name]: value });
+    }
+}
+export function wrapError(err) {
+    if (err instanceof McpToolError) {
+        return err;
+    }
+    if (err instanceof Error) {
+        // Check for known error types
+        if (err.message.includes('rate limit')) {
+            return new McpToolError(ErrorCode.RATE_LIMITED, 'Rate limit exceeded');
+        }
+        if (err.message.includes('not found')) {
+            return new McpToolError(ErrorCode.MARKET_NOT_FOUND, err.message);
+        }
+        return new McpToolError(ErrorCode.INTERNAL_ERROR, err.message);
+    }
+    return new McpToolError(ErrorCode.INTERNAL_ERROR, 'An unexpected error occurred');
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Polymarket MCP Server
+ *
+ * This package provides MCP (Model Context Protocol) tools for interacting with Polymarket.
+ * It can be used to build an MCP server that exposes Polymarket functionality to AI agents.
+ *
+ * Tool Categories:
+ * - Trader Tools: Analyze traders/wallets (positions, trades, profiles, leaderboard)
+ * - Market Tools: Discover and analyze markets (get, search, trending, trades)
+ * - Order Tools: Analyze orderbooks (depth, best prices, execution estimates)
+ * - Trade Tools: Execute trades (limit orders, market orders) - requires API credentials
+ * - Wallet Tools: Deposits and authorization management
+ *
+ * Usage:
+ * ```typescript
+ * import { PolymarketSDK } from '@catalyst-team/poly-sdk';
+ * import { createMcpHandler, allToolDefinitions } from '@catalyst-team/poly-mcp';
+ *
+ * const sdk = new PolymarketSDK();
+ * const handler = createMcpHandler(sdk);
+ *
+ * // Use with MCP server
+ * const result = await handler('get_trader_positions', { address: '0x...' });
+ * ```
+ */
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
+export * from './types.js';
+export * from './errors.js';
+export { allToolDefinitions } from './tools/index.js';
+export type ToolHandler = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Create an MCP tool handler for the given SDK instance
+ */
+export declare function createMcpHandler(sdk: PolymarketSDK): ToolHandler;
+/**
+ * Get all tool definitions for MCP registration
+ */
+export declare function getToolDefinitions(): import("./types.js").ToolDefinition[];
+/**
+ * MCP Server factory (for use with @modelcontextprotocol/sdk)
+ *
+ * Example usage with MCP SDK:
+ * ```typescript
+ * import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+ * import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+ * import { PolymarketSDK } from '@catalyst-team/poly-sdk';
+ * import { registerMcpTools } from '@catalyst-team/poly-mcp';
+ *
+ * const server = new Server(
+ *   { name: 'poly-mcp', version: '1.0.0' },
+ *   { capabilities: { tools: {} } }
+ * );
+ *
+ * const sdk = new PolymarketSDK();
+ * registerMcpTools(server, sdk);
+ *
+ * const transport = new StdioServerTransport();
+ * await server.connect(transport);
+ * ```
+ */
+export declare function registerMcpTools(server: any, sdk: PolymarketSDK): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAwCxD,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAGtD,MAAM,MAAM,WAAW,GAAG,CACxB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,WAAW,CAwKhE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,0CAEjC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAE9B,MAAM,EAAE,GAAG,EACX,GAAG,EAAE,aAAa,GACjB,IAAI,CA0BN"}

package/dist/index.js

@@ -0,0 +1,173 @@
+/**
+ * Polymarket MCP Server
+ *
+ * This package provides MCP (Model Context Protocol) tools for interacting with Polymarket.
+ * It can be used to build an MCP server that exposes Polymarket functionality to AI agents.
+ *
+ * Tool Categories:
+ * - Trader Tools: Analyze traders/wallets (positions, trades, profiles, leaderboard)
+ * - Market Tools: Discover and analyze markets (get, search, trending, trades)
+ * - Order Tools: Analyze orderbooks (depth, best prices, execution estimates)
+ * - Trade Tools: Execute trades (limit orders, market orders) - requires API credentials
+ * - Wallet Tools: Deposits and authorization management
+ *
+ * Usage:
+ * ```typescript
+ * import { PolymarketSDK } from '@catalyst-team/poly-sdk';
+ * import { createMcpHandler, allToolDefinitions } from '@catalyst-team/poly-mcp';
+ *
+ * const sdk = new PolymarketSDK();
+ * const handler = createMcpHandler(sdk);
+ *
+ * // Use with MCP server
+ * const result = await handler('get_trader_positions', { address: '0x...' });
+ * ```
+ */
+import { McpToolError, wrapError } from './errors.js';
+import { allToolDefinitions, 
+// Guide handlers
+createGuideHandlers, 
+// Trader handlers
+handleGetTraderPositions, handleGetTraderTrades, handleGetTraderProfile, handleGetLeaderboard, 
+// Market handlers
+handleGetMarket, handleSearchMarkets, handleGetTrendingMarkets, handleGetMarketTrades, 
+// Order handlers
+handleGetOrderbook, handleGetBestPrices, handleEstimateExecution, 
+// Trade handlers
+handlePlaceLimitOrder, handlePlaceMarketOrder, handleCancelOrder, handleGetMyOrders, 
+// Wallet handlers
+handleGetSupportedAssets, handleGetDepositAddresses, handleDepositUsdc, handleCheckAllowances, handleApproveTrading, handleSwap, handleSwapAndDeposit, handleGetTokenBalances, handleGetWalletBalances, handleGetSwapQuote, handleGetAvailablePools, } from './tools/index.js';
+// Re-export types
+export * from './types.js';
+export * from './errors.js';
+export { allToolDefinitions } from './tools/index.js';
+/**
+ * Create an MCP tool handler for the given SDK instance
+ */
+export function createMcpHandler(sdk) {
+    // Create guide handlers (no SDK dependency)
+    const guideHandlers = createGuideHandlers();
+    return async (toolName, args) => {
+        try {
+            switch (toolName) {
+                // Guide Tool - should be called FIRST
+                case 'get_usage_guide':
+                    return await guideHandlers.get_usage_guide(args);
+                // Trader Tools
+                case 'get_trader_positions':
+                    return await handleGetTraderPositions(sdk, args);
+                case 'get_trader_trades':
+                    return await handleGetTraderTrades(sdk, args);
+                case 'get_trader_profile':
+                    return await handleGetTraderProfile(sdk, args);
+                case 'get_leaderboard':
+                    return await handleGetLeaderboard(sdk, args);
+                // Market Tools
+                case 'get_market':
+                    return await handleGetMarket(sdk, args);
+                case 'search_markets':
+                    return await handleSearchMarkets(sdk, args);
+                case 'get_trending_markets':
+                    return await handleGetTrendingMarkets(sdk, args);
+                case 'get_market_trades':
+                    return await handleGetMarketTrades(sdk, args);
+                // Order Tools
+                case 'get_orderbook':
+                    return await handleGetOrderbook(sdk, args);
+                case 'get_best_prices':
+                    return await handleGetBestPrices(sdk, args);
+                case 'estimate_execution':
+                    return await handleEstimateExecution(sdk, args);
+                // Trade Tools
+                case 'place_limit_order':
+                    return await handlePlaceLimitOrder(sdk, args);
+                case 'place_market_order':
+                    return await handlePlaceMarketOrder(sdk, args);
+                case 'cancel_order':
+                    return await handleCancelOrder(sdk, args);
+                case 'get_my_orders':
+                    return await handleGetMyOrders(sdk, args);
+                // Wallet Tools
+                case 'get_supported_deposit_assets':
+                    return await handleGetSupportedAssets(sdk, args);
+                case 'get_deposit_addresses':
+                    return await handleGetDepositAddresses(sdk);
+                case 'deposit_usdc':
+                    return await handleDepositUsdc(sdk, args);
+                case 'check_allowances':
+                    return await handleCheckAllowances(sdk);
+                case 'approve_trading':
+                    return await handleApproveTrading(sdk);
+                case 'swap':
+                    return await handleSwap(sdk, args);
+                case 'swap_and_deposit':
+                    return await handleSwapAndDeposit(sdk, args);
+                case 'get_token_balances':
+                    return await handleGetTokenBalances(sdk);
+                case 'get_wallet_balances':
+                    return await handleGetWalletBalances(sdk, args);
+                case 'get_swap_quote':
+                    return await handleGetSwapQuote(sdk, args);
+                case 'get_available_pools':
+                    return await handleGetAvailablePools(sdk);
+                default:
+                    throw new McpToolError('INVALID_INPUT', `Unknown tool: ${toolName}`);
+            }
+        }
+        catch (err) {
+            if (err instanceof McpToolError) {
+                return err.toResponse();
+            }
+            return wrapError(err).toResponse();
+        }
+    };
+}
+/**
+ * Get all tool definitions for MCP registration
+ */
+export function getToolDefinitions() {
+    return allToolDefinitions;
+}
+/**
+ * MCP Server factory (for use with @modelcontextprotocol/sdk)
+ *
+ * Example usage with MCP SDK:
+ * ```typescript
+ * import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+ * import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+ * import { PolymarketSDK } from '@catalyst-team/poly-sdk';
+ * import { registerMcpTools } from '@catalyst-team/poly-mcp';
+ *
+ * const server = new Server(
+ *   { name: 'poly-mcp', version: '1.0.0' },
+ *   { capabilities: { tools: {} } }
+ * );
+ *
+ * const sdk = new PolymarketSDK();
+ * registerMcpTools(server, sdk);
+ *
+ * const transport = new StdioServerTransport();
+ * await server.connect(transport);
+ * ```
+ */
+export function registerMcpTools(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+server, sdk) {
+    const handler = createMcpHandler(sdk);
+    // Register list tools handler
+    server.setRequestHandler({ method: 'tools/list' }, async () => ({ tools: allToolDefinitions }));
+    // Register call tool handler
+    server.setRequestHandler({ method: 'tools/call' }, async (request) => {
+        const { name, arguments: args = {} } = request.params;
+        const result = await handler(name, args);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=index.js.map