@paydprotocol/mcp 0.1.0 → 0.2.0

package/README.md

@@ -14,7 +14,9 @@ claude mcp add payd -- npx -y @paydprotocol/mcp   # any MCP client: same command
 
 Tools: `payd_list_tokens`, `payd_token_info`, `payd_holder_shares`,
 `payd_launch_options`, and the prepare tools `payd_prepare_create_vault`,
-`payd_prepare_launch`, `payd_prepare_bind`, `payd_prepare_claim`. Every prepare
+`payd_prepare_launch`, `payd_prepare_bind`, `payd_prepare_claim`, and for keepers
+`payd_pending_work`, `payd_prepare_harvest`, `payd_prepare_buy_basket` — open
+calls that pay their caller (gas back, or a bounty). Every prepare
 tool simulates from `from` first and returns an error instead of calldata when
 the simulation reverts.
 

package/dist/server.js

@@ -644,6 +644,7 @@ async function listTokens(c, o) {
   }));
   return { total: all.length, offset: o.offset, tokens: rows };
 }
+var pct2 = (bps) => bps === null ? null : `${bps / 100} %`;
 var HOOK = ["not launched", "collecting", "redirect scheduled", "fees lost"];
 async function tokenInfo(c, vault) {
   const i = await createPayd({ vault: requireAddress("vault", vault), client: c }).info();
@@ -651,9 +652,13 @@ async function tokenInfo(c, vault) {
     ...i,
     symbol: untrusted(i.symbol),
     quote: i.quote === ZERO2 ? "native ETH" : i.quote,
+    // Spelled out: a model handed 873 next to totalFeeBps 1000 told holders
+    // "87.3 % of volume" (assistant eval, 2026-10-04). The real figure is 8.73 %.
+    holdersGetPercentOfVolume: pct2(i.rewardsOfVolumeBps),
+    creatorGetsPercentOfVolume: pct2(i.creatorOfVolumeBps),
     hookStatus: i.hookStatus === null ? null : { code: i.hookStatus, meaning: HOOK[i.hookStatus] },
     warning: i.hookStatus !== null && i.hookStatus !== 1 ? "Fees are not (or soon will not be) arriving at this launch. Say so; do not quote its percentages as current." : void 0,
-    note: "rewardsOfVolumeBps is a share of TRADED VOLUME paid to holders as stock, not a yield. null means unread \u2014 hide it, never show 0."
+    note: "holdersGetPercentOfVolume is a share of TRADED VOLUME paid to holders as stock, not a yield; quote it as written, never recompute it from the bps fields. null means unread \u2014 hide it, never show 0."
   };
 }
 async function holderShares(c, vault, holder) {
@@ -1357,7 +1362,8 @@ var registryAbi2 = parseAbi4([
   "function listing(address stock) view returns (uint24 poolFee, address feed, bool allowed)",
   "function quoteListing(address quote) view returns (uint24 poolFee, uint24 wethFee, uint256 minBuy, bool allowed)",
   "function platformBps() view returns (uint256)",
-  "function isVault(address vault) view returns (bool)"
+  "function isVault(address vault) view returns (bool)",
+  "function vaults() view returns (address[])"
 ]);
 var vaultAbi2 = parseAbi4([
   "function bind(address token)",
@@ -1365,6 +1371,10 @@ var vaultAbi2 = parseAbi4([
   "function token() view returns (address)",
   "function QUOTE() view returns (address)"
 ]);
+var cycleAbi = parseAbi4([
+  "function harvest() returns (uint256 gross)",
+  "function buyBasket(uint256[] minOuts) returns (uint256 legsBought)"
+]);
 var claimAbi = parseAbi4([
   "function claim(address[] stocks, uint256[] cumulative, bytes32[][] proofs) returns (uint256 delivered)"
 ]);
@@ -1485,10 +1495,49 @@ async function prepareClaim(c, i) {
     notes: ["Proofs are valid for the CURRENT root only; a new one is published every epoch. Sign and send now, or prepare again."]
   };
 }
+async function registryVault(c, v) {
+  const vault = requireAddress("vault", v);
+  if (!await c.readContract({ address: REGISTRY, abi: registryAbi2, functionName: "isVault", args: [vault] })) {
+    throw new Error(`${vault} is not a vault the Payd registry built`);
+  }
+  return vault;
+}
+var PAYS = "An ETH-quoted vault refunds the caller's gas; any other quote pays a bounty in its own currency. A wallet that refuses ETH gets its refund set aside: collect it with the vault's withdraw().";
+async function prepareHarvest(c, i) {
+  const vault = await registryVault(c, i.vault);
+  return {
+    ...await prepare(c, { from: requireAddress("from", i.from), to: vault, abi: cycleAbi, functionName: "harvest", args: [] }),
+    notes: [PAYS]
+  };
+}
+async function prepareBuyBasket(c, i) {
+  const vault = await registryVault(c, i.vault);
+  const legs = (await createPayd({ vault, client: c }).info()).basket.length;
+  const minOuts = Array(legs).fill(0n);
+  return {
+    ...await prepare(c, { from: requireAddress("from", i.from), to: vault, abi: cycleAbi, functionName: "buyBasket", args: [minOuts] }),
+    notes: [PAYS, "minOuts are zeros: the vault's own oracle floor bounds every leg. Do not loosen it \u2014 you cannot."]
+  };
+}
+async function pendingWork(c, i) {
+  const vaults = i.vault ? [await registryVault(c, i.vault)] : await c.readContract({ address: REGISTRY, abi: registryAbi2, functionName: "vaults" });
+  const status = (p) => p.then(() => "ready", (e) => e.message);
+  const rows = await Promise.all(vaults.map(async (vault) => ({
+    vault,
+    harvest: await status(prepareHarvest(c, { vault, from: i.from })),
+    buyBasket: await status(prepareBuyBasket(c, { vault, from: i.from }))
+  })));
+  const ready = rows.filter((r) => r.harvest === "ready" || r.buyBasket === "ready");
+  return {
+    ready,
+    idle: rows.length - ready.length,
+    note: '"ready" means it simulated from `from` just now; another caller may land first, and NothingToDo is then the normal answer. Harvest before buyBasket. distribute() is not offered here: it needs the push tree.'
+  };
+}
 
 // src/server.ts
 var client = makeClient();
-var server = new McpServer({ name: "payd", version: "0.1.0" });
+var server = new McpServer({ name: "payd", version: "0.2.0" });
 var run = async (f) => {
   try {
     return { content: [{ type: "text", text: toJson(await f()) }] };
@@ -1562,4 +1611,20 @@ server.registerTool("payd_prepare_claim", {
   inputSchema: { vault: address, holder: address },
   annotations: PREPARE_HINTS
 }, (a) => run(() => prepareClaim(client, a)));
+var KEEPER = "Open to anyone and pays its caller (docs/SDK.md \xA79); it gives no say over where the money goes. ";
+server.registerTool("payd_pending_work", {
+  description: "For keepers: which Payd vaults have a harvest or a buyBasket that would succeed right now, simulated from `from`. Omit vault to scan every launch. " + KEEPER,
+  inputSchema: { from: address, vault: address.optional() },
+  annotations: READ_ONLY
+}, (a) => run(() => pendingWork(client, a)));
+server.registerTool("payd_prepare_harvest", {
+  description: "Pull a launch's creator fees out of the Pons escrow and split them. " + KEEPER + PREPARE,
+  inputSchema: { vault: address, from: address },
+  annotations: PREPARE_HINTS
+}, (a) => run(() => prepareHarvest(client, a)));
+server.registerTool("payd_prepare_buy_basket", {
+  description: "Buy a launch's whole stock basket for every closed epoch not yet bought; slippage is bounded by the vault's own oracle floor. Harvest first. " + KEEPER + PREPARE,
+  inputSchema: { vault: address, from: address },
+  annotations: PREPARE_HINTS
+}, (a) => run(() => prepareBuyBasket(client, a)));
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydprotocol/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Keyless MCP server for Payd on Robinhood Chain: read launches, baskets and holder shares, and prepare unsigned transactions for your own wallet.",
   "type": "module",
   "license": "MIT",