@catalyst-team/poly-mcp 0.1.0

package/src/tools/index.ts

@@ -0,0 +1,73 @@
+/**
+ * MCP Tools Index
+ */
+
+// Re-export all tool definitions and handlers
+export {
+  guideToolDefinitions,
+  createGuideHandlers,
+} from './guide.js';
+
+export {
+  traderToolDefinitions,
+  handleGetTraderPositions,
+  handleGetTraderTrades,
+  handleGetTraderProfile,
+  handleGetLeaderboard,
+} from './trader.js';
+
+export {
+  marketToolDefinitions,
+  handleGetMarket,
+  handleSearchMarkets,
+  handleGetTrendingMarkets,
+  handleGetMarketTrades,
+} from './market.js';
+
+export {
+  orderToolDefinitions,
+  handleGetOrderbook,
+  handleGetBestPrices,
+  handleEstimateExecution,
+} from './order.js';
+
+export {
+  tradeToolDefinitions,
+  handlePlaceLimitOrder,
+  handlePlaceMarketOrder,
+  handleCancelOrder,
+  handleGetMyOrders,
+} from './trade.js';
+
+export {
+  walletToolDefinitions,
+  handleGetSupportedAssets,
+  handleGetDepositAddresses,
+  handleDepositUsdc,
+  handleCheckAllowances,
+  handleApproveTrading,
+  handleSwap,
+  handleSwapAndDeposit,
+  handleGetTokenBalances,
+  handleGetWalletBalances,
+  handleGetSwapQuote,
+  handleGetAvailablePools,
+} from './wallet.js';
+
+// Combined tool definitions
+import { guideToolDefinitions } from './guide.js';
+import { traderToolDefinitions } from './trader.js';
+import { marketToolDefinitions } from './market.js';
+import { orderToolDefinitions } from './order.js';
+import { tradeToolDefinitions } from './trade.js';
+import { walletToolDefinitions } from './wallet.js';
+
+// Guide tool FIRST so AI sees it prominently
+export const allToolDefinitions = [
+  ...guideToolDefinitions,
+  ...traderToolDefinitions,
+  ...marketToolDefinitions,
+  ...orderToolDefinitions,
+  ...tradeToolDefinitions,
+  ...walletToolDefinitions,
+];

package/src/tools/market.ts

