@magpieloans/magpie-mcp 0.1.0 → 0.1.1

package/README.md

@@ -2,11 +2,13 @@
 
 **MCP server exposing the Magpie Capital x402 API as native tools for Claude Desktop, Cursor, Windsurf, ChatGPT desktop, and any other MCP-aware agent host.**
 
-Drop one config block into your host and your agent can query Magpie's protocol state, simulate borrows, fetch credit scores, build deposit/withdraw transactions, and post conditional borrow intents — all as first-class tool calls. No bespoke client code, no API keys.
+Drop one config block into your host and your agent can query Magpie's protocol state, simulate borrows, fetch credit scores, build deposit/withdraw transactions, post conditional borrow intents, and arm self-owned in-vault take-profit / stop-loss exits on its own loans — all as first-class tool calls. No bespoke client code, no API keys.
+
+> A share of Magpie protocol fees accrues to a **$MAGPIE** holder-rewards pool, paid pro-rata in SOL (no staking, no lockup). 70% is the governance-ratified (MGP-001) target allocation; distributions run on a governance cadence. x402 call fees feed the same holder-rewards economics — agent adoption grows the fees that reward holders.
 
 ## What it exposes
 
-19 tools wrapping the x402 endpoints:
+26 tools wrapping the x402 endpoints:
 
 **Free reads (work out of the box):**
 - `magpie_pool_state` — live LendingPool account
@@ -20,20 +22,41 @@ Drop one config block into your host and your agent can query Magpie's protocol
 - `magpie_liquidatable` — loans currently liquidatable
 - `magpie_credit_leaderboard` — top wallets by credit score
 - `magpie_lp_state` — depositor position + pool context
+- `magpie_loan_by_pda` — single loan by on-chain loan PDA
+- `magpie_pools` — Magpie lending pools (program-version lanes + context)
+- `magpie_list_exits` — armed in-vault exit orders for a wallet
+- `magpie_modify_exit` — change an armed exit's trigger / params
+- `magpie_cancel_exit` — cancel an armed exit (loan stays Active)
 
 **Paid (require a configured Solana keypair):**
 - `magpie_credit_score` — 0.001 SOL
 - `magpie_token_risk` — 0.001 SOL (per-token risk profile)
-- `magpie_build_borrow` — 0.005 SOL
+- `magpie_build_borrow` — 0.005 SOL (pass `has_exit_arming: true` to route into the V4 in-vault-exit lane)
 - `magpie_build_repay` — 0.002 SOL
 - `magpie_build_deposit` — 0.002 SOL
 - `magpie_build_withdraw` — 0.002 SOL
 - `magpie_build_liquidate` — 0.003 SOL (liquidate a past-due loan, receive keeper bounty)
 - `magpie_create_intent` — 0.01 SOL (conditional borrow)
 - `magpie_get_intent` — 0.0005 SOL (poll)
+- `magpie_arm_exit` — 0.001 SOL (arm a self-owned in-vault TP / SL / trailing exit)
 
 When a paid tool fires, the server signs an x402 payment tx locally with your configured keypair and forwards the signature to magpie-x402. The keypair never leaves your machine.
 
+## Self-owned in-vault exits (V4)
+
+Magpie's V4 lane lets an agent arm **its own** take-profit, stop-loss, and trailing exits on **its own** active loan — and the sell happens **in-vault**: when a trigger fires, the collateral is auto-sold and the proceeds (SOL by default, or USDC) accumulate inside that loan's per-loan proceeds vault while the loan stays **Active**. Proceeds only ever reach your wallet through your own borrower-signed repay. There's no fire-and-close, and nothing the protocol can do to move your funds out.
+
+- `magpie_arm_exit` (**0.001 SOL**) — arm a TP / SL / trailing exit on a V4 loan you own. Set `direction` (`above` = take-profit, the default; `below` = stop-loss) and exactly one trigger: `target` (e.g. `"2x"` / `"0.7x"`), `price_usd`, `mc_usd` (e.g. `"5M"`, `"1.2B"`), or `trailing_bps` (stop-loss only). Optional `slippage_bps`, `dest` (`sol` | `usdc`), and `slice` for laddered exits.
+- `magpie_modify_exit` (**free**) — retune an armed order's trigger or params in place.
+- `magpie_cancel_exit` (**free**) — remove an armed order; the loan is untouched.
+- `magpie_list_exits` (**free**) — audit a wallet's armed orders, each with its distance-to-trigger.
+
+Every exit call is authenticated with a dependency-free Ed25519 **signed envelope** built locally from your configured keypair. For `magpie_arm_exit` the envelope is signed by the **same** keypair that pays the 0.001 SOL x402 challenge, so the bot's `payer == signer` invariant holds and only the owner of a loan can arm exits on it. The bot enforces a 5-minute freshness window and nonce-uniqueness on every envelope.
+
+To start a borrow that supports these exits, call `magpie_build_borrow` with `has_exit_arming: true` (routes into V4); leave it `false` for a plain memecoin (V1) borrow.
+
+> RWA / xStock collateral runs on the separate V3 lane, which is launch-gated — on the V3 launch, the same exit tooling will extend to RWA loans.
+
 ## Install
 
 Two paths. Both end at the same place.
