@catalyst-team/poly-mcp 0.1.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@catalyst-team/poly-mcp",
+  "version": "0.1.0",
+  "private": false,
+  "description": "MCP (Model Context Protocol) server for Polymarket - enables AI agents to interact with prediction markets",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "poly-mcp": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "keywords": [
+    "polymarket",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "prediction-markets",
+    "claude",
+    "anthropic"
+  ],
+  "author": "Catalyst Team",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "ethers": "^5.7.2",
+    "@catalyst-team/poly-sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "ethers": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/server.js",
+    "mcp": "node dist/server.js",
+    "mcp:dev": "tsx src/server.ts"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,124 @@
+/**
+ * MCP Error Handling for Polymarket Tools
+ */
+
+export 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 class McpToolError extends Error {
+  constructor(
+    public code: ErrorCode,
+    message: string,
+    public details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'McpToolError';
+  }
+
+  toResponse() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        details: this.details,
+      },
+    };
+  }
+}
+
+export function validateAddress(address: string): void {
+  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: string): void {
+  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: string): void {
+  if (!['Yes', 'No'].includes(outcome)) {
+    throw new McpToolError(
+      ErrorCode.INVALID_INPUT,
+      'Outcome must be "Yes" or "No"',
+      { outcome }
+    );
+  }
+}
+
+export function validateSide(side: string): void {
+  if (!['BUY', 'SELL'].includes(side)) {
+    throw new McpToolError(
+      ErrorCode.INVALID_INPUT,
+      'Side must be "BUY" or "SELL"',
+      { side }
+    );
+  }
+}
+
+export function validatePrice(price: number): void {
+  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: number, name: string): void {
+  if (typeof value !== 'number' || value <= 0) {
+    throw new McpToolError(
+      ErrorCode.INVALID_INPUT,
+      `${name} must be a positive number`,
+      { [name]: value }
+    );
+  }
+}
+
+export function wrapError(err: unknown): McpToolError {
+  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');
+}

package/src/index.ts

