@agentutility/mcp-rollforge 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# @agentutility/mcp-rollforge
+
+> The whole tabletop toolkit, one call at a time.
+
+Dice, characters, NPCs, encounters, loot, and the full 5e SRD reference — monsters, spells, equipment, classes, races, conditions, magic items. Build a character, stat an encounter, resolve the rolls, and look up every rule without leaving the cluster.
+
+**Pricing:** pay-per-call in USDC on Base. No subscriptions, no API keys. See per-tool prices below.
+
+## Install — Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "agentutility-rollforge": {
+      "command": "npx",
+      "args": ["-y", "@agentutility/mcp-rollforge"],
+      "env": { "X402_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HEX" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. 26 tools appear in the tool palette.
+
+## Install — Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentutility-rollforge": {
+      "command": "npx",
+      "args": ["-y", "@agentutility/mcp-rollforge"],
+      "env": { "X402_PRIVATE_KEY": "0x..." }
+    }
+  }
+}
+```
+
+## Funding
+
+Send any amount of **USDC on Base mainnet** to the address derived from your `X402_PRIVATE_KEY`. The MCP server uses it to pay for tool calls automatically.
+
+USDC on Base contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+
+## Tools (26)
+
+| Tool | Description |
+|---|---|
+| `ability-check` | (0.001 USDC/call) D20 ability check / skill check / attack roll / saving throw resolver API for tabletop RPGs. Rolls a d20 with an optional modifier and advantage/disadvantage, compares to a DC, and reports total, success/failure, and natural-20 / natural-1. Seedable. Pure deterministic compute, no upstream API. |
+| `background-gen` | (0.001 USDC/call) Character background generator API / personality trait, ideal, bond, flaw generator for tabletop RPGs. Rolls the four roleplaying hooks for a character sheet — a personality trait, an ideal, a bond, and a flaw. Seedable. Pure compute, no upstream. Original generic-fantasy phrasing. |
+| `character-gen` | (0.002 USDC/call) Tabletop character generator API / D&D 5e character builder / RPG character creator / random fantasy character. Generates a complete 5e-style character: ability scores (4d6-keep-highest-3, 3d6, or standard array) assigned by class priority, race / class / background / alignment, racial ability bonuses, derived hit points, ability modifiers, proficiency bonus, saving-throw proficiencies, and a procedurally generated name. Pin any field (race, class, level 1-20, method, name) or omit to randomize; pass 'seed' for a reproducible character. Pure deterministic compute, no upstream API. Uses only 5e SRD content (OGL 1.0a / CC-BY-4.0). |
+| `character-portrait` | (0.08 USDC/call) Character portrait generator API / RPG character art / D&D character image / fantasy avatar generator. Builds a portrait from structured inputs — race, class, gender, a free-text description, and an art style (fantasy-art, realistic, anime, oil-painting, ink-sketch, watercolor, pixel-art, comic-book) — and renders it to a hosted PNG URL. Pairs with character-gen: generate the character, then its portrait. Text-to-image via Venice, output hosted on fal. |
+| `class-lookup` | (0.003 USDC/call) D&D 5e class lookup API / SRD class reference / class proficiencies and hit dice. Look up a class by name for hit dice, armor/weapon/tool/skill proficiencies, saving throws, spellcasting ability, and starting equipment, or list all SRD classes. SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e. |
+| `condition-lookup` | (0.003 USDC/call) D&D 5e condition lookup API / SRD conditions reference (blinded, grappled, prone, stunned, etc.). Look up a condition by name for its full rules text, or list all SRD conditions. SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e. |
+| `dice-roll` | (0.001 USDC/call) Dice roller API / dice notation evaluator / RPG dice / tabletop random roll engine. Evaluates standard dice notation — XdY, flat modifiers (+/-), and keep-highest / keep-lowest (4d6kh3 for stat rolls, 2d20kh1 / 2d20kl1 for advantage/disadvantage). Returns each individual die, which were kept vs dropped, the per-roll total, and the grand total; roll the whole expression up to 100 times with 'rolls'. Pass 'seed' for reproducible output. Pure deterministic compute, no upstream API. |
+| `dice-stats` | (0.002 USDC/call) Dice probability calculator API / anydice-style dice statistics / odds of a dice roll. For plain XdY+mod returns the EXACT distribution (mean, stdev, min, max, and P(>= target)); for keep-highest/lowest (4d6kh3, 2d20kl1) estimates via seeded Monte Carlo. For sizing DCs, damage, and stat rolls. Pure compute, no upstream. |
+| `dungeon-room` | (0.001 USDC/call) Dungeon room generator API / random dungeon generator / D&D room description for GMs. Generates a room: shape, contents, a notable feature, a hazard, an occupant, and the number of exits. Pass 'rooms' for a small batch. Seedable. Pure compute, no upstream. |
+| `encounter-builder` | (0.002 USDC/call) Encounter builder / encounter difficulty calculator API for D&D 5e. Give the party (levels, or size + level) to get easy/medium/hard/deadly XP thresholds; optionally give monster CRs to get the multiplier-adjusted XP and the resulting difficulty rating. SRD DMG tables (OGL 1.0a / CC-BY-4.0). Pure compute, no upstream. |
+| `equipment-lookup` | (0.003 USDC/call) D&D 5e equipment lookup API / SRD weapons and armor / gear stats. Look up a weapon or piece of armor by name (weapon damage dice/type/properties/cost, or armor class/cost/weight/stealth), or list items by type ('weapon' or 'armor'). SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e. |
+| `initiative-roll` | (0.001 USDC/call) Initiative tracker / initiative order roller API for tabletop combat. Each combatant rolls 1d20 plus their initiative (DEX) modifier; returns the full turn order, ties broken by modifier then input order. Seedable. Pure deterministic compute, no upstream API. |
+| `loot-gen` | (0.002 USDC/call) Loot generator / treasure generator API for D&D 5e. Rolls coins (and, for hoards, gems/art objects and a magic-item slot) scaled by a challenge-rating band. SRD-style treasure math (OGL 1.0a / CC-BY-4.0). Seedable. Pure compute, no upstream. |
+| `magic-item-lookup` | (0.003 USDC/call) D&D 5e magic item lookup API / SRD magic items / wondrous item reference. Look up a magic item by name for its type, rarity, attunement, and full description, or list items filtered by rarity and/or type. SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e. |
+| `monster-lookup` | (0.003 USDC/call) D&D 5e monster lookup API / SRD monster stat block / bestiary search. Look up a monster by name for a compact stat block (size, type, alignment, AC, HP, hit dice, speed, ability scores, challenge rating, and actions), or list monsters filtered by challenge rating and/or type. SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e. |
+| `name-gen` | (0.001 USDC/call) Fantasy name generator API / RPG name generator / D&D character & NPC names / random fantasy names by race. Generates original syllable-built names, optionally flavored by race (Dwarf, Elf, Half-Orc, etc.). Batch up to 50 at once with 'count'; pass 'seed' for reproducible output. Pure deterministic compute, no upstream API. |
+| `npc-gen` | (0.001 USDC/call) NPC generator API / random D&D NPC / tabletop character generator for GMs. Generates a quick non-player character: name, race, occupation, personality trait, distinctive appearance, mannerism, and a hidden secret/plot hook. Pin race or occupation, or omit to randomize. Seedable. Pure compute, no upstream. |
+| `quest-gen` | (0.001 USDC/call) Quest generator API / random plot hook / D&D adventure seed generator. Generates a quest hook: giver, objective, location, complication, and reward, plus a one-line ready-to-read hook. Seedable. Pure compute, no upstream. Original generic-fantasy content. |
+| `race-lookup` | (0.003 USDC/call) D&D 5e race lookup API / SRD race reference / racial traits and ability score increases. Look up a race by name for ability score increases, speed, size, languages, vision, and racial traits, or list all SRD races. SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e. |
+| `random-table` | (0.001 USDC/call) Random table roller API / weighted random picker / loot & rumor table roller. Roll on a caller-provided table — weighted entries ([{value, weight?}]) or classic die-range rows ([{min,max,result}] with a 'die') — any number of times, with or without replacement. Seedable. A generic random-selection utility for any custom table. Pure compute, no upstream. |
+| `settlement-gen` | (0.001 USDC/call) Settlement generator API / random town generator / D&D village & city generator. Generates a settlement: name, size category with a plausible population, government, primary trade, a notable feature, and a current problem the party could engage with. Pin 'size' (hamlet/village/town/city) or randomize. Seedable. Pure compute, no upstream. |
+| `spell-lookup` | (0.003 USDC/call) D&D 5e spell lookup API / SRD spell search / spell card details. Look up a spell by name for full details (level, school, casting time, range, components, duration, concentration, ritual, classes, description, higher-level scaling), or list spells filtered by level and/or school. SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e. |
+| `spell-slots` | (0.001 USDC/call) Spell slots by class and level API / D&D 5e spellcasting slot table / pact magic lookup. Returns the level 1-9 spell-slot array for any 5e class at a given level (full casters, half-casters like Paladin/Ranger, Warlock pact magic, and non-casters), plus proficiency bonus. SRD spellcasting tables (OGL 1.0a / CC-BY-4.0). Pure compute, no upstream. |
+| `tavern-gen` | (0.001 USDC/call) Tavern generator API / random fantasy inn / D&D tavern name & details. Generates a tavern: name, proprietor, the house drink and meal, a notable patron, and a rumor overheard inside. Seedable. Pure compute, no upstream. Original generic-fantasy content. |
+| `weather-gen` | (0.001 USDC/call) Fantasy weather generator API / random RPG weather / tabletop campaign weather forecast. Rolls a day's weather for a climate (temperate, arid, cold, tropical) with conditions and wind. Pass 'days' for a short forecast. Seedable. Pure compute, no upstream. |
+| `xp-level` | (0.001 USDC/call) XP to level calculator / D&D 5e experience table / level from XP lookup API. Give 'xp' to get the current level, XP to the next level, and progress; or give 'level' to get the XP needed to reach it. Returns proficiency bonus. SRD advancement table (OGL/CC). Pure compute, no upstream. |
+
+## How it works
+
+1. Agent calls a tool (e.g. `ability-check`).
+2. MCP server POSTs to `https://x402.agentutility.ai/ability-check`.
+3. The endpoint responds **HTTP 402** with payment instructions.
+4. The MCP server signs an EIP-3009 USDC transfer authorization with `X402_PRIVATE_KEY` and retries.
+5. CDP facilitator settles on Base.
+6. The endpoint returns the actual response.
+
+The agent never sees the payment flow — it just gets the result.
+
+## Links
+
+- Cluster overview: https://agentutility.ai/rollforge/
+- All MCP packages: https://mcp.agentutility.ai/
+- Source: https://github.com/rooz21/x402/tree/main/packages/mcp-rollforge
+
+---
+
+**Version:** 0.1.0 · **License:** MIT

