conviction-mcp

Instructions

Implementation Reference

• mcp/src/index.ts:760-817 (handler)

  The implementation of the `get_pools` tool, which fetches open pool data from the API and formats it into a markdown string for the MCP client.

  // ── Tool: get_pools ──
  
  server.tool(
    "get_pools",
    "Get all currently open pools with win probabilities, pool shares, prices, time remaining, and conviction multiplier info. Use this to decide which pools to enter.",
    {},
    async () => {
      const data = (await apiGet("pool-state?mode=open")) as any;
      const pools = data.pools || [];
  
      if (pools.length === 0) {
        return {
          content: [
            { type: "text", text: "No open pools right now. Pools open daily at 10:00 UTC." },
          ],
        };
      }
  
      const lines = pools.map((p: any) => {
        const aId = p.tokenA?.id ?? "?";
        const bId = p.tokenB?.id ?? "?";
        const hrs = p.hoursRemaining?.toFixed(1) ?? "?";
        const total = p.totalPoolUsdc?.toFixed(0) ?? "?";
  
        const aProb = p.tokenA?.winProbability != null ? p.tokenA.winProbability.toFixed(1) : null;
        const bProb = p.tokenB?.winProbability != null ? p.tokenB.winProbability.toFixed(1) : null;
        const aShare = p.tokenA?.poolSharePercent?.toFixed(1) ?? "50.0";
        const bShare = p.tokenB?.poolSharePercent?.toFixed(1) ?? "50.0";
        const aStart = p.tokenA?.startPrice ? `$${p.tokenA.startPrice.toFixed(2)}` : "—";
        const bStart = p.tokenB?.startPrice ? `$${p.tokenB.startPrice.toFixed(2)}` : "—";
  
        // Conviction multiplier context
        const timeRatio = p.convictionInfo?.currentTimeRatio ?? 0;
        const multHint = timeRatio <= 0 ? "1.0x (early bonus)" : timeRatio >= 0.8 ? "penalized for late entries on favorites" : `time ratio ${timeRatio.toFixed(2)}`;
  
        const probLine = aProb && bProb
          ? `  Win probability: ${aId} ${aProb}% / ${bId} ${bProb}%`
          : `  Win probability: pending (updates every 5 min)`;
  
        return [
          `**${p.tokenPairKey}** — ${hrs}h left, $${total} pool`,
          probLine,
          `  ${aId}: ${aShare}% pool ($${p.tokenA?.poolAmount?.toFixed(0) ?? 0}) | open ${aStart}`,
          `  ${bId}: ${bShare}% pool ($${p.tokenB?.poolAmount?.toFixed(0) ?? 0}) | open ${bStart}`,
          `  Conviction: ${multHint}`,
        ].join("\n");
      });
  
      return {
        content: [
          {
            type: "text",
            text: `# Open Pools (${pools.length})\n\n${lines.join("\n\n")}\n\n_Fetched at ${new Date().toISOString()}_\n_Win probability = computed from live price momentum (updated every 5 min). Pool share = money distribution (payout odds). Use enter_position to enter a pool, or create_agent for automatic strategy execution._`,
          },
        ],
      };
    }
  );