@@ -116,7 +139,7 @@ Use the same shape — point the host at `node /ABS/PATH/.../mcp/dist/index.js`,
 
 ## Free-only mode (no keypair)
 
-Omit `MAGPIE_MCP_PAYER_KEYPAIR` and all 11 free tools still work. Paid tools return a clear error explaining that no payer is configured. Useful for read-only research agents or as a no-friction first install.
+Omit `MAGPIE_MCP_PAYER_KEYPAIR` and the read-only free tools still work. Paid tools — and the envelope-signed exit tools (`magpie_arm_exit`, `magpie_modify_exit`, `magpie_cancel_exit`, which need the keypair to sign the envelope even though modify/cancel cost nothing) — return a clear error explaining that no payer is configured. Useful for read-only research agents or as a no-friction first install.
 
 ## Environment variables
 

package/dist/envelope.js

@@ -0,0 +1,84 @@
+/**
+ * Ed25519 signed-envelope builder for Magpie's self-owned exit orders.
+ *
+ * The bot's /api/v1/site/limit-close/* surface authenticates with a signed
+ * "Header: value" text envelope (NOT a session). This module builds + signs
+ * that envelope so an agent can arm / modify / cancel exits on its OWN loan
+ * with one call. The signature is produced with Node's built-in crypto
+ * (Ed25519) and a tiny inline base58 encoder — ZERO extra dependencies.
+ *
+ * The signed text is exactly what the bot re-parses and verifies, e.g.:
+ *
+ *   magpie: limit-close-arm/v1
+ *   From: <signer pubkey>
+ *   LoanId: 12345
+ *   Direction: above
+ *   Target: 2x
+ *   Slippage: 100
+ *   Dest: sol
+ *   Nonce: <uuid>
+ *   IssuedAt: 2026-06-20T00:00:00.000Z
+ */
+import { createPrivateKey, sign as nodeSign, randomUUID } from "node:crypto";
+// PKCS8 DER prefix for an Ed25519 private key (RFC 8410). The 32-byte seed
+// follows, giving a 48-byte DER we can hand to Node's createPrivateKey.
+const PKCS8_ED25519_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+/** Standard (Bitcoin/Solana) base58 encode. */
+function base58Encode(bytes) {
+    const digits = [0];
+    for (let i = 0; i < bytes.length; i++) {
+        let carry = bytes[i];
+        for (let j = 0; j < digits.length; j++) {
+            carry += digits[j] << 8;
+            digits[j] = carry % 58;
+            carry = (carry / 58) | 0;
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = (carry / 58) | 0;
+        }
+    }
+    let zeros = 0;
+    while (zeros < bytes.length && bytes[zeros] === 0)
+        zeros++;
+    let out = "1".repeat(zeros);
+    for (let k = digits.length - 1; k >= 0; k--)
+        out += BASE58_ALPHABET[digits[k]];
+    return out;
+}
+function signEd25519(message, keypair) {
+    // Solana secretKey is [32-byte seed || 32-byte pubkey]; Ed25519 PKCS8
+    // needs only the seed.
+    const seed = Buffer.from(keypair.secretKey.slice(0, 32));
+    const der = Buffer.concat([PKCS8_ED25519_PREFIX, seed]);
+    const key = createPrivateKey({ key: der, format: "der", type: "pkcs8" });
+    return nodeSign(null, Buffer.from(message), key);
+}
+/**
+ * Build + sign an envelope. `From`, `Nonce`, and `IssuedAt` are added
+ * automatically (unless you override them) — the bot requires all three and
+ * enforces a 5-minute freshness window on IssuedAt + nonce-uniqueness.
+ */
+export function buildSignedEnvelope(keypair, magpieHeader, fields) {
+    const signer = keypair.publicKey.toBase58();
+    const merged = {
+        Nonce: randomUUID(),
+        IssuedAt: new Date().toISOString(),
+        ...fields,
+    };
+    const lines = [`magpie: ${magpieHeader}`, `From: ${signer}`];
+    for (const [k, v] of Object.entries(merged)) {
+        if (v === undefined || v === null || v === "")
+            continue;
+        lines.push(`${k}: ${v}`);
+    }
+    const text = lines.join("\n");
+    const messageBytes = new TextEncoder().encode(text);
+    const sig = signEd25519(messageBytes, keypair);
+    return {
+        signedMessageBase64: Buffer.from(messageBytes).toString("base64"),
+        signatureBase58: base58Encode(sig),
+        signerPubkey: signer,
+    };
+}

