@t2000/mcp 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 t2000
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @t2000/mcp
+
+MCP server for AI agent bank accounts on Sui. Connect Claude Desktop, Cursor, or any MCP client to your t2000 agent.
+
+**16 tools · 3 prompts · stdio transport · safeguard enforced**
+
+## Quick Start
+
+```bash
+# Install
+npm i -g @t2000/cli
+
+# Create wallet + configure safeguards
+t2000 init
+t2000 config set maxPerTx 100
+t2000 config set maxDailySend 500
+
+# Create session (saves PIN for MCP)
+t2000 balance
+
+# Start MCP server
+t2000 mcp
+```
+
+## Platform Config
+
+Paste into your AI platform's MCP settings:
+
+```json
+{ "mcpServers": { "t2000": { "command": "t2000", "args": ["mcp"] } } }
+```
+
+## Tools
+
+| Tool | Type | Description |
+|------|------|-------------|
+| `t2000_balance` | read | Current balance |
+| `t2000_address` | read | Wallet address |
+| `t2000_positions` | read | Lending positions |
+| `t2000_rates` | read | Interest rates |
+| `t2000_health` | read | Health factor |
+| `t2000_history` | read | Transaction history |
+| `t2000_earnings` | read | Yield earnings |
+| `t2000_send` | write | Send USDC |
+| `t2000_save` | write | Deposit to savings |
+| `t2000_withdraw` | write | Withdraw from savings |
+| `t2000_borrow` | write | Borrow against collateral |
+| `t2000_repay` | write | Repay debt |
+| `t2000_exchange` | write | Swap assets |
+| `t2000_rebalance` | write | Optimize yield |
+| `t2000_config` | safety | View/set limits |
+| `t2000_lock` | safety | Emergency freeze |
+
+## Programmatic Usage
+
+```typescript
+import { startMcpServer } from '@t2000/mcp';
+
+await startMcpServer({ keyPath: '/path/to/key' });
+```
+
+## Security
+
+- Safeguard gate prevents starting without configured limits
+- Per-transaction and daily send caps enforced on all state-changing tools
+- `unlock` is CLI-only — AI cannot circumvent a locked agent
+- `dryRun: true` previews operations without signing
+- stdio transport — private key never leaves the machine
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin.js