@@ -0,0 +1,309 @@
+/**
+ * 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';
+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';
+
+// Tool handler type
+export type ToolHandler = (
+  toolName: string,
+  args: Record<string, unknown>
+) => Promise<unknown>;
+
+/**
+ * Create an MCP tool handler for the given SDK instance
+ */
+export function createMcpHandler(sdk: PolymarketSDK): ToolHandler {
+  // Create guide handlers (no SDK dependency)
+  const guideHandlers = createGuideHandlers();
+
+  return async (toolName: string, args: Record<string, unknown>): Promise<unknown> => {
+    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 as { address: string });
+
+        case 'get_trader_trades':
+          return await handleGetTraderTrades(sdk, args as {
+            address: string;
+            limit?: number;
+            side?: 'BUY' | 'SELL';
+          });
+
+        case 'get_trader_profile':
+          return await handleGetTraderProfile(sdk, args as { address: string });
+
+        case 'get_leaderboard':
+          return await handleGetLeaderboard(sdk, args as {
+            limit?: number;
+            offset?: number;
+          });
+
+        // Market Tools
+        case 'get_market':
+          return await handleGetMarket(sdk, args as { identifier: string });
+
+        case 'search_markets':
+          return await handleSearchMarkets(sdk, args as {
+            query: string;
+            active?: boolean;
+            limit?: number;
+          });
+
+        case 'get_trending_markets':
+          return await handleGetTrendingMarkets(sdk, args as {
+            limit?: number;
+            sortBy?: 'volume' | 'liquidity' | 'newest';
+          });
+
+        case 'get_market_trades':
+          return await handleGetMarketTrades(sdk, args as {
+            conditionId: string;
+            limit?: number;
+          });
+
+        // Order Tools
+        case 'get_orderbook':
+          return await handleGetOrderbook(sdk, args as {
+            conditionId: string;
+            outcome: 'Yes' | 'No';
+            depth?: number;
+          });
+
+        case 'get_best_prices':
+          return await handleGetBestPrices(sdk, args as {
+            conditionId: string;
+          });
+
+        case 'estimate_execution':
+          return await handleEstimateExecution(sdk, args as {
+            conditionId: string;
+            outcome: 'Yes' | 'No';
+            side: 'BUY' | 'SELL';
+            amount: number;
+          });
+
+        // Trade Tools
+        case 'place_limit_order':
+          return await handlePlaceLimitOrder(sdk, args as {
+            conditionId: string;
+            outcome: 'Yes' | 'No';
+            side: 'BUY' | 'SELL';
+            price: number;
+            size: number;
+            orderType?: 'GTC' | 'GTD';
+          });
+
+        case 'place_market_order':
+          return await handlePlaceMarketOrder(sdk, args as {
+            conditionId: string;
+            outcome: 'Yes' | 'No';
+            side: 'BUY' | 'SELL';
+            amount: number;
+            maxSlippage?: number;
+          });
+
+        case 'cancel_order':
+          return await handleCancelOrder(sdk, args as { orderId: string });
+
+        case 'get_my_orders':
+          return await handleGetMyOrders(sdk, args as {
+            status?: 'LIVE' | 'FILLED' | 'CANCELLED';
+          });
+
+        // Wallet Tools
+        case 'get_supported_deposit_assets':
+          return await handleGetSupportedAssets(sdk, args as {
+            chainId?: number;
+          });
+
+        case 'get_deposit_addresses':
+          return await handleGetDepositAddresses(sdk);
+
+        case 'deposit_usdc':
+          return await handleDepositUsdc(sdk, args as {
+            amount: number;
+            token?: 'NATIVE_USDC' | 'USDC_E';
+          });
+
+        case 'check_allowances':
+          return await handleCheckAllowances(sdk);
+
+        case 'approve_trading':
+          return await handleApproveTrading(sdk);
+
+        case 'swap':
+          return await handleSwap(sdk, args as {
+            tokenIn: string;
+            tokenOut: string;
+            amount: string;
+            slippage?: number;
+          });
+
+        case 'swap_and_deposit':
+          return await handleSwapAndDeposit(sdk, args as {
+            token: string;
+            amount: string;
+            slippage?: number;
+          });
+
+        case 'get_token_balances':
+          return await handleGetTokenBalances(sdk);
+
+        case 'get_wallet_balances':
+          return await handleGetWalletBalances(sdk, args as { address: string });
+
+        case 'get_swap_quote':
+          return await handleGetSwapQuote(sdk, args as {
+            tokenIn: string;
+            tokenOut: string;
+            amount: string;
+          });
+
+        case 'get_available_pools':
+          return await handleGetAvailablePools(sdk);
+
+        default:
+          throw new McpToolError(
+            'INVALID_INPUT' as unknown as import('./errors.js').ErrorCode,
+            `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: any,
+  sdk: PolymarketSDK
+): void {
+  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: { params: { name: string; arguments?: Record<string, unknown> } }) => {
+      const { name, arguments: args = {} } = request.params;
+      const result = await handler(name, args);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    }
+  );
+}

package/src/server.ts

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * Polymarket MCP Server
+ *
+ * A standalone MCP server that exposes Polymarket functionality to AI agents.
+ *
+ * Usage:
+ *   npx @catalyst-team/poly-mcp
+ *   # or
+ *   node dist/server.js
+ *
+ * Configuration via environment variables:
+ *   - POLY_PRIVATE_KEY: Wallet private key (required for trading, API credentials are derived automatically)
+ *   - POLY_CHAIN_ID: Chain ID (137 for mainnet, 80002 for testnet, default: 137)
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { Wallet } from 'ethers';
+
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
+import { allToolDefinitions } from './tools/index.js';
+import { createMcpHandler } from './index.js';
+
+/**
+ * Create a wallet signer from private key if available
+ */
+function createSigner(): Wallet | undefined {
+  const privateKey = process.env.POLY_PRIVATE_KEY;
+  if (!privateKey) {
+    return undefined;
+  }
+
+  try {
+    // Ensure private key has 0x prefix
+    const formattedKey = privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`;
+    return new Wallet(formattedKey);
+  } catch (error) {
+    console.error('Failed to create wallet from POLY_PRIVATE_KEY:', error);
+    return undefined;
+  }
+}
+
+// Server metadata
+const SERVER_NAME = 'polymarket-mcp';
+const SERVER_VERSION = '0.1.0';
+
+/**
+ * Create and configure the MCP server
+ */
+function createServer(): Server {
+  const server = new Server(
+    {
+      name: SERVER_NAME,
+      version: SERVER_VERSION,
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // Create signer from private key if available
+  const signer = createSigner();
+
+  // Initialize SDK with environment configuration
+  // API credentials are derived automatically from private key via createOrDeriveApiKey()
+  const sdk = new PolymarketSDK({
+    chainId: process.env.POLY_CHAIN_ID ? parseInt(process.env.POLY_CHAIN_ID) : 137,
+    signer,
+  });
+
+  // Log trading status
+  if (signer) {
+    console.error(`Trading enabled for wallet: ${signer.address}`);
+  } else {
+    console.error('Trading disabled (set POLY_PRIVATE_KEY to enable)');
+  }
+
+  // Create the tool handler
+  const handler = createMcpHandler(sdk);
+
+  // Register list tools handler
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: allToolDefinitions.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      })),
+    };
+  });
+
+  // Register call tool handler
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+
+    try {
+      const result = await handler(name, args as Record<string, unknown>);
+
+      // Check if result is an error response
+      if (result && typeof result === 'object' && 'error' in result) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                error: {
+                  code: 'INTERNAL_ERROR',
+                  message: errorMessage,
+                },
+              },
+              null,
+              2
+            ),
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+
+  return server;
+}
+
+/**
+ * Main entry point
+ */
+async function main(): Promise<void> {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+
+  // Handle shutdown gracefully
+  process.on('SIGINT', async () => {
+    await server.close();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', async () => {
+    await server.close();
+    process.exit(0);
+  });
+
+  // Connect and run
+  await server.connect(transport);
+
+  // Log to stderr (stdout is reserved for MCP protocol)
+  console.error(`${SERVER_NAME} v${SERVER_VERSION} started`);
+  console.error(`Available tools: ${allToolDefinitions.length}`);
+}
+
+// Run the server
+main().catch((error) => {
+  console.error('Failed to start MCP server:', error);
+  process.exit(1);
+});