package/dist/index.js

@@ -29,10 +29,20 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { call, loadKeypairFromEnv } from "./x402-client.js";
+import { buildSignedEnvelope } from "./envelope.js";
 const baseUrl = process.env.MAGPIE_X402_BASE_URL ?? "https://x402.magpie.capital";
 const rpcUrl = process.env.SOLANA_RPC_URL ?? "https://api.mainnet-beta.solana.com";
 const payer = loadKeypairFromEnv();
 const ctx = { baseUrl, rpcUrl, payer };
+// The self-owned exit surface signs an Ed25519 envelope with the payer
+// keypair. Both the signature AND (for arm) the x402 payment come from this
+// one keypair, guaranteeing the bot's payer==signer invariant.
+function requirePayer() {
+    if (!payer) {
+        throw new Error("this tool signs an exit envelope (and arm also pays an x402 challenge) but no payer keypair was configured. Set MAGPIE_MCP_PAYER_KEYPAIR.");
+    }
+    return payer;
+}
 // Schema-only tool registry. Each entry maps to a thin handler below
 // that turns the args into a magpie-x402 HTTP call. Keeping the tool
 // list in one declarative block makes ListTools cheap + always in sync
@@ -161,7 +171,7 @@ const TOOLS = [
     },
     {
         name: "magpie_build_borrow",
-        description: "Build an UNSIGNED borrow transaction. Server runs the full anti-exploit gate eval (ban registry, TWAP, pool floor, cross-source price, RWA-only guard, etc.) and returns a partial-signed tx. Agent signs locally and submits to magpie.capital/api/v1/cosign-borrow. Paid: 0.005 SOL.",
+        description: "Build an UNSIGNED borrow transaction. Server runs the full anti-exploit gate eval (ban registry, TWAP, pool floor, cross-source price, RWA-only guard, etc.) and returns a partial-signed tx. Agent signs locally and submits to magpie.capital/api/v1/cosign-borrow. Set has_exit_arming=true to route the loan into the V4 in-vault exit pool so you can later arm self-owned TP/SL exits on it (via magpie_arm_exit); leave false for a plain memecoin (V1) borrow. Paid: 0.005 SOL.",
         inputSchema: {
             type: "object",
             properties: {
@@ -169,6 +179,11 @@ const TOOLS = [
                 collateral_mint: { type: "string" },
                 collateral_amount: { type: "string", pattern: "^[0-9]+$" },
                 tier: { type: "integer", enum: [0, 1, 2] },
+                has_exit_arming: {
+                    type: "boolean",
+                    default: false,
+                    description: "When true, routes the borrow into the V4 program so the loan supports in-vault auto-sell exits (TP/SL/trailing). When false, a standard V1 borrow with no exit arming.",
+                },
             },
             required: ["borrower_wallet", "collateral_mint", "collateral_amount", "tier"],
         },
@@ -262,6 +277,136 @@ const TOOLS = [
             required: ["id"],
         },
     },
+    // ── V4 in-vault exit orders (self-owned TP / SL / trailing) ─────────
+    {
+        name: "magpie_arm_exit",
+        description: "Arm a self-owned in-vault exit (take-profit / stop-loss / trailing) on YOUR OWN active V4 loan. When the trigger fires, the collateral is auto-sold IN-VAULT: SOL (or USDC) accumulates inside the loan's per-loan proceeds vault and the loan stays Active — the proceeds only leave to your wallet via your own borrower-signed repay. Pick exactly one trigger: target (e.g. '2x' TP / '0.7x' SL), price_usd, mc_usd (e.g. '5M','1.2B'), or trailing_bps (SL only). direction defaults to 'above' (TP); use 'below' for a stop-loss. The envelope is signed with the configured payer keypair, and the x402 payment pays from that SAME keypair, so payer==signer holds (the bot rejects any mismatch). Only works on V4 loans you own. Paid: 0.001 SOL.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                loan_id: {
+                    type: "string",
+                    description: "The u64 loan ID of your active V4 loan to arm the exit on.",
+                },
+                direction: {
+                    type: "string",
+                    enum: ["above", "below"],
+                    description: "above = take-profit (default), below = stop-loss.",
+                },
+                target: {
+                    type: "string",
+                    description: "Multiplier trigger, e.g. '2x' for a 2x take-profit or '0.7x' for a stop-loss. One trigger only.",
+                },
+                price_usd: {
+                    type: "string",
+                    description: "Absolute USD price-per-token trigger. One trigger only.",
+                },
+                mc_usd: {
+                    type: "string",
+                    description: "Market-cap trigger, e.g. '5M' or '1.2B'. One trigger only.",
+                },
+                trailing_bps: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "Trailing stop distance in basis points (stop-loss / direction=below only). One trigger only.",
+                },
+                slippage_bps: {
+                    type: "integer",
+                    minimum: 0,
+                    description: "Max slippage tolerance for the in-vault sell, in basis points.",
+                },
+                dest: {
+                    type: "string",
+                    enum: ["sol", "usdc"],
+                    description: "Proceeds asset accumulated in the vault. Defaults to sol.",
+                },
+                slice: {
+                    type: "string",
+                    description: "Optional fraction/size of the position to sell at this trigger (for laddered exits). Omit to sell the full position.",
+                },
+            },
+            required: ["loan_id"],
+        },
+    },
+    {
+        name: "magpie_modify_exit",
+        description: "Modify an existing armed in-vault exit order on your own V4 loan — change its trigger or execution params without cancelling and re-arming. Signed with the configured payer keypair (payer==signer). FREE.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                order_id: {
+                    type: "string",
+                    description: "The ID of the armed exit order to modify.",
+                },
+                price_usd: { type: "string", description: "New absolute USD price trigger." },
+                mc_usd: { type: "string", description: "New market-cap trigger, e.g. '5M'." },
+                target: { type: "string", description: "New multiplier trigger, e.g. '2x' / '0.7x'." },
+                trailing_bps: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "New trailing stop distance in basis points (SL only).",
+                },
+                slippage_bps: {
+                    type: "integer",
+                    minimum: 0,
+                    description: "New max slippage tolerance in basis points.",
+                },
+                dest: {
+                    type: "string",
+                    enum: ["sol", "usdc"],
+                    description: "New proceeds asset for the in-vault sell.",
+                },
+            },
+            required: ["order_id"],
+        },
+    },
+    {
+        name: "magpie_cancel_exit",
+        description: "Cancel an armed in-vault exit order on your own V4 loan. The loan stays Active and unaffected; only the pending auto-sell is removed. Signed with the configured payer keypair (payer==signer). FREE.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                order_id: {
+                    type: "string",
+                    description: "The ID of the armed exit order to cancel.",
+                },
+            },
+            required: ["order_id"],
+        },
+    },
+    {
+        name: "magpie_list_exits",
+        description: "List the armed in-vault exit orders for a wallet — each order's loan, direction, trigger, distance-to-trigger, and status. Use to audit what's armed before modifying or cancelling. FREE.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                wallet: {
+                    type: "string",
+                    description: "The wallet whose armed exit orders to list.",
+                },
+            },
+            required: ["wallet"],
+        },
+    },
+    {
+        name: "magpie_loan_by_pda",
+        description: "Fetch a single Magpie loan by its on-chain loan PDA (account address). Returns the loan's program version, status, collateral, due timestamp, and (for V4) proceeds-vault context. FREE.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                loan_pda: {
+                    type: "string",
+                    description: "The on-chain loan PDA / account address.",
+                },
+            },
+            required: ["loan_pda"],
+        },
+    },
+    {
+        name: "magpie_pools",
+        description: "List the Magpie lending pools (program versions and their pool context) — V1 memecoin and V4 in-vault-exit lanes. FREE.",
+        inputSchema: { type: "object", properties: {} },
+    },
 ];
 // ── Server wiring ─────────────────────────────────────────────────
 const server = new Server({
@@ -369,6 +514,62 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
                     query: { id: String(a.id) },
                 });
                 break;
