@caypo/canton-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,643 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CantonAgent } from "@caypo/canton-sdk";
+
+// src/tools/index.ts
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/tools/balance.ts
+function balanceTools(agent) {
+  return [
+    {
+      name: "caypo_balance",
+      description: "Get USDCx checking account balance and holding count",
+      inputSchema: { type: "object", properties: {}, required: [] },
+      handler: async () => {
+        const bal = await agent.checking.balance();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                available: bal.available,
+                holdingCount: bal.holdingCount,
+                currency: "USDCx",
+                network: agent.wallet.network
+              }, null, 2)
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "caypo_address",
+      description: "Get Canton party ID (address) and network info",
+      inputSchema: { type: "object", properties: {}, required: [] },
+      handler: async () => ({
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              partyId: agent.wallet.address,
+              network: agent.wallet.network,
+              format: "<DisplayName>::<hex-fingerprint>"
+            }, null, 2)
+          }
+        ]
+      })
+    },
+    {
+      name: "caypo_history",
+      description: "Get recent transaction history",
+      inputSchema: {
+        type: "object",
+        properties: { limit: { type: "number", description: "Max transactions to return", default: 20 } }
+      },
+      handler: async (args) => {
+        const history = await agent.checking.history({ limit: args.limit });
+        return {
+          content: [{ type: "text", text: JSON.stringify(history, null, 2) }]
+        };
+      }
+    },
+    {
+      name: "caypo_positions",
+      description: "View DeFi positions (Coming in Phase 3)",
+      inputSchema: { type: "object", properties: {}, required: [] },
+      handler: async () => ({
+        content: [{ type: "text", text: "DeFi positions are not yet available. Coming in Phase 3 when Canton DeFi protocols launch." }]
+      })
+    },
+    {
+      name: "caypo_rates",
+      description: "Get exchange rates and APYs (Coming in Phase 3)",
+      inputSchema: { type: "object", properties: {}, required: [] },
+      handler: async () => ({
+        content: [{ type: "text", text: "Exchange rates and APYs are not yet available. Coming in Phase 3." }]
+      })
+    }
+  ];
+}
+
+// src/tools/checking.ts
+function checkingTools(agent) {
+  return [
+    {
+      name: "caypo_send",
+      description: "Send USDCx to a recipient via TransferFactory_Transfer. Checks safeguards before sending.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          recipient: { type: "string", description: "Recipient Canton party ID" },
+          amount: { type: "string", description: "Amount of USDCx to send (string, e.g. '1.50')" },
+          memo: { type: "string", description: "Optional memo" }
+        },
+        required: ["recipient", "amount"]
+      },
+      handler: async (args) => {
+        const { recipient, amount, memo } = args;
+        const result = await agent.checking.send(recipient, amount, { memo });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                status: "success",
+                amount,
+                recipient,
+                updateId: result.updateId,
+                completionOffset: result.completionOffset,
+                commandId: result.commandId
+              }, null, 2)
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "caypo_receive",
+      description: "Show party ID and deposit instructions for receiving USDCx",
+      inputSchema: { type: "object", properties: {}, required: [] },
+      handler: async () => ({
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              partyId: agent.wallet.address,
+              network: agent.wallet.network,
+              instructions: "Send USDCx to this party ID. The sender needs a TransferPreapproval or must use a 2-step TransferInstruction."
+            }, null, 2)
+          }
+        ]
+      })
+    },
+    {
+      name: "caypo_contacts",
+      description: "Manage contact list \u2014 list, add, or remove contacts",
+      inputSchema: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: ["list", "add", "remove"], default: "list" },
+          name: { type: "string", description: "Contact name" },
+          partyId: { type: "string", description: "Contact party ID" }
+        }
+      },
+      handler: async () => ({
+        content: [{ type: "text", text: "Contact management coming soon. Use party IDs directly for now." }]
+      })
+    }
+  ];
+}
+
+// src/tools/mpp.ts
+function mppTools(agent) {
+  return [
+    {
+      name: "caypo_pay",
+      description: "Pay for an API call via MPP (HTTP 402 auto-handling). Fetches URL, handles payment if 402, returns response.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "URL to fetch" },
+          method: { type: "string", description: "HTTP method", default: "GET" },
+          body: { type: "string", description: "Request body (JSON string)" },
+          maxPrice: { type: "string", description: "Maximum price willing to pay in USDCx" }
+        },
+        required: ["url"]
+      },
+      handler: async (args) => {
+        const { url, method, body, maxPrice } = args;
+        const result = await agent.mpp.pay(url, {
+          method,
+          body,
+          maxPrice,
+          headers: body ? { "Content-Type": "application/json" } : void 0
+        });
+        const responseBody = await result.response.text();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                status: result.response.status,
+                paid: result.paid,
+                receipt: result.receipt,
+                body: responseBody.slice(0, 2e3)
+              }, null, 2)
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "caypo_pay_status",
+      description: "Check payment status by Canton update ID",
+      inputSchema: {
+        type: "object",
+        properties: {
+          updateId: { type: "string", description: "Canton transaction update ID" }
+        },
+        required: ["updateId"]
+      },
+      handler: async () => ({
+        content: [{ type: "text", text: "Payment status lookup requires gateway integration. Use the updateId with the Canton Ledger API directly." }]
+      })
+    },
+    {
+      name: "caypo_services",
+      description: "List available MPP gateway services and pricing",
+      inputSchema: { type: "object", properties: {}, required: [] },
+      handler: async () => ({
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              gateway: "mpp.cayvox.io",
+              services: [
+                { name: "OpenAI", path: "/openai", price: "$0.001-$0.05" },
+                { name: "Anthropic", path: "/anthropic", price: "$0.01" },
+                { name: "fal.ai", path: "/fal", price: "$0.01-$0.10" },
+                { name: "Firecrawl", path: "/firecrawl", price: "$0.005-$0.02" },
+                { name: "Google Gemini", path: "/gemini", price: "$0.005-$0.02" },
+                { name: "Groq", path: "/groq", price: "$0.001-$0.005" },
+                { name: "Perplexity", path: "/perplexity", price: "$0.01" },
+                { name: "Brave Search", path: "/brave", price: "$0.001-$0.005" },
+                { name: "DeepSeek", path: "/deepseek", price: "$0.005" },
+                { name: "Resend", path: "/resend", price: "$0.005" },
+                { name: "Together AI", path: "/together", price: "$0.001-$0.02" },
+                { name: "ElevenLabs", path: "/elevenlabs", price: "$0.02-$0.05" },
+                { name: "OpenWeather", path: "/openweather", price: "$0.001" },
+                { name: "Google Maps", path: "/googlemaps", price: "$0.005" },
+                { name: "Judge0", path: "/judge0", price: "$0.002" },
+                { name: "Reloadly", path: "/reloadly", price: "$0.01+" },
+                { name: "Lob", path: "/lob", price: "$0.01-$0.50" }
+              ]
+            }, null, 2)
+          }
+        ]
+      })
+    }
+  ];
+}
+
+// src/tools/safeguards.ts
+function safeguardTools(agent) {
+  return [
+    {
+      name: "caypo_safeguards",
+      description: "View current safeguard settings: tx limit, daily limit, lock status, daily spending",
+      inputSchema: { type: "object", properties: {}, required: [] },
+      handler: async () => {
+        const s = agent.safeguards.settings();
+        return {
+          content: [{ type: "text", text: JSON.stringify(s, null, 2) }]
+        };
+      }
+    },
+    {
+      name: "caypo_set_limit",
+      description: "Set per-transaction or daily spending limit",
+      inputSchema: {
+        type: "object",
+        properties: {
+          type: { type: "string", enum: ["tx", "daily"], description: "Limit type" },
+          amount: { type: "string", description: "Limit amount in USDCx" }
+        },
+        required: ["type", "amount"]
+      },
+      handler: async (args) => {
+        const { type, amount } = args;
+        if (type === "tx") {
+          agent.safeguards.setTxLimit(amount);
+        } else {
+          agent.safeguards.setDailyLimit(amount);
+        }
+        return {
+          content: [{ type: "text", text: `${type === "tx" ? "Per-transaction" : "Daily"} limit set to ${amount} USDCx` }]
+        };
+      }
+    },
+    {
+      name: "caypo_lock",
+      description: "Lock or unlock the wallet. When locked, all transactions are rejected.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: ["lock", "unlock"], description: "Action to perform" },
+          pin: { type: "string", description: "PIN for lock/unlock" }
+        },
+        required: ["action"]
+      },
+      handler: async (args) => {
+        const { action, pin } = args;
+        if (action === "lock") {
+          agent.safeguards.lock(pin);
+          return { content: [{ type: "text", text: "Wallet locked. All transactions will be rejected until unlocked." }] };
+        } else {
+          agent.safeguards.unlock(pin ?? "");
+          return { content: [{ type: "text", text: "Wallet unlocked." }] };
+        }
+      }
+    }
+  ];
+}
+
+// src/tools/traffic.ts
+function trafficTools(agent) {
+  return [
+    {
+      name: "caypo_traffic",
+      description: "Check validator traffic balance. Canton uses traffic budgets, not gas fees.",
+      inputSchema: { type: "object", properties: {}, required: [] },
+      handler: async () => {
+        const bal = await agent.traffic.trafficBalance();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                ...bal,
+                note: "Canton uses traffic budgets per validator, not per-transaction gas fees."
+              }, null, 2)
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "caypo_purchase_traffic",
+      description: "Purchase additional traffic by burning Canton Coin (CC). Coming soon.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ccAmount: { type: "string", description: "Amount of CC to burn" }
+        },
+        required: ["ccAmount"]
+      },
+      handler: async () => ({
+        content: [{ type: "text", text: "Traffic purchase is not yet implemented. Requires validator admin API access." }]
+      })
+    }
+  ];
+}
+
+// src/tools/stubs.ts
+function stub(name, description, phase) {
+  return {
+    name,
+    description: `${description} (Coming in ${phase})`,
+    inputSchema: { type: "object", properties: {} },
+    handler: async () => ({
+      content: [{ type: "text", text: `${description} is not yet available. Coming in ${phase} when Canton DeFi protocols launch.` }]
+    })
+  };
+}
+function stubTools() {
+  return [
+    // Savings (4)
+    stub("caypo_save", "Deposit USDCx into savings for yield", "Phase 3"),
+    stub("caypo_withdraw", "Withdraw from savings to checking", "Phase 3"),
+    stub("caypo_rebalance_savings", "Rebalance savings across protocols", "Phase 3"),
+    stub("caypo_earnings", "View savings earnings and APY", "Phase 3"),
+    // Credit (3)
+    stub("caypo_borrow", "Borrow USDCx against collateral", "Phase 3"),
+    stub("caypo_repay", "Repay borrowed amount", "Phase 3"),
+    stub("caypo_health", "Check credit health factor", "Phase 3"),
+    // Exchange (2)
+    stub("caypo_exchange", "Exchange tokens on Canton DEX", "Phase 3"),
+    stub("caypo_quote", "Get exchange rate quote", "Phase 3"),
+    // Investment (8)
+    stub("caypo_invest_buy", "Buy investment assets", "Phase 4"),
+    stub("caypo_invest_sell", "Sell investment assets", "Phase 4"),
+    stub("caypo_invest_earn", "Stake assets for yield", "Phase 4"),
+    stub("caypo_invest_unearn", "Unstake assets", "Phase 4"),
+    stub("caypo_invest_rebalance", "Rebalance investment portfolio", "Phase 4"),
+    stub("caypo_portfolio", "View investment portfolio", "Phase 4"),
+    stub("caypo_strategy_buy", "Execute investment strategy", "Phase 4"),
+    stub("caypo_auto_invest", "Configure auto-invest DCA", "Phase 4"),
+    // Rewards (2)
+    stub("caypo_claim_rewards", "Claim Canton Coin mining rewards", "Phase 3"),
+    stub("caypo_reward_history", "View reward claim history", "Phase 3")
+  ];
+}
+
+// src/tools/index.ts
+function registerTools(server, agent) {
+  const allTools = [
+    ...balanceTools(agent),
+    ...checkingTools(agent),
+    ...mppTools(agent),
+    ...safeguardTools(agent),
+    ...trafficTools(agent),
+    ...stubTools()
+  ];
+  const toolMap = /* @__PURE__ */ new Map();
+  for (const tool of allTools) {
+    toolMap.set(tool.name, tool);
+  }
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: allTools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema
+    }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = toolMap.get(request.params.name);
+    if (!tool) {
+      return {
+        content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
+        isError: true
+      };
+    }
+    try {
+      return await tool.handler(request.params.arguments ?? {});
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true
+      };
+    }
+  });
+}
+
+// src/prompts/index.ts
+import {
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+function stubPrompt(name, description) {
+  return {
+    name,
+    description,
+    handler: () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Please provide a ${description.toLowerCase()}. Note: This prompt template will be enhanced in a future version.`
+          }
+        }
+      ]
+    })
+  };
+}
+var prompts = [
+  // 5 fully implemented prompts
+  {
+    name: "morning_briefing",
+    description: "Daily financial briefing \u2014 balance, spending, traffic, alerts",
+    handler: () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Good morning! Please give me my daily Canton agent briefing:
+
+1. **Balance**: Call caypo_balance to get my current USDCx balance and holding count.
+2. **Spending**: Call caypo_safeguards to check my daily spending vs limits.
+3. **Traffic**: Call caypo_traffic to check validator traffic status.
+4. **Recent activity**: Call caypo_history with limit=5 to show recent transactions.
+
+Format as a concise morning briefing with key numbers highlighted.`
+          }
+        }
+      ]
+    })
+  },
+  {
+    name: "financial_report",
+    description: "Comprehensive financial report \u2014 all accounts, spending patterns, recommendations",
+    handler: () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Generate a comprehensive financial report for my Canton agent:
+
+1. Call caypo_balance for current balance
+2. Call caypo_safeguards for spending limits and daily usage
+3. Call caypo_history with limit=20 for recent transactions
+4. Call caypo_traffic for traffic status
+
+Analyze the data and provide:
+- Total balance and holding efficiency (suggest merging if >5 UTXOs)
+- Daily spending rate vs limits
+- Traffic consumption trend
+- Recommendations for limit adjustments`
+          }
+        }
+      ]
+    })
+  },
+  {
+    name: "spending_analysis",
+    description: "Analyze recent spending patterns and suggest optimizations",
+    handler: () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Analyze my spending patterns:
+
+1. Call caypo_history with limit=50
+2. Call caypo_safeguards for current limits
+3. Call caypo_balance for current balance
+
+Then:
+- Categorize spending (API calls, transfers, etc.)
+- Identify the most expensive API services
+- Suggest whether my safeguard limits are appropriate
+- Flag any unusual transaction patterns`
+          }
+        }
+      ]
+    })
+  },
+  {
+    name: "security_audit",
+    description: "Security audit \u2014 check safeguards, wallet status, traffic health",
+    handler: () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Perform a security audit of my Canton agent:
+
+1. Call caypo_safeguards \u2014 are limits set appropriately?
+2. Call caypo_traffic \u2014 is traffic healthy?
+3. Call caypo_balance \u2014 any concerns about holding count?
+4. Call caypo_address \u2014 verify network
+
+Check for:
+- Are safeguard limits reasonable? (tx limit should be < 10% of balance)
+- Is the wallet locked when it should be?
+- Are there too many UTXOs? (>10 = recommend merge)
+- Is traffic balance sufficient?
+- Any signs of unusual activity?`
+          }
+        }
+      ]
+    })
+  },
+  {
+    name: "onboarding",
+    description: "New user onboarding \u2014 explain Canton agent features and guide setup",
+    handler: () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Welcome a new user to CAYPO \u2014 their Canton Network agent bank account. Explain:
+
+1. **What CAYPO is**: A bank account for AI agents on Canton Network. Privacy-preserving, institutional-grade.
+2. **Key features**: USDCx checking account, MPP auto-payments for APIs, safeguards, traffic management.
+3. **How to get started**:
+   - Call caypo_address to show their party ID
+   - Call caypo_balance to check initial balance
+   - Call caypo_safeguards to review default limits
+   - Call caypo_services to see available paid APIs
+4. **Important concepts**:
+   - Canton uses party IDs, not addresses
+   - USDCx is USDC-backed via Circle xReserve
+   - Amounts are always strings (never floating point)
+   - Traffic replaces gas (validator-level, not per-tx)
+5. **Safety**: Safeguards protect against overspending. Always set appropriate limits.`
+          }
+        }
+      ]
+    })
+  },
+  // 15 stub prompts
+  stubPrompt("what_if", "What-if financial scenario analysis"),
+  stubPrompt("optimize_yield", "Yield optimization recommendations"),
+  stubPrompt("risk_assessment", "Risk assessment for current positions"),
+  stubPrompt("investment_thesis", "Investment thesis generation"),
+  stubPrompt("rebalance_plan", "Portfolio rebalance plan"),
+  stubPrompt("savings_strategy", "Savings strategy recommendations"),
+  stubPrompt("credit_health", "Credit health assessment"),
+  stubPrompt("traffic_report", "Detailed traffic consumption report"),
+  stubPrompt("market_overview", "Canton market overview"),
+  stubPrompt("portfolio_review", "Investment portfolio review"),
+  stubPrompt("defi_opportunities", "DeFi opportunities on Canton"),
+  stubPrompt("weekly_summary", "Weekly financial summary"),
+  stubPrompt("budget_plan", "Budget planning assistant"),
+  stubPrompt("tax_summary", "Transaction tax summary"),
+  stubPrompt("troubleshoot", "Troubleshoot Canton agent issues")
+];
+function registerPrompts(server) {
+  const promptMap = /* @__PURE__ */ new Map();
+  for (const p of prompts) {
+    promptMap.set(p.name, p);
+  }
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: prompts.map((p) => ({
+      name: p.name,
+      description: p.description,
+      arguments: p.arguments
+    }))
+  }));
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const prompt = promptMap.get(request.params.name);
+    if (!prompt) {
+      throw new Error(`Unknown prompt: ${request.params.name}`);
+    }
+    return prompt.handler(request.params.arguments ?? {});
+  });
+}
+
+// src/index.ts
+var CANTON_MCP_VERSION = "0.1.0";
+async function main() {
+  const agent = await CantonAgent.create({
+    token: process.env.CANTON_JWT ?? ""
+  });
+  const server = new Server(
+    { name: "caypo", version: CANTON_MCP_VERSION },
+    { capabilities: { tools: {}, prompts: {} } }
+  );
+  registerTools(server, agent);
+  registerPrompts(server);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("MCP server failed to start:", err);
+  process.exit(1);
+});
+export {
+  CANTON_MCP_VERSION
+};
+//# sourceMappingURL=index.js.map