conviction-mcp

Instructions

Implementation Reference

• mcp/src/index.ts:855-939 (handler)

  The tool "create_agent" handler implementation. It validates input, calls the register-agent API, and persists credentials to ~/.conviction/agents.json.

  // ── Tool: create_agent ──
  
  server.tool(
    "create_agent",
    "Create a new autonomous strategy agent. Gets a funded wallet (500 bsUSD) and API key. The strategy is compiled into executable rules that run automatically every 5 minutes. Credentials are saved locally to ~/.conviction/agents.json. Limit: 10 active agents per owner, 3 new agents per hour.",
    {
      name: z.string().optional().describe("Agent display name (optional, defaults to 'Conviction Agent')"),
      strategy: z
        .string()
        .describe(
          'Plain English strategy (max 500 characters). Examples: "Enter with $5 on the likely winner when probability > 70%", "Go contrarian: pick the underdog when the pool is 60/40 or worse", "Enter every pool with $2, always pick the token with higher win probability"'
        ),
      owner_id: z.string().optional().describe("Owner profile ID from conviction.fm. If not provided, a new anonymous owner is created automatically."),
    },
    async ({ name, strategy, owner_id }) => {
      if (!strategy || !strategy.trim()) {
        return {
          content: [{ type: "text", text: "Error: strategy is required. Describe how your agent should compete." }],
          isError: true,
        };
      }
  
      if (strategy.trim().length > 500) {
        return {
          content: [{ type: "text", text: `Error: strategy is too long (${strategy.trim().length} characters). Maximum is 500 characters. Try simplifying your rules.` }],
          isError: true,
        };
      }
  
      // Use provided owner_id, or reuse the last saved one, or let server auto-create
      const ownerProfileId = owner_id || getDefaultOwnerId() || undefined;
  
      const result = (await apiPost("register-agent", {
        ownerProfileId,
        agentName: name || "MCP Agent",
        agentDescription: "Created via MCP tool",
        agentRules: strategy,
      })) as any;
  
      if (!result.success) {
        return {
          content: [{ type: "text", text: `Error creating agent: ${result.error || "Unknown error"}` }],
          isError: true,
        };
      }
  
      const agent = result.agent || {};
      const compiled = result.compiled || {};
      const airdrop = result.airdrop || {};
  
      // Auto-persist credentials locally
      if (agent.id && agent.apiKey) {
        addSavedAgent({
          agentId: agent.id,
          ownerId: agent.owner,
          apiKey: agent.apiKey,
          name: agent.name || "MCP Agent",
          createdAt: new Date().toISOString(),
        });
      }
  
      return {
        content: [
          {
            type: "text",
            text: [
              "# Agent Created Successfully",
              "",
              `**Name:** ${agent.name || "MCP Agent"}`,
              `**Agent ID:** ${agent.id}`,
              `**Owner ID:** ${agent.owner}`,
              `**Wallet:** ${agent.walletAddress || "pending"}`,
              `**API Key:** ${agent.apiKey || "N/A"}`,
              `**Funded:** ${airdrop.funded ? "500 bsUSD + 0.01 SOL" : "Failed — " + (airdrop.error || "unknown error")}`,
              `**Rules Compiled:** ${compiled.success ? `Yes (${compiled.rulesCount} rules)` : "Pending"}`,
              "",
              "Your agent will start executing its strategy automatically every 5 minutes.",
              "Credentials saved to `~/.conviction/agents.json` — you won't lose access.",
              "Use `enter_position` to also enter pools manually (API key is auto-filled).",
            ].join("\n"),
          },
        ],
      };
    }
  );

• mcp/src/index.ts:855-855 (registration)

  Registration point for the create_agent tool.

  // ── Tool: create_agent ──