conviction-mcp

Instructions

Implementation Reference

• mcp/src/index.ts:1139-1207 (handler)

  Implementation of the "get_my_agents" tool, which lists saved agents from a local JSON file and fetches their status from the conviction.fm API.

  // ── Tool: get_my_agents ──
  
  server.tool(
    "get_my_agents",
    "List your saved agents with their IDs, API keys, and status. Agents are saved locally when created via create_agent. Also fetches latest status from the server.",
    {},
    async () => {
      const saved = loadSavedAgents();
  
      if (saved.length === 0) {
        return {
          content: [
            { type: "text", text: "No saved agents found. Use `create_agent` to create one." },
          ],
        };
      }
  
      // Try to fetch live status from server using the first agent's owner
      const ownerId = saved[0].ownerId;
      let serverAgents: any[] | null = null;
      try {
        const result = (await apiPost("update-agent", {
          action: "list_agents",
          ownerProfileId: ownerId,
        })) as any;
        if (result.success) serverAgents = result.agents;
      } catch { /* offline is fine, show local data */ }
  
      // Fetch on-chain balances in parallel for all agents with wallets
      const balanceMap: Record<string, number | null> = {};
      if (serverAgents) {
        const entries = await Promise.all(
          serverAgents
            .filter((s: any) => s.walletAddress)
            .map(async (s: any) => [s.id, await fetchOnChainBalance(s.walletAddress)] as [string, number | null])
        );
        for (const [id, bal] of entries) balanceMap[id] = bal;
      }
  
      const lines = saved.map((a) => {
        const server = serverAgents?.find((s: any) => s.id === a.agentId);
        const status = server ? (server.active ? "ACTIVE" : "PAUSED") : "unknown";
        const today = server?.today;
        const todayLine = today && today.count > 0
          ? `  Today: ${today.count} entries, $${today.spend.toFixed(2)} spent${today.lastAt ? `, last at ${new Date(today.lastAt).toISOString().replace("T", " ").slice(0, 19)} UTC` : ""}`
          : `  Today: no entries yet`;
        const onChainBal = balanceMap[a.agentId];
        const balanceLine = onChainBal != null ? `  Balance: ${onChainBal.toFixed(2)} bsUSD (on-chain)` : server ? `  Balance: $${server.balance?.toFixed(2) ?? "?"} (db)` : "";
        return [
          `**${a.name}** (${status})`,
          `  Agent ID: ${a.agentId}`,
          `  API Key: ${a.apiKey}`,
          `  Owner: ${a.ownerId}`,
          server?.walletAddress ? `  Wallet: ${server.walletAddress}` : "",
          balanceLine,
          todayLine,
        ].filter(Boolean).join("\n");
      });
  
      return {
        content: [
          {
            type: "text",
            text: `# Your Agents (${saved.length})\n\n${lines.join("\n\n")}\n\n_Fetched at ${new Date().toISOString()}_\n_Credentials stored in ~/.conviction/agents.json. Use get_agent_status for detailed activity log._`,
          },
        ],
      };
    }
  );