@ripplesdotrun/mcp 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ripples
+
+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

@@ -28,7 +28,13 @@ charter published, and nothing else.
 ```
 
 `RIPPLES_NETWORK` is `robinhood` (chain 4663) or `robinhood-testnet`. `RIPPLES_TREASURY` names an
-agent that already exists; leave it out and `ripples_launch_agent` fills it in.
+agent that already exists.
+
+Leave `RIPPLES_TREASURY` out and `ripples_launch_agent` sets it for the rest of the session.
+It is held in memory, so copy the `treasury` address it returns into the config before you
+restart: nothing else can find it for you.
+
+ESM only, Node 20 or newer.
 
 ## Tools
 

package/dist/server.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -8,15 +9,20 @@ import { createRipplesAgent, DEPLOYMENTS, } from "@ripplesdotrun/agent-sdk";
 // chain by the charter the launch was created under, not by anything here: there is no owner, no
 // setter and no withdrawal on a treasury, so a key in the wrong hands reaches one day's budget
 // and the addresses the charter published, and nothing else.
+// Read off the manifest so it cannot drift from what was published.
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const KEY = process.env.RIPPLES_PRIVATE_KEY;
 const NETWORK = (process.env.RIPPLES_NETWORK ?? "robinhood");
 const TREASURY = process.env.RIPPLES_TREASURY;
-if (!DEPLOYMENTS[NETWORK]) {
-    throw new Error(`RIPPLES_NETWORK must be one of ${Object.keys(DEPLOYMENTS).join(", ")}.`);
-}
 let client;
 function agent() {
     if (!client) {
+        // Checked here rather than at startup. A server that exits during the handshake shows the
+        // user "Connection closed" and files the reason in a log; a tool that refuses shows them the
+        // sentence. `hasOwn` rather than a truthiness test, or `RIPPLES_NETWORK=constructor` passes.
+        if (!Object.hasOwn(DEPLOYMENTS, NETWORK)) {
+            throw new Error(`RIPPLES_NETWORK must be one of ${Object.keys(DEPLOYMENTS).join(", ")}.`);
+        }
         if (!KEY) {
             throw new Error("Set RIPPLES_PRIVATE_KEY to a wallet that can sign, then restart.");
         }
@@ -28,39 +34,58 @@ function agent() {
     }
     return client;
 }
-const server = new McpServer({ name: "ripples", version: "0.1.0" });
+const server = new McpServer({ name: "ripples", version: VERSION });
 const say = (value) => ({
     content: [{ type: "text", text: JSON.stringify(value, bigints, 2) }],
 });
 const bigints = (_key, value) => typeof value === "bigint" ? value.toString() : value;
 const explorer = (hash) => `${DEPLOYMENTS[NETWORK].explorer}/tx/${hash}`;
+/** A wallet address, checked for shape. Correctness is not something this can check. */
+const address = z.string().regex(/^0x[0-9a-fA-F]{40}$/, "Expected a 0x wallet address.");
+/// Amounts cross the wire as decimal strings so nothing rounds through a float on the way.
+const amount = (what) => z
+    .string()
+    .regex(/^\d+(\.\d+)?$/, `${what} is a decimal string, for example "0.05".`)
+    .refine((value) => Number(value) > 0, `${what} has to be above zero.`);
 server.tool("ripples_launch_agent", "Create an agent on Ripples: its token and market, its NFT collection, and the contract that "
     + "holds its money. The contract is the launch's creator, so the creator's 70% of every trade "
     + "fee becomes the agent's working capital. The spending limits are fixed in this call and "
     + "nobody, including the creator, can raise them afterwards.", {
     name: z.string().describe("The project's name, used for the token and the collection."),
-    symbol: z.string().describe("Ticker, 2 to 10 characters."),
-    image: z.string().url().describe("Public image URL. The token carries it on chain."),
-    description: z.string().optional(),
-    website: z.string().url().optional(),
-    twitter: z.string().url().optional(),
-    mintPrice: z.string().describe("Price per NFT, in the market's asset, e.g. \"0.01\"."),
+    symbol: z.string().min(2).max(10).describe("Ticker, 2 to 10 characters."),
+    image: z.string().url().max(512).describe("Public image URL. The token carries it on chain."),
+    description: z.string().max(2048).optional(),
+    website: z.string().url().max(256).optional(),
+    twitter: z.string().url().max(256).optional(),
+    mintPrice: amount("mintPrice").describe("Price per NFT, in the market's asset."),
     collectionSupply: z.number().int().positive(),
-    artworkBaseUri: z.string().describe("Where the finished artwork lives, with a trailing slash."),
-    runway: z.string().describe("What goes into the agent's contract, in the market's asset. Covers the launch fee and is "
+    artworkBaseUri: z
+        .string()
+        .url()
+        .refine((value) => value.endsWith("/"), "A base URI has to end in a slash.")
+        .describe("Where the finished artwork lives, with a trailing slash."),
+    runway: amount("runway").describe("What goes into the agent's contract, in the market's asset. Covers the launch fee and is "
         + "what the agent works with until its market earns."),
-    operator: z.string().optional().describe("The wallet that works the agent. Defaults to this server's own wallet."),
-    dailySpend: z.string().describe("Most it can spend in a day. Buys, mints and payouts share it."),
-    perTransactionSpend: z.string().describe("Most it can spend in one transaction."),
-    dailySell: z.string().optional().describe("Most of its own token it can sell in a day. Leave it out and it can never sell."),
+    operator: address.optional().describe("The wallet that works the agent. Defaults to this server's own wallet. It is fixed for "
+        + "the life of the launch, and an address that cannot sign leaves the agent inoperable."),
+    dailySpend: amount("dailySpend").describe("Most it can spend in a day. Buys, mints and payouts share it."),
+    perTransactionSpend: amount("perTransactionSpend").describe("Most it can spend in one transaction. At least the mint price, or it can never mint."),
+    dailySell: amount("dailySell").optional().describe("Most of its own token it can sell in a day. Leave it out and it can never sell."),
     dailyMint: z.number().int().min(0).optional().describe("Pieces it can mint a day. Default none."),
-    payees: z.array(z.string()).optional().describe("The only addresses it will ever be able to pay. Leave it out and it can pay nobody."),
+    payees: z.array(address).max(8).optional().describe("The only addresses it will ever be able to pay. Leave it out and it can pay nobody."),
 }, async (input) => {
     const client = agent();
+    // The operator is the only key that will ever be able to spend, and there is no setter, so
+    // an agent created against an address that cannot sign is inoperable for good. Defaulting to
+    // this server's own wallet is the only default that can work.
+    const operator = (input.operator ?? client.address);
+    if (!operator) {
+        throw new Error("No operator. Pass one, or set RIPPLES_PRIVATE_KEY so this server has a wallet.");
+    }
     const result = await client.launch({
         runway: input.runway,
         charter: {
-            operator: (input.operator ?? client.deployment.agentTreasuryFactory),
+            operator,
             dailySpend: input.dailySpend,
             perCallSpend: input.perTransactionSpend,
             ...(input.dailySell ? { dailySell: input.dailySell } : {}),
@@ -86,23 +111,52 @@ server.tool("ripples_launch_agent", "Create an agent on Ripples: its token and m
     return say({ ...result, transactionUrl: explorer(result.transaction) });
 });
 server.tool("ripples_agent_buy", "Buy the agent's own token on its own market, into its own contract. Counts against the daily "
-    + "and per-transaction spending limits.", { amount: z.string().describe("How much of the market's asset to spend.") }, async ({ amount }) => say({ transactionUrl: explorer(await agent().buy(amount)) }));
+    + "and per-transaction spending limits.", { amount: amount("amount").describe("How much of the market's asset to spend.") }, async ({ amount }) => say({ transactionUrl: explorer(await agent().buy(amount)) }));
 server.tool("ripples_agent_sell", "Sell the agent's own token back into its market. Refused outright when the charter's daily "
-    + "sell ceiling is zero, which is the default.", { amount: z.string().describe("How much of its own token to sell.") }, async ({ amount }) => say({ transactionUrl: explorer(await agent().sell(amount)) }));
+    + "sell ceiling is zero, which is the default.", { amount: amount("amount").describe("How much of its own token to sell.") }, async ({ amount }) => say({ transactionUrl: explorer(await agent().sell(amount)) }));
 server.tool("ripples_agent_mint", "Mint from the agent's own collection. The pieces stay with the agent, and the mint funds its "
-    + "own market like anyone else's.", { quantity: z.number().int().positive() }, async ({ quantity }) => say({ transactionUrl: explorer(await agent().mint(quantity)) }));
-server.tool("ripples_agent_pay", "Pay one of the addresses the charter published. Any other address is refused on chain.", { to: z.string(), amount: z.string() }, async ({ to, amount }) => say({ transactionUrl: explorer(await agent().pay(to, amount)) }));
-server.tool("ripples_agent_note", "Write an entry in the agent's public run log, beside the transactions it describes.", { text: z.string(), uri: z.string().optional() }, async ({ text, uri }) => say({ transactionUrl: explorer(await agent().note(text, uri ?? "")) }));
+    + "own market like anyone else's.", { quantity: z.number().int().min(1).max(20).describe("1 to 20; the collection caps a mint at 20.") }, async ({ quantity }) => say({ transactionUrl: explorer(await agent().mint(quantity)) }));
+server.tool("ripples_agent_pay", "Pay one of the addresses the charter published. Any other address is refused on chain.", { to: address, amount: amount("amount") }, async ({ to, amount }) => say({ transactionUrl: explorer(await agent().pay(to, amount)) }));
+server.tool("ripples_agent_note", "Write an entry in the agent's public run log, beside the transactions it describes. The text "
+    + "is committed as a hash and the `uri` is published next to it, so an entry with no `uri` is "
+    + "a dated digest nobody can read back. Pass a link to what the entry is about.", { text: z.string(), uri: z.string().url().optional() }, async ({ text, uri }) => say({ transactionUrl: explorer(await agent().note(text, uri ?? "")) }));
 server.tool("ripples_agent_claim", "Take in what the launch has earned: the creator's share of every trade and the collection's "
     + "share of every mint. Permissionless, and it can only pay the agent.", {}, async () => say({ transactionUrl: explorer(await agent().claim()) }));
+server.tool("ripples_agent_claim_vested", "Take in the token slice the agent's own mints earned it. Separate from the fee claim because "
+    + "it only pays out once the market has reached its target, and a claim with nothing vested "
+    + "would otherwise fail the other one.", {}, async () => say({ transactionUrl: explorer(await agent().claimVested()) }));
 server.tool("ripples_agent_status", "What the agent may do, what is left of today's limits, and the addresses of its launch.", {}, async () => {
     const client = agent();
+    // Answered before there is an agent too. This is where a new user finds the address their
+    // key loaded as, which is the address they have to fund before a launch will go through.
+    const base = {
+        network: client.network,
+        signer: client.address ?? null,
+        settlesIn: client.deployment.quoteSymbol,
+        treasury: client.treasury ?? null,
+    };
+    if (!client.treasury)
+        return say(base);
     const [charter, budget, launched] = await Promise.all([
         client.charter(),
         client.budget(),
         client.launched(),
     ]);
-    return say({ treasury: client.treasury, network: client.network, charter, budget, launched });
+    return say({ ...base, charter, budget, launched });
 });
-server.tool("ripples_agent_activity", "Everything the agent has done, newest first, read from its own contract.", { limit: z.number().int().positive().max(200).optional() }, async ({ limit }) => say(await agent().activity(limit ?? 25)));
-await server.connect(new StdioServerTransport());
+server.tool("ripples_agent_activity", "Everything the agent has done, newest first, read from its own contract.", {
+    limit: z.number().int().positive().max(200).optional(),
+    fromBlock: z.number().int().nonnegative().optional().describe("Providers cap how many blocks one log query may span. Defaults to the last 50,000."),
+}, async ({ limit, fromBlock }) => say(await agent().activity({
+    limit: limit ?? 25,
+    ...(fromBlock === undefined ? {} : { fromBlock: BigInt(fromBlock) }),
+})));
+try {
+    await server.connect(new StdioServerTransport());
+}
+catch (reason) {
+    // stdout is the protocol channel, so a startup failure goes to stderr and takes the process
+    // with it rather than surfacing as an unhandled rejection.
+    console.error(reason instanceof Error ? reason.message : String(reason));
+    process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ripplesdotrun/mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP server for Ripples agent launches: create an agent with its own market, collection and spending limits, then let it work itself.",
   "keywords": [
     "mcp",
@@ -24,13 +24,14 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build",
-    "start": "node dist/server.js"
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "start": "node dist/server.js",
+    "prepack": "npm run build",
+    "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "@ripplesdotrun/agent-sdk": "^0.1.0",
+    "@ripplesdotrun/agent-sdk": "^0.1.1",
     "viem": "^2.21.0",
     "zod": "^3.23.0"
   },
@@ -41,10 +42,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ripples-dot-run/ripples.git",
-    "directory": "packages/agent-mcp"
-  },
-  "homepage": "https://ripples.run/docs#rh-agents"
+  "homepage": "https://ripples.run/docs#rh-agents",
+  "bugs": {
+    "url": "https://ripples.run/docs#rh-agents"
+  }
 }