+            // ── V4 in-vault exit orders ──────────────────────────────────
+            case "magpie_arm_exit": {
+                // PAID. The envelope MUST be signed by the SAME keypair that pays
+                // the x402 challenge, so the bot's payer==signer guard holds.
+                const kp = requirePayer();
+                const fields = {
+                    LoanId: String(a.loan_id),
+                    Direction: a.direction !== undefined ? String(a.direction) : undefined,
+                    Target: a.target !== undefined ? String(a.target) : undefined,
+                    Price: a.price_usd !== undefined ? String(a.price_usd) : undefined,
+                    MC: a.mc_usd !== undefined ? String(a.mc_usd) : undefined,
+                    Trailing: a.trailing_bps !== undefined ? String(a.trailing_bps) : undefined,
+                    Slippage: a.slippage_bps !== undefined ? String(a.slippage_bps) : undefined,
+                    Slice: a.slice !== undefined ? String(a.slice) : undefined,
+                    Dest: a.dest !== undefined ? String(a.dest) : undefined,
+                };
+                const env = buildSignedEnvelope(kp, "limit-close-arm/v1", fields);
+                result = await call(ctx, "POST", "/api/v1/agent/self-limit-close/arm", { body: env });
+                break;
+            }
+            case "magpie_modify_exit": {
+                // FREE — still envelope-signed by the payer keypair (payer==signer).
+                const kp = requirePayer();
+                const fields = {
+                    OrderId: String(a.order_id),
+                    Price: a.price_usd !== undefined ? String(a.price_usd) : undefined,
+                    MC: a.mc_usd !== undefined ? String(a.mc_usd) : undefined,
+                    Target: a.target !== undefined ? String(a.target) : undefined,
+                    Trailing: a.trailing_bps !== undefined ? String(a.trailing_bps) : undefined,
+                    Slippage: a.slippage_bps !== undefined ? String(a.slippage_bps) : undefined,
+                    Dest: a.dest !== undefined ? String(a.dest) : undefined,
+                };
+                const env = buildSignedEnvelope(kp, "limit-close-modify/v1", fields);
+                result = await call(ctx, "POST", "/api/v1/agent/self-limit-close/modify", { body: env });
+                break;
+            }
+            case "magpie_cancel_exit": {
+                // FREE — envelope-signed by the payer keypair (payer==signer).
+                const kp = requirePayer();
+                const env = buildSignedEnvelope(kp, "limit-close-cancel/v1", {
+                    OrderId: String(a.order_id),
+                });
+                result = await call(ctx, "POST", "/api/v1/agent/self-limit-close/cancel", { body: env });
+                break;
+            }
+            case "magpie_list_exits":
+                result = await call(ctx, "GET", "/api/v1/agent/self-limit-close/list", {
+                    query: { wallet: String(a.wallet) },
+                });
+                break;
+            case "magpie_loan_by_pda":
+                result = await call(ctx, "GET", `/api/v1/loan/by-pda/${encodeURIComponent(String(a.loan_pda))}`);
+                break;
+            case "magpie_pools":
+                result = await call(ctx, "GET", "/api/v1/pools");
+                break;
             default:
                 return {
                     isError: true,

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@magpieloans/magpie-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
+  "mcpName": "io.github.magpiecapital/magpie-mcp",
   "description": "MCP server exposing Magpie Capital's x402 API as native tools for Claude Desktop, Cursor, Windsurf, ChatGPT desktop, and any MCP-aware agent host.",
   "type": "module",
   "bin": {