@@ -0,0 +1,590 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readFile } from 'fs/promises';
+import { resolve } from 'path';
+import { homedir } from 'os';
+import { T2000, validateAddress, SafeguardError, T2000Error } from '@t2000/sdk';
+import { z } from 'zod';
+
+var SESSION_PATH = resolve(homedir(), ".t2000", ".session");
+async function resolvePin() {
+  const envPin = process.env.T2000_PIN ?? process.env.T2000_PASSPHRASE;
+  if (envPin) return envPin;
+  try {
+    const session = await readFile(SESSION_PATH, "utf-8");
+    if (session.trim()) return session.trim();
+  } catch {
+  }
+  throw new Error(
+    "No PIN available. Either:\n  1. Run `t2000 balance` first (creates session), or\n  2. Set T2000_PIN environment variable"
+  );
+}
+async function createAgent(keyPath) {
+  const pin = await resolvePin();
+  return T2000.create({ pin, keyPath });
+}
+function mapError(err) {
+  if (err instanceof SafeguardError) {
+    return {
+      code: "SAFEGUARD_BLOCKED",
+      message: err.message,
+      retryable: false,
+      details: { rule: err.rule, ...err.details }
+    };
+  }
+  if (err instanceof T2000Error) {
+    return {
+      code: err.code,
+      message: err.message,
+      retryable: err.retryable
+    };
+  }
+  return {
+    code: "UNKNOWN",
+    message: err instanceof Error ? err.message : String(err),
+    retryable: false
+  };
+}
+function errorResult(err) {
+  const mapped = mapError(err);
+  return {
+    content: [{ type: "text", text: JSON.stringify(mapped) }],
+    isError: true
+  };
+}
+
+// src/tools/read.ts
+function registerReadTools(server, agent) {
+  server.tool(
+    "t2000_balance",
+    "Get agent's current balance \u2014 available (checking), savings, gas reserve, and total. All values in USD.",
+    {},
+    async () => {
+      try {
+        const result = await agent.balance();
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_address",
+    "Get the agent's Sui wallet address.",
+    {},
+    async () => {
+      try {
+        const address = agent.address();
+        return { content: [{ type: "text", text: JSON.stringify({ address }) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_positions",
+    "View current lending positions across protocols (NAVI, Suilend) \u2014 deposits, borrows, APYs.",
+    {},
+    async () => {
+      try {
+        const result = await agent.positions();
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_rates",
+    "Get best available interest rates per asset across all lending protocols.",
+    {},
+    async () => {
+      try {
+        const result = await agent.rates();
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_health",
+    "Check the agent's health factor \u2014 measures how safe current borrows are. Below 1.0 risks liquidation.",
+    {},
+    async () => {
+      try {
+        const result = await agent.healthFactor();
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_history",
+    "View recent transactions (sends, saves, borrows, swaps, etc.).",
+    { limit: z.number().optional().describe("Number of transactions to return (default: 20)") },
+    async ({ limit }) => {
+      try {
+        const result = await agent.history({ limit });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_earnings",
+    "View yield earnings from savings positions \u2014 total earned, daily rate, current APY.",
+    {},
+    async () => {
+      try {
+        const result = await agent.earnings();
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+}
+
+// src/mutex.ts
+var TxMutex = class {
+  queue = Promise.resolve();
+  async run(fn) {
+    let release;
+    const next = new Promise((r) => {
+      release = r;
+    });
+    const prev = this.queue;
+    this.queue = next;
+    await prev;
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+};
+
+// src/tools/write.ts
+function registerWriteTools(server, agent) {
+  const mutex = new TxMutex();
+  server.tool(
+    "t2000_send",
+    "Send USDC or stablecoins to a Sui address. Amount is in dollars. Subject to per-transaction and daily send limits. Set dryRun: true to preview without signing.",
+    {
+      to: z.string().describe("Recipient Sui address (0x...)"),
+      amount: z.number().describe("Amount in dollars to send"),
+      asset: z.string().optional().describe("Asset to send (default: USDC)"),
+      dryRun: z.boolean().optional().describe("Preview without signing (default: false)")
+    },
+    async ({ to, amount, asset, dryRun }) => {
+      try {
+        if (!validateAddress(to)) {
+          return errorResult(new Error(`Invalid Sui address: ${to}`));
+        }
+        if (dryRun) {
+          agent.enforcer.check({ operation: "send", amount });
+          const balance = await agent.balance();
+          const config = agent.enforcer.getConfig();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                preview: true,
+                canSend: balance.available >= amount,
+                amount,
+                to,
+                asset: asset ?? "USDC",
+                currentBalance: balance.available,
+                balanceAfter: balance.available - amount,
+                safeguards: {
+                  dailyUsedAfter: config.dailyUsed + amount,
+                  dailyLimit: config.maxDailySend
+                }
+              })
+            }]
+          };
+        }
+        const result = await mutex.run(() => agent.send({ to, amount, asset }));
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_save",
+    'Deposit USDC to savings (earns yield). Amount is in dollars. Use "all" to save entire available balance. Set dryRun: true to preview.',
+    {
+      amount: z.union([z.number(), z.literal("all")]).describe('Dollar amount to save, or "all"'),
+      dryRun: z.boolean().optional().describe("Preview without signing (default: false)")
+    },
+    async ({ amount, dryRun }) => {
+      try {
+        if (dryRun) {
+          agent.enforcer.assertNotLocked();
+          const balance = await agent.balance();
+          const rates = await agent.rates();
+          const saveAmount = amount === "all" ? balance.available - 1 : amount;
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                preview: true,
+                amount: saveAmount,
+                currentApy: rates.USDC?.saveApy ?? 0,
+                savingsBalanceAfter: balance.savings + saveAmount
+              })
+            }]
+          };
+        }
+        const result = await mutex.run(() => agent.save({ amount }));
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_withdraw",
+    'Withdraw from savings back to checking. Amount is in dollars. Use "all" to withdraw everything. Set dryRun: true to preview.',
+    {
+      amount: z.union([z.number(), z.literal("all")]).describe('Dollar amount to withdraw, or "all"'),
+      dryRun: z.boolean().optional().describe("Preview without signing (default: false)")
+    },
+    async ({ amount, dryRun }) => {
+      try {
+        if (dryRun) {
+          agent.enforcer.assertNotLocked();
+          const positions = await agent.positions();
+          const health = await agent.healthFactor();
+          const savings = positions.positions.filter((p) => p.type === "save").reduce((sum, p) => sum + p.amount, 0);
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                preview: true,
+                amount: amount === "all" ? savings : amount,
+                currentSavings: savings,
+                currentHealthFactor: health.healthFactor
+              })
+            }]
+          };
+        }
+        const result = await mutex.run(() => agent.withdraw({ amount }));
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_borrow",
+    "Borrow USDC against savings collateral. Check health factor first \u2014 below 1.0 risks liquidation. Amount is in dollars. Set dryRun: true to preview.",
+    {
+      amount: z.number().describe("Dollar amount to borrow"),
+      dryRun: z.boolean().optional().describe("Preview without signing (default: false)")
+    },
+    async ({ amount, dryRun }) => {
+      try {
+        if (dryRun) {
+          agent.enforcer.assertNotLocked();
+          const health = await agent.healthFactor();
+          const maxBorrow = await agent.maxBorrow();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                preview: true,
+                amount,
+                maxBorrow: maxBorrow.maxAmount,
+                currentHealthFactor: health.healthFactor,
+                estimatedHealthFactorAfter: maxBorrow.healthFactorAfter
+              })
+            }]
+          };
+        }
+        const result = await mutex.run(() => agent.borrow({ amount }));
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_repay",
+    'Repay borrowed USDC. Amount is in dollars. Use "all" to repay entire debt. Set dryRun: true to preview.',
+    {
+      amount: z.union([z.number(), z.literal("all")]).describe('Dollar amount to repay, or "all"'),
+      dryRun: z.boolean().optional().describe("Preview without signing (default: false)")
+    },
+    async ({ amount, dryRun }) => {
+      try {
+        if (dryRun) {
+          agent.enforcer.assertNotLocked();
+          const health = await agent.healthFactor();
+          const positions = await agent.positions();
+          const totalDebt = positions.positions.filter((p) => p.type === "borrow").reduce((sum, p) => sum + p.amount, 0);
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                preview: true,
+                amount: amount === "all" ? totalDebt : amount,
+                currentDebt: totalDebt,
+                currentHealthFactor: health.healthFactor
+              })
+            }]
+          };
+        }
+        const result = await mutex.run(() => agent.repay({ amount }));
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_exchange",
+    "Swap assets via Cetus DEX (e.g. USDC to SUI, SUI to USDC). Amount is in source asset units. Set dryRun: true to get a quote without executing.",
+    {
+      amount: z.number().describe("Amount to swap (in source asset units)"),
+      from: z.string().describe("Source asset (e.g. USDC, SUI)"),
+      to: z.string().describe("Target asset (e.g. SUI, USDC)"),
+      maxSlippage: z.number().optional().describe("Max slippage percentage (default: 3%)"),
+      dryRun: z.boolean().optional().describe("Preview without signing (default: false)")
+    },
+    async ({ amount, from, to, maxSlippage, dryRun }) => {
+      try {
+        if (dryRun) {
+          agent.enforcer.assertNotLocked();
+          const quote = await agent.exchangeQuote({ from, to, amount });
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                preview: true,
+                from,
+                to,
+                amount,
+                expectedOutput: quote.expectedOutput,
+                priceImpact: quote.priceImpact,
+                fee: quote.fee.amount
+              })
+            }]
+          };
+        }
+        const result = await mutex.run(
+          () => agent.exchange({ from, to, amount, maxSlippage })
+        );
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_rebalance",
+    "Optimize yield by moving funds to the highest-rate protocol. Always previews first \u2014 set dryRun: false to execute. Shows plan with expected APY gain and break-even period.",
+    {
+      dryRun: z.boolean().optional().describe("Preview without executing (default: true)"),
+      minYieldDiff: z.number().optional().describe("Min APY difference to rebalance (default: 0.5%)"),
+      maxBreakEven: z.number().optional().describe("Max break-even days (default: 30)")
+    },
+    async ({ dryRun, minYieldDiff, maxBreakEven }) => {
+      try {
+        const result = await mutex.run(
+          () => agent.rebalance({
+            dryRun: dryRun ?? true,
+            minYieldDiff,
+            maxBreakEven
+          })
+        );
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+}
+function registerSafetyTools(server, agent) {
+  server.tool(
+    "t2000_config",
+    'View or set agent safeguard limits (per-transaction max, daily send limit). Use action "show" to view current limits, "set" to update. Values are in dollars. Set to 0 for unlimited.',
+    {
+      action: z.enum(["show", "set"]).describe('"show" to view current limits, "set" to update a limit'),
+      key: z.string().optional().describe('Setting to update: "maxPerTx" or "maxDailySend"'),
+      value: z.number().optional().describe("New value in dollars (0 = unlimited)")
+    },
+    async ({ action, key, value }) => {
+      try {
+        if (action === "show") {
+          const config = agent.enforcer.getConfig();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                locked: config.locked,
+                maxPerTx: config.maxPerTx,
+                maxDailySend: config.maxDailySend,
+                dailyUsed: config.dailyUsed
+              })
+            }]
+          };
+        }
+        if (!key || value === void 0) {
+          return errorResult(new Error('Both "key" and "value" are required for action "set"'));
+        }
+        if (key === "locked") {
+          return errorResult(new Error('Cannot set "locked" via config. Use t2000_lock to freeze operations.'));
+        }
+        if (key !== "maxPerTx" && key !== "maxDailySend") {
+          return errorResult(new Error(`Unknown key "${key}". Valid keys: "maxPerTx", "maxDailySend"`));
+        }
+        if (value < 0) {
+          return errorResult(new Error("Value must be a non-negative number"));
+        }
+        agent.enforcer.set(key, value);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ updated: true, key, value })
+          }]
+        };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.tool(
+    "t2000_lock",
+    "Freeze all agent operations immediately. Only a human can unlock via `t2000 unlock` in the terminal. Use this as an emergency stop.",
+    {},
+    async () => {
+      try {
+        agent.enforcer.lock();
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              locked: true,
+              message: "Agent locked. Only a human can unlock via: t2000 unlock"
+            })
+          }]
+        };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+}
+function registerPrompts(server) {
+  server.prompt(
+    "financial-report",
+    "Get a comprehensive summary of the agent's financial position \u2014 balance, savings, debt, health factor, and yield earnings.",
+    async () => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            "You are a financial assistant for a t2000 AI agent bank account.",
+            "",
+            "Please provide a comprehensive financial report by:",
+            "1. Check the current balance (t2000_balance)",
+            "2. Review lending positions (t2000_positions)",
+            "3. Check the health factor (t2000_health)",
+            "4. Show yield earnings (t2000_earnings)",
+            "5. Review current interest rates (t2000_rates)",
+            "",
+            "Summarize the agent's financial health in a clear, concise format with actionable recommendations."
+          ].join("\n")
+        }
+      }]
+    })
+  );
+  server.prompt(
+    "optimize-yield",
+    "Analyze savings positions and suggest yield optimizations \u2014 rate comparisons, rebalancing opportunities.",
+    async () => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            "You are a yield optimization assistant for a t2000 AI agent bank account.",
+            "",
+            "Please analyze the current yield strategy:",
+            "1. Check current positions (t2000_positions)",
+            "2. Compare rates across protocols (t2000_rates)",
+            "3. Run a dry-run rebalance to see if optimization is available (t2000_rebalance with dryRun: true)",
+            "",
+            "If a rebalance would improve yield, explain the trade-off (gas cost vs yield gain, break-even period) and ask if the user wants to proceed."
+          ].join("\n")
+        }
+      }]
+    })
+  );
+  server.prompt(
+    "send-money",
+    "Guided flow for sending USDC to a Sui address \u2014 validates address, checks limits, previews before signing.",
+    {
+      to: z.string().optional().describe("Recipient Sui address"),
+      amount: z.number().optional().describe("Amount in dollars")
+    },
+    async ({ to, amount }) => {
+      const context = [
+        to ? `Recipient address: ${to}` : "",
+        amount ? `Amount: $${amount}` : ""
+      ].filter(Boolean).join("\n");
+      return {
+        messages: [{
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "You are a payment assistant for a t2000 AI agent bank account.",
+              "",
+              context ? `Context:
+${context}
+` : "",
+              "The user wants to send money. Follow this flow:",
+              "1. If address or amount is missing, ask the user",
+              "2. Preview the transaction (t2000_send with dryRun: true)",
+              "3. Show the preview \u2014 amount, recipient, remaining balance, safeguard status",
+              "4. Ask the user to confirm before executing",
+              "5. Execute the send (t2000_send with dryRun: false)",
+              "6. Show the transaction result with the Suiscan link"
+            ].join("\n")
+          }
+        }]
+      };
+    }
+  );
+}
+
+// src/index.ts
+async function startMcpServer(opts) {
+  const agent = await createAgent(opts?.keyPath);
+  if (!agent.enforcer.isConfigured()) {
+    console.error(
+      "Safeguards not configured. Set limits before starting MCP:\n  t2000 config set maxPerTx 100\n  t2000 config set maxDailySend 500\n"
+    );
+    process.exit(1);
+  }
+  const server = new McpServer({ name: "t2000", version: "0.12.0" });
+  registerReadTools(server, agent);
+  registerWriteTools(server, agent);
+  registerSafetyTools(server, agent);
+  registerPrompts(server);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// src/bin.ts
+await startMcpServer();
+//# sourceMappingURL=bin.js.map
+//# sourceMappingURL=bin.js.map