@ripplesdotrun/mcp 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# @ripplesdotrun/mcp
+
+An MCP server for [Ripples](https://ripples.run) agent launches. It lets a model create an agent
+with its own token market and NFT collection, and then run that agent: buy its own token, mint its
+own art, pay its bills, and write a public run log.
+
+What makes this safe to hand to a model is not the server. It is the contract underneath: the
+agent's money sits in a treasury with spending limits fixed before the first mint, no owner, no
+setter and no withdrawal. A model that goes wrong reaches one day's budget and the addresses the
+charter published, and nothing else.
+
+## Use it
+
+```json
+{
+  "mcpServers": {
+    "ripples": {
+      "command": "npx",
+      "args": ["-y", "@ripplesdotrun/mcp"],
+      "env": {
+        "RIPPLES_PRIVATE_KEY": "0x…",
+        "RIPPLES_NETWORK": "robinhood",
+        "RIPPLES_TREASURY": "0x…"
+      }
+    }
+  }
+}
+```
+
+`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.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `ripples_launch_agent` | Creates the token, the market, the collection and the agent's contract, in one transaction |
+| `ripples_agent_buy` | Buys its own token on its own market |
+| `ripples_agent_sell` | Sells it back, inside the charter's daily ceiling |
+| `ripples_agent_mint` | Mints from its own collection |
+| `ripples_agent_pay` | Pays one of the published addresses |
+| `ripples_agent_note` | Writes to the public run log |
+| `ripples_agent_claim` | Takes in the trade fees and the collection's share of every mint |
+| `ripples_agent_status` | The charter, what is left of today's limits, and the launch's addresses |
+| `ripples_agent_activity` | Everything the agent has done, newest first |
+
+A call the charter forbids fails on chain and comes back saying which limit it hit, for example
+`OverDailySell(100, 0)` for an agent that may never sell.
+
+## The key
+
+`RIPPLES_PRIVATE_KEY` signs everything. Give it the agent's own operator key, not a wallet that
+holds anything else: the charter bounds what that key can do with the agent's money and bounds
+nothing about the rest of the wallet.
+
+## Licence
+
+MIT

package/dist/server.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { privateKeyToAccount } from "viem/accounts";
+import { createRipplesAgent, DEPLOYMENTS, } from "@ripplesdotrun/agent-sdk";
+// The key signs everything this server does. What it can do with the agent's money is bounded on
+// 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.
+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) {
+        if (!KEY) {
+            throw new Error("Set RIPPLES_PRIVATE_KEY to a wallet that can sign, then restart.");
+        }
+        client = createRipplesAgent({
+            network: NETWORK,
+            account: privateKeyToAccount(KEY),
+            ...(TREASURY ? { treasury: TREASURY } : {}),
+        });
+    }
+    return client;
+}
+const server = new McpServer({ name: "ripples", version: "0.1.0" });
+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}`;
+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\"."),
+    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 "
+        + "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."),
+    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."),
+}, async (input) => {
+    const client = agent();
+    const result = await client.launch({
+        runway: input.runway,
+        charter: {
+            operator: (input.operator ?? client.deployment.agentTreasuryFactory),
+            dailySpend: input.dailySpend,
+            perCallSpend: input.perTransactionSpend,
+            ...(input.dailySell ? { dailySell: input.dailySell } : {}),
+            ...(input.dailyMint ? { dailyMint: input.dailyMint } : {}),
+            ...(input.payees ? { payees: input.payees } : {}),
+        },
+        token: {
+            name: input.name,
+            symbol: input.symbol,
+            image: input.image,
+            ...(input.description ? { description: input.description } : {}),
+            ...(input.website ? { website: input.website } : {}),
+            ...(input.twitter ? { twitter: input.twitter } : {}),
+        },
+        collection: {
+            name: `${input.name} Pieces`,
+            symbol: `${input.symbol}P`,
+            price: input.mintPrice,
+            supply: input.collectionSupply,
+            baseUri: input.artworkBaseUri,
+        },
+    });
+    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)) }));
+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)) }));
+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 ?? "")) }));
+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_status", "What the agent may do, what is left of today's limits, and the addresses of its launch.", {}, async () => {
+    const client = agent();
+    const [charter, budget, launched] = await Promise.all([
+        client.charter(),
+        client.budget(),
+        client.launched(),
+    ]);
+    return say({ treasury: client.treasury, network: client.network, 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());

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ripplesdotrun/mcp",
+  "version": "0.1.0",
+  "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",
+    "model-context-protocol",
+    "ripples",
+    "agent",
+    "launchpad",
+    "robinhood-chain"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ripples-mcp": "./dist/server.js"
+  },
+  "main": "./dist/server.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@ripplesdotrun/agent-sdk": "^0.1.0",
+    "viem": "^2.21.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "typescript": "^5.6.0"
+  },
+  "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"
+}