package/dist/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * @agentutility/mcp-<cluster> — stdio MCP server exposing the cluster's
+ * x402-paid endpoints as MCP tools. Forwards every CallToolRequest to
+ * x402.agentutility.ai, where @x402/fetch handles 402 → payment → retry
+ * using the agent's own wallet (X402_PRIVATE_KEY env var).
+ *
+ * Boilerplate is single-sourced at packages/_template/src/index.ts and
+ * copied verbatim into each packages/mcp-<cluster>/src/index.ts by
+ * scripts/generate-mcp-clusters.mjs. The codegen also writes a matching
+ * tools.generated.ts so this file imports CLUSTER_SLUG + VERSION + TOOLS
+ * rather than hard-coding.
+ *
+ * Required env: X402_PRIVATE_KEY (hex EVM key, USDC on Base).
+ * Optional env: X402_BASE_URL (default https://x402.agentutility.ai)
+ *               X402_RPC_URL  (default https://mainnet.base.org)
+ */
+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 { wrapFetchWithPayment, x402Client } from "@x402/fetch";
+import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";
+import { privateKeyToAccount } from "viem/accounts";
+import { createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+import { TOOLS, CLUSTER_SLUG, VERSION } from "./tools.generated.js";
+const BASE_URL = (process.env.X402_BASE_URL || "https://x402.agentutility.ai").replace(/\/$/, "");
+const RPC_URL = process.env.X402_RPC_URL || "https://mainnet.base.org";
+const PK = process.env.X402_PRIVATE_KEY;
+if (!PK) {
+    console.error(`[@agentutility/mcp-${CLUSTER_SLUG}] FATAL: X402_PRIVATE_KEY env var is required.`);
+    console.error("Set it to a hex-encoded EVM private key with USDC balance on Base (chain 8453).");
+    console.error("USDC on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
+    process.exit(1);
+}
+const account = privateKeyToAccount((PK.startsWith("0x") ? PK : `0x${PK}`));
+const publicClient = createPublicClient({
+    chain: base,
+    transport: http(RPC_URL),
+});
+const signer = toClientEvmSigner(account, publicClient);
+const client = new x402Client().register("eip155:8453", new ExactEvmScheme(signer));
+const paidFetch = wrapFetchWithPayment(fetch, client);
+async function trackedFetch(url, init) {
+    const headers = new Headers(init?.headers);
+    headers.set("X-Agent-Channel", `mcp-stdio-${CLUSTER_SLUG}`);
+    headers.set("X-Agent-Id", "47167");
+    if (!headers.has("User-Agent")) {
+        headers.set("User-Agent", `agentutility-mcp/${CLUSTER_SLUG}/${VERSION}`);
+    }
+    return paidFetch(url, { ...init, headers });
+}
+const server = new Server({ name: `agentutility-${CLUSTER_SLUG}`, version: VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.input_schema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool) {
+        return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    }
+    try {
+        const res = await trackedFetch(`${BASE_URL}/${tool.http_name}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(req.params.arguments ?? {}),
+        });
+        const body = await res.text();
+        if (!res.ok) {
+            return { content: [{ type: "text", text: `HTTP ${res.status}: ${body}` }], isError: true };
+        }
+        return { content: [{ type: "text", text: body }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `tool call failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+await server.connect(new StdioServerTransport());

package/dist/tools.generated.js

@@ -0,0 +1,611 @@
+/** Auto-generated by scripts/generate-mcp-clusters.mjs. Do not edit by hand. */
+export const CLUSTER_SLUG = "rollforge";
+export const VERSION = "0.1.0";
+export const TOOLS = [
+    {
+        "name": "ability-check",
+        "http_name": "ability-check",
+        "description": "(0.001 USDC/call) D20 ability check / skill check / attack roll / saving throw resolver API for tabletop RPGs. Rolls a d20 with an optional modifier and advantage/disadvantage, compares to a DC, and reports total, success/failure, and natural-20 / natural-1. Seedable. Pure deterministic compute, no upstream API.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "dc": {
+                    "type": "number",
+                    "description": "Difficulty class to beat. Omit to just get the roll."
+                },
+                "modifier": {
+                    "type": "number",
+                    "description": "Total bonus/penalty added to the d20 (-20..40). Default 0."
+                },
+                "advantage": {
+                    "type": "boolean",
+                    "description": "Roll twice, take the higher."
+                },
+                "disadvantage": {
+                    "type": "boolean",
+                    "description": "Roll twice, take the lower."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed for a reproducible roll."
+                }
+            }
+        }
+    },
+    {
+        "name": "background-gen",
+        "http_name": "background-gen",
+        "description": "(0.001 USDC/call) Character background generator API / personality trait, ideal, bond, flaw generator for tabletop RPGs. Rolls the four roleplaying hooks for a character sheet — a personality trait, an ideal, a bond, and a flaw. Seedable. Pure compute, no upstream. Original generic-fantasy phrasing.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed."
+                }
+            }
+        }
+    },
+    {
+        "name": "character-gen",
+        "http_name": "character-gen",
+        "description": "(0.002 USDC/call) Tabletop character generator API / D&D 5e character builder / RPG character creator / random fantasy character. Generates a complete 5e-style character: ability scores (4d6-keep-highest-3, 3d6, or standard array) assigned by class priority, race / class / background / alignment, racial ability bonuses, derived hit points, ability modifiers, proficiency bonus, saving-throw proficiencies, and a procedurally generated name. Pin any field (race, class, level 1-20, method, name) or omit to randomize; pass 'seed' for a reproducible character. Pure deterministic compute, no upstream API. Uses only 5e SRD content (OGL 1.0a / CC-BY-4.0).",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "race": {
+                    "type": "string",
+                    "description": "SRD race: Human, Elf, Dwarf, Halfling, Dragonborn, Gnome, Half-Elf, Half-Orc, Tiefling. Omit to randomize."
+                },
+                "class": {
+                    "type": "string",
+                    "description": "SRD class: Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, Wizard. Omit to randomize."
+                },
+                "level": {
+                    "type": "number",
+                    "description": "Character level 1-20. Default 1."
+                },
+                "method": {
+                    "type": "string",
+                    "description": "Ability score method: 4d6kh3 (default), 3d6, or standard-array."
+                },
+                "name": {
+                    "type": "string",
+                    "description": "Optional fixed name; omit to generate one."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed for a reproducible character."
+                }
+            }
+        }
+    },
+    {
+        "name": "character-portrait",
+        "http_name": "character-portrait",
+        "description": "(0.08 USDC/call) Character portrait generator API / RPG character art / D&D character image / fantasy avatar generator. Builds a portrait from structured inputs — race, class, gender, a free-text description, and an art style (fantasy-art, realistic, anime, oil-painting, ink-sketch, watercolor, pixel-art, comic-book) — and renders it to a hosted PNG URL. Pairs with character-gen: generate the character, then its portrait. Text-to-image via Venice, output hosted on fal.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "race": {
+                    "type": "string",
+                    "description": "Character race, e.g. 'Elf', 'Half-Orc'."
+                },
+                "class": {
+                    "type": "string",
+                    "description": "Character class, e.g. 'Wizard', 'Rogue'."
+                },
+                "gender": {
+                    "type": "string",
+                    "description": "Optional gender/presentation descriptor."
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Free-text details: appearance, gear, mood, setting."
+                },
+                "style": {
+                    "type": "string",
+                    "description": "Art style: fantasy-art (default), realistic, anime, oil-painting, ink-sketch, watercolor, pixel-art, comic-book."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed for reproducibility."
+                }
+            }
+        }
+    },
+    {
+        "name": "class-lookup",
+        "http_name": "class-lookup",
+        "description": "(0.003 USDC/call) D&D 5e class lookup API / SRD class reference / class proficiencies and hit dice. Look up a class by name for hit dice, armor/weapon/tool/skill proficiencies, saving throws, spellcasting ability, and starting equipment, or list all SRD classes. SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Class name, e.g. 'Wizard'. Omit to list all classes."
+                }
+            }
+        }
+    },
+    {
+        "name": "condition-lookup",
+        "http_name": "condition-lookup",
+        "description": "(0.003 USDC/call) D&D 5e condition lookup API / SRD conditions reference (blinded, grappled, prone, stunned, etc.). Look up a condition by name for its full rules text, or list all SRD conditions. SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Condition name, e.g. 'Grappled'. Omit to list all conditions."
+                }
+            }
+        }
+    },
+    {
+        "name": "dice-roll",
+        "http_name": "dice-roll",
+        "description": "(0.001 USDC/call) Dice roller API / dice notation evaluator / RPG dice / tabletop random roll engine. Evaluates standard dice notation — XdY, flat modifiers (+/-), and keep-highest / keep-lowest (4d6kh3 for stat rolls, 2d20kh1 / 2d20kl1 for advantage/disadvantage). Returns each individual die, which were kept vs dropped, the per-roll total, and the grand total; roll the whole expression up to 100 times with 'rolls'. Pass 'seed' for reproducible output. Pure deterministic compute, no upstream API.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "notation": {
+                    "type": "string",
+                    "description": "Dice notation: 1d20, 3d6+2, 4d6kh3 (keep highest 3), 2d20kl1 (keep lowest 1)."
+                },
+                "rolls": {
+                    "type": "number",
+                    "description": "How many times to evaluate the whole expression. 1-100, default 1."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed for reproducible rolls."
+                }
+            },
+            "required": [
+                "notation"
+            ]
+        }
+    },
+    {
+        "name": "dice-stats",
+        "http_name": "dice-stats",
+        "description": "(0.002 USDC/call) Dice probability calculator API / anydice-style dice statistics / odds of a dice roll. For plain XdY+mod returns the EXACT distribution (mean, stdev, min, max, and P(>= target)); for keep-highest/lowest (4d6kh3, 2d20kl1) estimates via seeded Monte Carlo. For sizing DCs, damage, and stat rolls. Pure compute, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "notation": {
+                    "type": "string",
+                    "description": "Dice notation: 2d6+3, 1d20, 4d6kh3, 2d20kl1."
+                },
+                "target": {
+                    "type": "number",
+                    "description": "Optional target; returns probability of rolling at least this."
+                },
+                "trials": {
+                    "type": "number",
+                    "description": "Monte-Carlo trials for keep-variants (1000-200000, default 50000)."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed for the Monte-Carlo case."
+                }
+            },
+            "required": [
+                "notation"
+            ]
+        }
+    },
+    {
+        "name": "dungeon-room",
+        "http_name": "dungeon-room",
+        "description": "(0.001 USDC/call) Dungeon room generator API / random dungeon generator / D&D room description for GMs. Generates a room: shape, contents, a notable feature, a hazard, an occupant, and the number of exits. Pass 'rooms' for a small batch. Seedable. Pure compute, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "rooms": {
+                    "type": "number",
+                    "description": "How many rooms to generate, 1-20. Default 1."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed."
+                }
+            }
+        }
+    },
+    {
+        "name": "encounter-builder",
+        "http_name": "encounter-builder",
+        "description": "(0.002 USDC/call) Encounter builder / encounter difficulty calculator API for D&D 5e. Give the party (levels, or size + level) to get easy/medium/hard/deadly XP thresholds; optionally give monster CRs to get the multiplier-adjusted XP and the resulting difficulty rating. SRD DMG tables (OGL 1.0a / CC-BY-4.0). Pure compute, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "party_levels": {
+                    "type": "array",
+                    "description": "Array of character levels, e.g. [3,3,4,2]."
+                },
+                "party_size": {
+                    "type": "number",
+                    "description": "Number of characters (use with party_level if levels are uniform)."
+                },
+                "party_level": {
+                    "type": "number",
+                    "description": "Shared character level (use with party_size)."
+                },
+                "monster_crs": {
+                    "type": "array",
+                    "description": "Optional monster challenge ratings, e.g. [\"1\",\"1/2\",\"2\"], to rate the encounter."
+                }
+            }
+        }
+    },
+    {
+        "name": "equipment-lookup",
+        "http_name": "equipment-lookup",
+        "description": "(0.003 USDC/call) D&D 5e equipment lookup API / SRD weapons and armor / gear stats. Look up a weapon or piece of armor by name (weapon damage dice/type/properties/cost, or armor class/cost/weight/stealth), or list items by type ('weapon' or 'armor'). SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Item name, e.g. 'Longsword' or 'Breastplate'."
+                },
+                "type": {
+                    "type": "string",
+                    "description": "List a category: 'weapon' or 'armor'."
+                },
+                "limit": {
+                    "type": "number",
+                    "description": "Max results when listing, 1-60. Default 30."
+                }
+            }
+        }
+    },
+    {
+        "name": "initiative-roll",
+        "http_name": "initiative-roll",
+        "description": "(0.001 USDC/call) Initiative tracker / initiative order roller API for tabletop combat. Each combatant rolls 1d20 plus their initiative (DEX) modifier; returns the full turn order, ties broken by modifier then input order. Seedable. Pure deterministic compute, no upstream API.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "combatants": {
+                    "type": "array",
+                    "description": "Array of { name?, modifier? } — one per combatant (max 50)."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed for reproducible rolls."
+                }
+            },
+            "required": [
+                "combatants"
+            ]
+        }
+    },
+    {
+        "name": "loot-gen",
+        "http_name": "loot-gen",
+        "description": "(0.002 USDC/call) Loot generator / treasure generator API for D&D 5e. Rolls coins (and, for hoards, gems/art objects and a magic-item slot) scaled by a challenge-rating band. SRD-style treasure math (OGL 1.0a / CC-BY-4.0). Seedable. Pure compute, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "challenge_rating": {
+                    "type": "number",
+                    "description": "Encounter/monster CR (0-30) to scale the treasure. Default 1."
+                },
+                "hoard": {
+                    "type": "boolean",
+                    "description": "Generate a treasure hoard (coins + gems/art + magic items) instead of individual coins."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed for reproducible loot."
+                }
+            }
+        }
+    },
+    {
+        "name": "magic-item-lookup",
+        "http_name": "magic-item-lookup",
+        "description": "(0.003 USDC/call) D&D 5e magic item lookup API / SRD magic items / wondrous item reference. Look up a magic item by name for its type, rarity, attunement, and full description, or list items filtered by rarity and/or type. SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Magic item name, e.g. 'Bag of Holding'."
+                },
+                "rarity": {
+                    "type": "string",
+                    "description": "Filter list by rarity: common, uncommon, rare, very rare, legendary."
+                },
+                "type": {
+                    "type": "string",
+                    "description": "Filter list by type, e.g. 'Wondrous item', 'Weapon', 'Armor'."
+                },
+                "limit": {
+                    "type": "number",
+                    "description": "Max results when listing, 1-50. Default 20."
+                }
+            }
+        }
+    },
+    {
+        "name": "monster-lookup",
+        "http_name": "monster-lookup",
+        "description": "(0.003 USDC/call) D&D 5e monster lookup API / SRD monster stat block / bestiary search. Look up a monster by name for a compact stat block (size, type, alignment, AC, HP, hit dice, speed, ability scores, challenge rating, and actions), or list monsters filtered by challenge rating and/or type. SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Monster name for a full stat block, e.g. 'Goblin'."
+                },
+                "challenge_rating": {
+                    "type": "string",
+                    "description": "Filter list by CR: 0, 1/8, 1/4, 1/2, or an integer 1-30."
+                },
+                "type": {
+                    "type": "string",
+                    "description": "Filter list by creature type, e.g. Dragon, Undead, Beast."
+                },
+                "limit": {
+                    "type": "number",
+                    "description": "Max results when listing, 1-40. Default 20."
+                }
+            }
+        }
+    },
+    {
+        "name": "name-gen",
+        "http_name": "name-gen",
+        "description": "(0.001 USDC/call) Fantasy name generator API / RPG name generator / D&D character & NPC names / random fantasy names by race. Generates original syllable-built names, optionally flavored by race (Dwarf, Elf, Half-Orc, etc.). Batch up to 50 at once with 'count'; pass 'seed' for reproducible output. Pure deterministic compute, no upstream API.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "count": {
+                    "type": "number",
+                    "description": "How many names to generate, 1-50. Default 5."
+                },
+                "race": {
+                    "type": "string",
+                    "description": "Optional race flavor: Human, Elf, Dwarf, Halfling, Dragonborn, Gnome, Half-Elf, Half-Orc, Tiefling."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed for reproducible names."
+                }
+            }
+        }
+    },
+    {
+        "name": "npc-gen",
+        "http_name": "npc-gen",
+        "description": "(0.001 USDC/call) NPC generator API / random D&D NPC / tabletop character generator for GMs. Generates a quick non-player character: name, race, occupation, personality trait, distinctive appearance, mannerism, and a hidden secret/plot hook. Pin race or occupation, or omit to randomize. Seedable. Pure compute, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "race": {
+                    "type": "string",
+                    "description": "Optional race: Human, Elf, Dwarf, Halfling, Dragonborn, Gnome, Half-Elf, Half-Orc, Tiefling."
+                },
+                "occupation": {
+                    "type": "string",
+                    "description": "Optional occupation to pin (e.g. blacksmith). Omit to randomize."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed for a reproducible NPC."
+                }
+            }
+        }
+    },
+    {
+        "name": "quest-gen",
+        "http_name": "quest-gen",
+        "description": "(0.001 USDC/call) Quest generator API / random plot hook / D&D adventure seed generator. Generates a quest hook: giver, objective, location, complication, and reward, plus a one-line ready-to-read hook. Seedable. Pure compute, no upstream. Original generic-fantasy content.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed."
+                }
+            }
+        }
+    },
+    {
+        "name": "race-lookup",
+        "http_name": "race-lookup",
+        "description": "(0.003 USDC/call) D&D 5e race lookup API / SRD race reference / racial traits and ability score increases. Look up a race by name for ability score increases, speed, size, languages, vision, and racial traits, or list all SRD races. SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Race name, e.g. 'Elf'. Omit to list all races."
+                }
+            }
+        }
+    },
+    {
+        "name": "random-table",
+        "http_name": "random-table",
+        "description": "(0.001 USDC/call) Random table roller API / weighted random picker / loot & rumor table roller. Roll on a caller-provided table — weighted entries ([{value, weight?}]) or classic die-range rows ([{min,max,result}] with a 'die') — any number of times, with or without replacement. Seedable. A generic random-selection utility for any custom table. Pure compute, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "entries": {
+                    "type": "array",
+                    "description": "Weighted entries: [{ value, weight? }]. Use this OR table+die."
+                },
+                "table": {
+                    "type": "array",
+                    "description": "Die-range rows: [{ min, max, result }]. Requires 'die'."
+                },
+                "die": {
+                    "type": "number",
+                    "description": "Die sides for a range table (e.g. 100 for a d100 table)."
+                },
+                "rolls": {
+                    "type": "number",
+                    "description": "How many results to draw, 1-100. Default 1."
+                },
+                "unique": {
+                    "type": "boolean",
+                    "description": "Draw without replacement."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed."
+                }
+            }
+        }
+    },
+    {
+        "name": "settlement-gen",
+        "http_name": "settlement-gen",
+        "description": "(0.001 USDC/call) Settlement generator API / random town generator / D&D village & city generator. Generates a settlement: name, size category with a plausible population, government, primary trade, a notable feature, and a current problem the party could engage with. Pin 'size' (hamlet/village/town/city) or randomize. Seedable. Pure compute, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "size": {
+                    "type": "string",
+                    "description": "Optional: hamlet, village, town, or city. Omit to randomize."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed."
+                }
+            }
+        }
+    },
+    {
+        "name": "spell-lookup",
+        "http_name": "spell-lookup",
+        "description": "(0.003 USDC/call) D&D 5e spell lookup API / SRD spell search / spell card details. Look up a spell by name for full details (level, school, casting time, range, components, duration, concentration, ritual, classes, description, higher-level scaling), or list spells filtered by level and/or school. SRD content only (OGL 1.0a / CC-BY-4.0) via Open5e.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Spell name for full details, e.g. 'Fireball'."
+                },
+                "level": {
+                    "type": "number",
+                    "description": "Filter list by spell level 0-9 (0 = cantrip)."
+                },
+                "school": {
+                    "type": "string",
+                    "description": "Filter list by school, e.g. evocation, abjuration."
+                },
+                "limit": {
+                    "type": "number",
+                    "description": "Max results when listing, 1-50. Default 20."
+                }
+            }
+        }
+    },
+    {
+        "name": "spell-slots",
+        "http_name": "spell-slots",
+        "description": "(0.001 USDC/call) Spell slots by class and level API / D&D 5e spellcasting slot table / pact magic lookup. Returns the level 1-9 spell-slot array for any 5e class at a given level (full casters, half-casters like Paladin/Ranger, Warlock pact magic, and non-casters), plus proficiency bonus. SRD spellcasting tables (OGL 1.0a / CC-BY-4.0). Pure compute, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "class": {
+                    "type": "string",
+                    "description": "5e class: Bard, Cleric, Druid, Sorcerer, Wizard, Warlock, Paladin, Ranger, Barbarian, Fighter, Monk, Rogue."
+                },
+                "level": {
+                    "type": "number",
+                    "description": "Class level 1-20. Default 1."
+                }
+            },
+            "required": [
+                "class"
+            ]
+        }
+    },
+    {
+        "name": "tavern-gen",
+        "http_name": "tavern-gen",
+        "description": "(0.001 USDC/call) Tavern generator API / random fantasy inn / D&D tavern name & details. Generates a tavern: name, proprietor, the house drink and meal, a notable patron, and a rumor overheard inside. Seedable. Pure compute, no upstream. Original generic-fantasy content.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed."
+                }
+            }
+        }
+    },
+    {
+        "name": "weather-gen",
+        "http_name": "weather-gen",
+        "description": "(0.001 USDC/call) Fantasy weather generator API / random RPG weather / tabletop campaign weather forecast. Rolls a day's weather for a climate (temperate, arid, cold, tropical) with conditions and wind. Pass 'days' for a short forecast. Seedable. Pure compute, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "climate": {
+                    "type": "string",
+                    "description": "temperate (default), arid, cold, or tropical."
+                },
+                "days": {
+                    "type": "number",
+                    "description": "Days to forecast, 1-14. Default 1."
+                },
+                "seed": {
+                    "type": "number",
+                    "description": "Optional integer seed."
+                }
+            }
+        }
+    },
+    {
+        "name": "xp-level",
+        "http_name": "xp-level",
+        "description": "(0.001 USDC/call) XP to level calculator / D&D 5e experience table / level from XP lookup API. Give 'xp' to get the current level, XP to the next level, and progress; or give 'level' to get the XP needed to reach it. Returns proficiency bonus. SRD advancement table (OGL/CC). Pure compute, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "xp": {
+                    "type": "number",
+                    "description": "Total experience points; returns the level it maps to."
+                },
+                "level": {
+                    "type": "number",
+                    "description": "Level 1-20; returns the XP needed to reach it."
+                }
+            }
+        }
+    }
+];

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@agentutility/mcp-rollforge",
+  "version": "0.1.0",
+  "description": "MCP server for the @agentutility rollforge cluster — pay-per-call x402 tools, no API keys, USDC on Base.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "agentutility-mcp-rollforge": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rooz21/x402",
+    "directory": "packages/mcp-rollforge"
+  },
+  "homepage": "https://mcp.agentutility.ai/rollforge/",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "agentutility",
+    "agent-tools",
+    "rollforge"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@x402/fetch": "^2.12.0",
+    "@x402/evm": "^2.12.0",
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}