@@ -0,0 +1,363 @@
+/**
+ * Market Tools - MCP tools for market discovery and analysis
+ */
+
+import type { PolymarketSDK } from '@catalyst-team/poly-sdk';
+import type {
+  ToolDefinition,
+  GetMarketInput,
+  GetMarketOutput,
+  SearchMarketsInput,
+  SearchMarketsOutput,
+  GetTrendingMarketsInput,
+  GetTrendingMarketsOutput,
+  GetMarketTradesInput,
+  GetMarketTradesOutput,
+} from '../types.js';
+import { validateConditionId, wrapError, McpToolError, ErrorCode } from '../errors.js';
+
+export const marketToolDefinitions: ToolDefinition[] = [
+  {
+    name: 'get_market',
+    description: 'Get market details including prices, volume, and status',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: {
+          type: 'string',
+          description: "Market slug (e.g., 'us-recession-in-2025') or conditionId (0x...)",
+        },
+      },
+      required: ['identifier'],
+    },
+  },
+  {
+    name: 'search_markets',
+    description:
+      'Search for markets by keyword. Searches in question text and slug. Returns markets sorted by 24h volume.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description:
+            'Search keyword (e.g., "Trump", "Bitcoin", "recession"). Multi-word queries match any word.',
+        },
+        active: {
+          type: 'boolean',
+          description: 'Only return active markets',
+          default: true,
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum results',
+          default: 10,
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'get_trending_markets',
+    description: 'Get trending markets sorted by volume or liquidity',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'number',
+          default: 10,
+        },
+        sortBy: {
+          type: 'string',
+          enum: ['volume', 'liquidity', 'newest'],
+          default: 'volume',
+        },
+      },
+    },
+  },
+  {
+    name: 'get_market_trades',
+    description: 'Get recent trades for a specific market',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        conditionId: {
+          type: 'string',
+          description: 'Market condition ID',
+        },
+        limit: {
+          type: 'number',
+          default: 20,
+        },
+      },
+      required: ['conditionId'],
+    },
+  },
+];
+
+export async function handleGetMarket(
+  sdk: PolymarketSDK,
+  input: GetMarketInput
+): Promise<GetMarketOutput> {
+  if (!input.identifier) {
+    throw new McpToolError(ErrorCode.INVALID_INPUT, 'Market identifier is required');
+  }
+
+  try {
+    const market = await sdk.getMarket(input.identifier);
+
+    return {
+      market: {
+        conditionId: market.conditionId,
+        question: market.question,
+        slug: market.slug,
+        description: market.description,
+      },
+      prices: {
+        yes: market.tokens.yes.price,
+        no: market.tokens.no.price,
+        spread: market.spread,
+      },
+      tokens: {
+        yes: {
+          tokenId: market.tokens.yes.tokenId,
+          price: market.tokens.yes.price,
+        },
+        no: {
+          tokenId: market.tokens.no.tokenId,
+          price: market.tokens.no.price,
+        },
+      },
+      stats: {
+        volume: market.volume,
+        liquidity: market.liquidity,
+      },
+      status: {
+        active: market.active,
+        closed: market.closed,
+        acceptingOrders: market.acceptingOrders,
+        endDate: market.endDate?.toISOString(),
+      },
+      trading: {
+        minTickSize: undefined, // From CLOB if needed
+        minOrderSize: undefined,
+      },
+    };
+  } catch (err) {
+    throw wrapError(err);
+  }
+}
+
+export async function handleSearchMarkets(
+  sdk: PolymarketSDK,
+  input: SearchMarketsInput
+): Promise<SearchMarketsOutput> {
+  if (!input.query) {
+    throw new McpToolError(ErrorCode.INVALID_INPUT, 'Search query is required');
+  }
+
+  try {
+    // Fetch active markets sorted by 24h volume for better relevance
+    // Note: Gamma API doesn't support server-side text search,
+    // so we fetch a larger set and filter client-side
+    const allMarkets = await sdk.gammaApi.getMarkets({
+      active: input.active !== false,
+      closed: false,
+      order: 'volume24hr',
+      ascending: false,
+      limit: 500, // Fetch more markets for comprehensive search
+    });
+
+    const queryLower = input.query.toLowerCase();
+    const queryWords = queryLower.split(/\s+/).filter((w) => w.length > 0);
+
+    // Filter by query - match any word in question or slug
+    const filtered = allMarkets.filter((m) => {
+      const questionLower = m.question.toLowerCase();
+      const slugLower = m.slug.toLowerCase();
+
+      // Match if any query word is found in question or slug
+      return queryWords.some(
+        (word) => questionLower.includes(word) || slugLower.includes(word)
+      );
+    });
+
+    // Sort by relevance: prioritize exact phrase matches, then by volume
+    filtered.sort((a, b) => {
+      const aQuestion = a.question.toLowerCase();
+      const bQuestion = b.question.toLowerCase();
+      const aExact = aQuestion.includes(queryLower);
+      const bExact = bQuestion.includes(queryLower);
+
+      // Exact phrase matches first
+      if (aExact && !bExact) return -1;
+      if (!aExact && bExact) return 1;
+
+      // Then by 24h volume
+      return (b.volume24hr || 0) - (a.volume24hr || 0);
+    });
+
+    // Apply limit
+    const results = filtered.slice(0, input.limit || 10);
+
+    return {
+      markets: results.map((m) => {
+        // Safely handle endDate - it may be invalid
+        let endDateStr: string | undefined;
+        try {
+          if (m.endDate && !isNaN(m.endDate.getTime())) {
+            endDateStr = m.endDate.toISOString();
+          }
+        } catch {
+          // Ignore invalid date
+        }
+
+        return {
+          conditionId: m.conditionId,
+          question: m.question,
+          slug: m.slug,
+          prices: {
+            yes: m.outcomePrices[0] || 0.5,
+            no: m.outcomePrices[1] || 0.5,
+          },
+          volume: m.volume,
+          volume24h: m.volume24hr,
+          endDate: endDateStr,
+        };
+      }),
+      total: filtered.length,
+    };
+  } catch (err) {
+    throw wrapError(err);
+  }
+}
+
+export async function handleGetTrendingMarkets(
+  sdk: PolymarketSDK,
+  input: GetTrendingMarketsInput
+): Promise<GetTrendingMarketsOutput> {
+  try {
+    const sortBy = input.sortBy || 'volume';
+    let orderBy: string;
+    const ascending = false;
+
+    switch (sortBy) {
+      case 'volume':
+        orderBy = 'volume24hr';
+        break;
+      case 'liquidity':
+        orderBy = 'liquidity';
+        break;
+      case 'newest':
+        orderBy = 'startDate';
+        break;
+      default:
+        orderBy = 'volume24hr';
+    }
+
+    // Fetch more markets than requested to allow filtering
+    const requestedLimit = input.limit || 10;
+    const markets = await sdk.gammaApi.getMarkets({
+      active: true,
+      closed: false, // Explicitly exclude closed markets
+      limit: requestedLimit * 2, // Fetch extra in case some need filtering
+      order: orderBy,
+      ascending,
+    });
+
+    // Filter out markets that are closed or not accepting orders
+    // This handles edge cases where API returns recently-settled markets
+    const activeMarkets = markets.filter((m) => {
+      // Skip if explicitly marked as closed
+      if (m.closed) return false;
+      // Skip if market has ended (endDate in past)
+      if (m.endDate) {
+        const endTime = m.endDate instanceof Date ? m.endDate.getTime() : new Date(m.endDate).getTime();
+        if (!isNaN(endTime) && endTime < Date.now()) return false;
+      }
+      return true;
+    });
+
+    // Take only the requested number after filtering
+    const finalMarkets = activeMarkets.slice(0, requestedLimit);
+
+    return {
+      markets: finalMarkets.map((m) => ({
+        conditionId: m.conditionId,
+        question: m.question,
+        slug: m.slug,
+        volume24h: m.volume24hr,
+        priceChange24h: m.oneDayPriceChange,
+        prices: {
+          yes: m.outcomePrices[0] || 0.5,
+          no: m.outcomePrices[1] || 0.5,
+        },
+        // Add status fields for transparency
+        status: {
+          active: m.active,
+          closed: m.closed,
+          endDate: m.endDate ? (m.endDate instanceof Date ? m.endDate.toISOString() : String(m.endDate)) : undefined,
+        },
+      })),
+    };
+  } catch (err) {
+    throw wrapError(err);
+  }
+}
+
+export async function handleGetMarketTrades(
+  sdk: PolymarketSDK,
+  input: GetMarketTradesInput
+): Promise<GetMarketTradesOutput> {
+  validateConditionId(input.conditionId);
+
+  try {
+    const trades = await sdk.dataApi.getTradesByMarket(
+      input.conditionId,
+      input.limit || 20
+    );
+
+    // Get market info for the title
+    let marketTitle = '';
+    try {
+      const market = await sdk.getMarket(input.conditionId);
+      marketTitle = market.question;
+    } catch {
+      // Use conditionId as fallback
+      marketTitle = input.conditionId;
+    }
+
+    const now = Date.now();
+    const oneDayAgo = now - 24 * 60 * 60 * 1000;
+
+    const recentTrades = trades.filter((t) => t.timestamp >= oneDayAgo);
+    const buyTrades = recentTrades.filter((t) => t.side === 'BUY');
+    const sellTrades = recentTrades.filter((t) => t.side === 'SELL');
+
+    const buyVolume24h = buyTrades.reduce((sum, t) => sum + t.size * t.price, 0);
+    const sellVolume24h = sellTrades.reduce((sum, t) => sum + t.size * t.price, 0);
+
+    return {
+      market: {
+        conditionId: input.conditionId,
+        title: marketTitle,
+      },
+      trades: trades.slice(0, input.limit || 20).map((t) => ({
+        trader: t.proxyWallet || '',
+        traderName: t.name,
+        side: t.side,
+        outcome: t.outcome,
+        size: t.size,
+        price: t.price,
+        timestamp: new Date(t.timestamp).toISOString(),
+      })),
+      summary: {
+        buyVolume24h,
+        sellVolume24h,
+        netFlow: buyVolume24h - sellVolume24h,
+      },
+    };
+  } catch (err) {
+    throw wrapError(err);
+  }
+}