conviction-mcp

Instructions

Implementation Reference

• mcp/src/index.ts:1211-1332 (handler)

  The get_agent_status tool handler fetches detailed agent information including status, balance, strategy, and recent activity logs from the backend.

  server.tool(
    "get_agent_status",
    "Get detailed status for a specific agent: active/paused state, balance, strategy, today's activity summary, recent activity log, and position history. Use this to monitor agent health and debug issues.",
    {
      agent_id: z.string().optional().describe("The agent's profile ID. Auto-filled from saved credentials if omitted."),
      owner_id: z.string().optional().describe("The owner's profile ID. Auto-filled from saved credentials if omitted."),
    },
    async ({ agent_id, owner_id }) => {
      const saved = loadSavedAgents();
      const resolvedAgent = agent_id || (saved.length > 0 ? saved[saved.length - 1].agentId : null);
      const resolvedOwner = owner_id || (saved.length > 0 ? saved[saved.length - 1].ownerId : null);
      if (!resolvedAgent || !resolvedOwner) {
        return { content: [{ type: "text", text: "No agent found. Create one first with `create_agent`, or pass agent_id and owner_id." }], isError: true };
      }
  
      const result = (await apiPost("update-agent", {
        action: "agent_status",
        agentId: resolvedAgent,
        ownerProfileId: resolvedOwner,
      })) as any;
  
      if (!result.success) {
        return {
          content: [{ type: "text", text: `Status check failed: ${result.error || "Unknown error"}` }],
          isError: true,
        };
      }
  
      const agent = result.agent || {};
      const today = result.today || {};
      const activityLog = result.activityLog || [];
      const recentBets = result.recentBets || [];
  
      // Fetch on-chain balance
      const onChainBalance = agent.walletAddress ? await fetchOnChainBalance(agent.walletAddress) : null;
  
      // Format compiled rules summary
      const compiled = agent.compiledRules;
      let compiledSummary = "  No compiled rules";
      if (compiled?.rules?.length) {
        const ruleLines = compiled.rules.map((r: any, i: number) => {
          const cond = r.condition || {};
          const act = r.action || {};
          const condDesc = cond.type === "always" ? "Every pool"
            : cond.type === "win_probability" ? `Win prob >${cond.probability_threshold_pct || 60}%`
            : cond.type === "pool_imbalance" ? `Pool imbalance >${cond.imbalance_threshold_pct || 60}%`
            : cond.type === "token_preference" ? `Tokens: ${cond.include_tokens?.join(",") || "any"}`
            : cond.type === "time_window" ? `Time: ${cond.min_hours_remaining ?? 0}-${cond.max_hours_remaining ?? 24}h`
            : cond.type;
          const timeFilter = (cond.type !== "time_window" && (cond.min_hours_remaining != null || cond.max_hours_remaining != null))
            ? ` (${cond.min_hours_remaining != null ? `>${cond.min_hours_remaining}h` : ""}${cond.max_hours_remaining != null ? `<${cond.max_hours_remaining}h` : ""})`
            : "";
          const poolFilter = cond.min_pool_size_usdc ? ` (pool>=$${cond.min_pool_size_usdc})` : "";
          const amtType = act.amount_type || "fixed";
          const amount = amtType === "full_balance" ? "full budget"
            : amtType === "split_equal" ? "split equally"
            : amtType === "percentage" ? `${act.amount_percent || 10}% of budget`
            : `$${act.amount_usdc || 1}`;
          return `  ${i + 1}. ${condDesc}${timeFilter}${poolFilter} → ${amount} on ${act.side_selection || "high_prob"}`;
        });
        const gc = compiled.global_constraints || {};
        const constraints = [
          gc.max_daily_spend_usdc ? `$${gc.max_daily_spend_usdc}/day` : null,
          gc.max_bets_per_pool ? `${gc.max_bets_per_pool}/pool` : null,
          gc.cooldown_minutes ? `${gc.cooldown_minutes}min cooldown` : null,
        ].filter(Boolean).join(", ");
        compiledSummary = ruleLines.join("\n") + (constraints ? `\n  Constraints: ${constraints}` : "");
      }
  
      // Format activity log
      const activityLines = activityLog.length > 0
        ? activityLog.map((a: any) => {
            const time = a.at ? new Date(a.at).toISOString().replace("T", " ").slice(0, 19) : "?";
            const details = typeof a.details === "string" ? a.details : JSON.stringify(a.details || "");
            return `  ${time} — ${a.action}: ${humanizeError(details)}`;
          }).join("\n")
        : "  No recent activity";
  
      // Format recent bets
      const betLines = recentBets.length > 0
        ? recentBets.map((b: any) => {
            const time = b.at ? new Date(b.at).toISOString().replace("T", " ").slice(0, 19) : "?";
            const status = b.won === true ? "WON" : b.won === false ? "LOST" : "PENDING";
            const claimed = b.claimed ? " (claimed)" : "";
            return `  ${time} | ${b.pair} → ${b.side} $${b.amount} | conv ${b.conviction?.toFixed(3) ?? "?"} | ${status}${claimed}`;
          }).join("\n")
        : "  No recent entries";
  
      return {
        content: [
          {
            type: "text",
            text: [
              `# Agent Status: ${agent.name || resolvedAgent}`,
              "",
              `**Status:** ${agent.active ? "ACTIVE" : "PAUSED"}`,
              `**Balance:** ${onChainBalance != null ? `${onChainBalance.toFixed(2)} bsUSD (on-chain)` : `$${agent.balance?.toFixed(2) ?? "?"} (db)`}`,
              `**Wallet:** ${agent.walletAddress || "unknown"}`,
              `**Created:** ${agent.createdAt || "?"}`,
              "",
              `**Strategy:** ${agent.rules || "none"}`,
              "",
              `## Compiled Rules`,
              compiledSummary,
              "",
              `## Today's Activity`,
              `  Entries placed: ${today.betsCount ?? 0}`,
              `  Total spent: $${today.spend?.toFixed(2) ?? "0.00"}`,
              "",
              `## Recent Activity Log (last 20)`,
              activityLines,
              "",
              `## Recent Entries (last 20)`,
              betLines,
              "",
              `_Fetched at ${new Date().toISOString()}_`,
            ].join("\n"),
          },
        ],
      };
    }
  );