@iamjameslennon/ddb-mcp 2.7.0 → 2.8.0

package/README.md

@@ -222,25 +222,37 @@ Can a character use the Help action to assist with a skill check?
 
 ## Installation
 
-### Option A — Install from npm (recommended)
+> 🆕 **New to all this?** If you're on a Mac starting from scratch (no Homebrew, no Node, no Claude Desktop), follow the [step-by-step beginner tutorial](INSTALL-MACOS.md) instead — it covers everything below plus how to install the prerequisites.
 
-```bash
-npm install -g @iamjameslennon/ddb-mcp
+Add this to your MCP client's config — no separate install step needed.
+
+```json
+{
+  "mcpServers": {
+    "dndbeyond": {
+      "command": "npx",
+      "args": ["-y", "@iamjameslennon/ddb-mcp"]
+    }
+  }
+}
 ```
 
-Playwright Chromium is installed automatically as part of the global install.
+On first launch, `npx` fetches the package itself (small — under 200 kB unpacked of JS). Playwright Chromium (~140 MB) is downloaded **on demand the first time you run `ddb_login`**, with progress printed to the server log; subsequent logins reuse the cached browser. This keeps server startup fast and the heavy download happens at a moment you expect to wait.
 
----
+Configure the path to your client's config file in the [Connecting to your MCP client](#connecting-to-your-mcp-client) section below.
 
-### Option B — Clone and build manually
+To pin a version (recommended for production setups), change the args to `["-y", "@iamjameslennon/ddb-mcp@2.7.0"]`.
+
+### Alternative: install globally
+
+If you'd rather have a persistent binary on `PATH` (offline use, air-gapped networks, faster startup):
 
 ```bash
-git clone https://github.com/iamjameslennon/ddb-mcp.git
-cd ddb-mcp
-npm ci
-npx playwright install chromium
+npm install -g @iamjameslennon/ddb-mcp
 ```
 
+Then use `"command": "ddb-mcp"` (no args) in your client config. Chromium is still fetched on first `ddb_login` rather than during install.
+
 ---
 
 ## Security & Privacy
@@ -258,7 +270,7 @@ npx playwright install chromium
   - Screenshots (opt-in): `~/Downloads` only
 - **Transport**: stdio only — the server opens no HTTP listeners and no ports.
 - **Untrusted content**: tools that return D&D Beyond page text (`ddb_navigate`, `ddb_get_page`) wrap the scraped output in `<untrusted_dndbeyond_content>` tags. Character notes, campaign descriptions, party-member backstories, and book content can be authored by other DDB users (DMs, party members, forum posters) and may contain prompt-injection attempts — treat them as untrusted input, never as instructions. The `confirm_click` / `confirm_fill` gates on `ddb_interact` exist for exactly this reason.
-- **Recommendation**: pin the version when installing — `npm install -g @iamjameslennon/ddb-mcp@2.6.1`.
+- **Recommendation**: pin the version in your MCP client config — `"@iamjameslennon/ddb-mcp@2.7.0"` — rather than letting `npx` auto-update on every launch.
 
 ---
 
@@ -266,85 +278,44 @@ npx playwright install chromium
 
 This server was built and tested with Claude — it will work with any MCP-compatible client, but response quality for D&D-specific reasoning will vary depending on the model used.
 
-First, find your global npm path:
-
-```bash
-npm root -g
-# macOS/Linux example: /usr/local/lib/node_modules
-# Windows example:     C:\Users\<you>\AppData\Roaming\npm\node_modules
-```
-
-> In all config examples below, replace `/usr/local/lib/node_modules` with the output of `npm root -g` on your system.
-
-> **Windows note**: JSON treats `\` as an escape character. Either use forward slashes (Node accepts them on Windows) — `"C:/Users/<you>/AppData/Roaming/npm/node_modules/@iamjameslennon/ddb-mcp/dist/index.js"` — or double every backslash: `"C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\@iamjameslennon\\ddb-mcp\\dist\\index.js"`. Forward slashes are simpler and harder to get wrong.
+All clients below use the same JSON config from the [Installation](#installation) section. Drop it into your client's config file (paths below), then restart the client.
 
 ### Claude Desktop (recommended)
 
-Edit your Claude Desktop config file:
-
 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json` (community builds only — Claude Desktop has no official Linux release; use [Claude Code](#claude-code) or [Cursor](#cursor) instead)
 
-Linux note: Claude Desktop has no official Linux release. If you don't run a community build, use [Claude Code](#claude-code), [Cursor](#cursor), or any other MCP client below.
+### Claude Code
 
-```json
-{
-  "mcpServers": {
-    "dndbeyond": {
-      "command": "node",
-      "args": ["/usr/local/lib/node_modules/@iamjameslennon/ddb-mcp/dist/index.js"]
-    }
-  }
-}
+One-liner — no manual JSON editing:
+
+```bash
+claude mcp add dndbeyond -- npx -y @iamjameslennon/ddb-mcp
 ```
 
-### Claude Code
+Or if you installed globally:
 
 ```bash
-claude mcp add dndbeyond node $(npm root -g)/@iamjameslennon/ddb-mcp/dist/index.js
+claude mcp add dndbeyond ddb-mcp
 ```
 
 ### Cursor
 
-Edit `~/.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "dndbeyond": {
-      "command": "node",
-      "args": ["/usr/local/lib/node_modules/@iamjameslennon/ddb-mcp/dist/index.js"]
-    }
-  }
-}
-```
+`~/.cursor/mcp.json`
 
 ### Windsurf
 
-Edit `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "dndbeyond": {
-      "command": "node",
-      "args": ["/usr/local/lib/node_modules/@iamjameslennon/ddb-mcp/dist/index.js"]
-    }
-  }
-}
-```
+`~/.codeium/windsurf/mcp_config.json`
 
 ### LM Studio
 
-MCP support was added in LM Studio 0.3.x. Configure through the UI under **Settings → MCP Servers** using the same JSON shape as Claude Desktop above. Steps may vary between versions — see [lmstudio.ai/docs](https://lmstudio.ai/docs) for current instructions.
+MCP support was added in LM Studio 0.3.x. Configure through the UI under **Settings → MCP Servers** using the same JSON shape as above. Steps may vary between versions — see [lmstudio.ai/docs](https://lmstudio.ai/docs) for current instructions.
 
 ### Open WebUI
 
 MCP servers are configured through the admin panel under **Settings → Tools**. See [docs.openwebui.com](https://docs.openwebui.com) for current instructions — the UI changes frequently between releases.
 
-> LM Studio and Open WebUI use the same underlying `node` command and path as the other clients above.
-
 ---
 
 ## First-time login
@@ -547,15 +518,17 @@ Remove-Item "$env:APPDATA\ddb-mcp\session.json"
 Your session has expired. Run `ddb_login` to re-authenticate.
 
 **Chromium not found / browser won't launch**
+Chromium is installed lazily on first `ddb_login`. If the download failed (network or sandbox issue), run `ddb_login` again — the server retries on each call. If it keeps failing, fetch the browser manually:
 ```bash
 npx playwright install chromium
 ```
+The same global Playwright cache is shared by every install path (npx, global, local clone) — one successful install is reused everywhere.
 
 **Character returns 403 or "private"**
 The character is set to private on D&D Beyond. You must be logged in as the owner, or the owner must make it public.
 
 **MCP server not appearing in Claude Code**
-Run `/mcp` in Claude Code to reconnect. If it still doesn't appear, verify the path in `claude mcp list` points to the correct `dist/index.js`.
+Run `/mcp` in Claude Code to reconnect. If it still doesn't appear, run `claude mcp list` to confirm the `dndbeyond` entry exists.
 
 **Server crashes on startup**
 Make sure you're running Node.js 20 or later: `node --version`.
@@ -565,10 +538,12 @@ Make sure you're running Node.js 20 or later: `node --version`.
 ## Development
 
 ```bash
-# Install dependencies (always use npm ci — not npm install)
+# Install dependencies — prefer npm ci to respect the lockfile
 npm ci
 
-# Run in development mode (no build step needed)
+# Run in development mode (no build step needed). Chromium is fetched lazily
+# on first `ddb_login`; if you want to pre-warm the cache:
+#   npx playwright install chromium
 npm run dev
 
 # Build
@@ -577,7 +552,7 @@ npm run build
 # Watch mode
 npm run build:watch
 
-# Run tests
+# Run tests (browser-free — they mock the Playwright surface)
 npm test
 ```
 

package/dist/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAKrE,OAAO,EAA0B,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvF,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;AAMrC,wBAAsB,UAAU,CAAC,QAAQ,UAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAclE;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAmB1E;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCxE;AAED,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpE;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAUlD"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAQrE,OAAO,EAA0B,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvF,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;AA0DrC,wBAAsB,UAAU,CAAC,QAAQ,UAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAkBlE;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAmB1E;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCxE;AAED,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpE;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAUlD"}

package/dist/browser.js

@@ -1,10 +1,65 @@
 import { chromium } from "playwright";
 import { existsSync, mkdirSync, openSync, closeSync, writeFileSync, fchmodSync, renameSync, constants, } from "fs";
+import { spawn } from "child_process";
+import { createRequire } from "module";
+import { dirname, join } from "path";
 import { invalidateSessionCache, SESSION_DIR, SESSION_PATH } from "./session-fetch.js";
 export { SESSION_DIR, SESSION_PATH };
 let browserInstance = null;
 let browserHeadless = null;
 let contextInstance = null;
+// Singleton Promise so concurrent getBrowser() callers share one install run.
+// Cleared on failure so subsequent calls can retry.
+let chromiumInstallPromise = null;
+async function ensureChromiumInstalled() {
+    if (chromiumInstallPromise)
+        return chromiumInstallPromise;
+    // chromium.executablePath() returns the *expected* path; if the binary is
+    // not there, we need to fetch it. Wrapped in try because some Playwright
+    // versions throw on this call when no browsers are registered yet.
+    let executablePath = "";
+    try {
+        executablePath = chromium.executablePath();
+    }
+    catch { /* fall through to install */ }
+    if (executablePath && existsSync(executablePath))
+        return;
+    chromiumInstallPromise = (async () => {
+        process.stderr.write("[ddb-mcp] Chromium not found — downloading (~140 MB, one-time)…\n");
+        // Resolve Playwright's CLI relative to *this* module (not CWD), so the
+        // install works whether the server was launched via npx, a global install,
+        // or a local clone. Note: Playwright's `exports` map doesn't expose
+        // `cli.js`, so we resolve `package.json` (which IS exported) and walk
+        // sideways. process.execPath ensures we use the same Node binary.
+        const require = createRequire(import.meta.url);
+        const cliPath = join(dirname(require.resolve("playwright/package.json")), "cli.js");
+        await new Promise((resolve, reject) => {
+            // stdout → parent stderr: critical because the MCP server uses stdout
+            // for JSON-RPC frames; leaking install progress into stdout would break
+            // the client connection.
+            const child = spawn(process.execPath, [cliPath, "install", "chromium"], {
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            child.stdout?.pipe(process.stderr);
+            child.stderr?.pipe(process.stderr);
+            child.on("error", reject);
+            child.on("exit", code => {
+                if (code === 0) {
+                    process.stderr.write("[ddb-mcp] Chromium installed.\n");
+                    resolve();
+                }
+                else {
+                    reject(new Error(`Chromium install failed (exit ${code}). ` +
+                        `Network or sandbox issue? Run \`npx playwright install chromium\` manually to retry.`));
+                }
+            });
+        });
+    })();
+    // Allow retry on failure — clear the cached promise so the next caller
+    // doesn't immediately re-fail against the same rejected Promise.
+    chromiumInstallPromise.catch(() => { chromiumInstallPromise = null; });
+    return chromiumInstallPromise;
+}
 export async function getBrowser(headless = true) {
     // If a browser is already running with a different headless setting, close it
     // first so ddb_login always gets a visible window even if headless tools ran before.
@@ -13,6 +68,10 @@ export async function getBrowser(headless = true) {
     }
     if (browserInstance)
         return browserInstance;
+    // Lazy Chromium provisioning: fetched on first use (during ddb_login) so
+    // package install stays fast and the ~140 MB download happens at a moment
+    // the user expects work to happen and we can surface progress.
+    await ensureChromiumInstalled();
     const args = ["--disable-blink-features=AutomationControlled"];
     // Sandbox should stay enabled. Only disable it in constrained container
     // environments (e.g. CI/Docker) where the kernel doesn't support it.

package/dist/browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
+#!/usr/bin/env node
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,18 +1,20 @@
+#!/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 { getBrowser, getContext, closeBrowser } from "./browser.js";
 import { login } from "./auth.js";
-import { getCharacter, downloadCharacter, listCharacters, parseCharacter, findCharacterByName, getDefinition } from "./tools/character.js";
-import { getCampaign, listMyCampaigns } from "./tools/campaign.js";
+import { getCharacter, downloadCharacter, listCharacters, parseCharacter, findCharacterByName, getDefinition, clearCharacterCache } from "./tools/character.js";
+import { getCampaign, listMyCampaigns, invalidateCampaignCache } from "./tools/campaign.js";
 import { getParty } from "./tools/party.js";
 import { navigate, interact, getCurrentPageContent } from "./tools/navigate.js";
 import { search } from "./tools/search.js";
 import { listLibrary, readBook } from "./tools/library.js";
-import { searchMonsters, getMonster } from "./tools/monster.js";
+import { searchMonsters, getMonster, clearMonsterCache } from "./tools/monster.js";
 import { rateEncounter, targetEncounterCr } from "./tools/encounter.js";
 import { generateTreasure } from "./tools/treasure.js";
-import { getCondition, searchSpells, getSpell, searchItems, getItem, searchRaces, searchClasses, searchBackgrounds, searchFeats, searchClassFeatures, searchRacialTraits, searchRules, getRule } from "./tools/reference.js";
+import { getCondition, searchSpells, getSpell, searchItems, getItem, searchRaces, searchClasses, searchBackgrounds, searchFeats, searchClassFeatures, searchRacialTraits, searchRules, getRule, clearReferenceCache } from "./tools/reference.js";
+import { clearOpen5eCache } from "./open5e.js";
 const server = new McpServer({
     name: "dndbeyond",
     version: "1.0.0",
@@ -59,8 +61,35 @@ server.tool("ddb_close_browser", "Close the background browser window if one is
         return { content: [{ type: "text", text: `Failed to close browser: ${msg}` }], isError: true };
     }
 });
+// ─── ddb_clear_cache ─────────────────────────────────────────────────────────
+server.tool("ddb_clear_cache", "Wipe in-process caches so the next call re-fetches from D&D Beyond. Use this when search results look like the SRD/Open5e fallback (e.g. 2024 cantrips missing from spell results) after you've logged in — the partial compendium build is cached for up to 5 minutes and this forces an immediate retry. cache='spells' (default) clears just the spell/reference compendium; 'all' wipes every cache.", {
+    cache: z
+        .enum(["spells", "characters", "monsters", "all"])
+        .default("spells")
+        .describe("Which cache to clear. 'spells' (default) — the spell / equipment / races / classes / feats compendium. 'characters' — character JSON cache. 'monsters' — monster stat-block cache. 'all' — everything, including campaigns and Open5e responses."),
+}, async ({ cache }) => {
+    const cleared = [];
+    if (cache === "spells" || cache === "all") {
+        clearReferenceCache();
+        cleared.push("spells/reference compendium");
+    }
+    if (cache === "characters" || cache === "all") {
+        clearCharacterCache();
+        cleared.push("character JSON");
+    }
+    if (cache === "monsters" || cache === "all") {
+        clearMonsterCache();
+        cleared.push("monsters");
+    }
+    if (cache === "all") {
+        invalidateCampaignCache();
+        clearOpen5eCache();
+        cleared.push("campaigns", "Open5e responses");
+    }
+    return { content: [{ type: "text", text: `Cleared: ${cleared.join(", ")}. The next relevant tool call will re-fetch from D&D Beyond.` }] };
+});
 // ─── ddb_list_characters ──────────────────────────────────────────────────────
-server.tool("ddb_list_characters", "List all characters in your D&D Beyond account, including their ID, level, race, and class.", {}, async () => {
+server.tool("ddb_list_characters", "List all characters in your D&D Beyond account, including their ID, level, race, and class. Requires login — run ddb_login first if you haven't already.", {}, async () => {
     try {
         const result = await listCharacters();
         return { content: [{ type: "text", text: result }] };
@@ -72,7 +101,7 @@ server.tool("ddb_list_characters", "List all characters in your D&D Beyond accou
     }
 });
 // ─── ddb_get_character_raw ────────────────────────────────────────────────────
-server.tool("ddb_get_character_raw", "Returns raw 300–500 KB character JSON. Requires confirm_large_response: true. Use ddb_get_character instead for all normal use.", {
+server.tool("ddb_get_character_raw", "Returns raw 300–500 KB character JSON. Requires confirm_large_response: true. Use ddb_get_character instead for all normal use. Requires login — run ddb_login first if you haven't already.", {
     character_id: z.string().min(1).optional().describe("The D&D Beyond character ID (e.g. '12345678')"),
     character_name: z.string().min(1).optional().describe("Character name to look up (fuzzy matched against your account)"),
     confirm_large_response: z.literal(true).describe("Must be true to proceed — acknowledges this call returns 300–500 KB."),
@@ -99,7 +128,7 @@ server.tool("ddb_get_character_raw", "Returns raw 300–500 KB character JSON. R
     }
 });
 // ─── ddb_download_character ───────────────────────────────────────────────────
-server.tool("ddb_download_character", "Download a character's full JSON data to a local file.", {
+server.tool("ddb_download_character", "Download a character's full JSON data to a local file. Requires login — run ddb_login first if you haven't already.", {
     character_id: z.string().min(1).describe("The D&D Beyond character ID"),
     output_path: z
         .string()
@@ -118,7 +147,7 @@ server.tool("ddb_download_character", "Download a character's full JSON data to
     }
 });
 // ─── ddb_get_character ───────────────────────────────────────────────────────
-server.tool("ddb_get_character", "Parse and display a character sheet. Use sections to reduce output: summary (vitals+stats), combat (adds actions/weapons), spells (spellcasting only), inventory, features, concentration, notes (backstory, traits, bonds), or full (default).", {
+server.tool("ddb_get_character", "Parse and display a character sheet. Use sections to reduce output: summary (vitals+stats), combat (adds actions/weapons), spells (spellcasting only), inventory, features, concentration, notes (backstory, traits, bonds), or full (default). Requires login — run ddb_login first if you haven't already.", {
     character_id: z.string().min(1).optional().describe("The D&D Beyond character ID (e.g. '12345678')"),
     character_name: z.string().min(1).optional().describe("Character name to look up (fuzzy matched — e.g. 'Throin' finds 'Thorin Ironforge')"),
     sections: z.enum(["summary", "combat", "spells", "inventory", "features", "concentration", "notes", "full"])
@@ -147,7 +176,7 @@ server.tool("ddb_get_character", "Parse and display a character sheet. Use secti
     }
 });
 // ─── ddb_character_lookup ────────────────────────────────────────────────────
-server.tool("ddb_character_lookup", "Look up the full description of a spell, feat, class feature, subclass feature, racial trait, background feature, or equipped item by name. Supports partial and fuzzy name matching (e.g. 'cutting' finds Cutting Words, 'sheild' finds Shield). Accepts either a numeric character_id or a character_name.", {
+server.tool("ddb_character_lookup", "Look up the full description of a spell, feat, class feature, subclass feature, racial trait, background feature, or equipped item by name. Supports partial and fuzzy name matching (e.g. 'cutting' finds Cutting Words, 'sheild' finds Shield). Accepts either a numeric character_id or a character_name. Requires login — run ddb_login first if you haven't already.", {
     character_id: z.string().min(1).optional().describe("The D&D Beyond character ID"),
     character_name: z.string().min(1).optional().describe("Character name (fuzzy matched against your account)"),
     name: z.string().min(1).describe("Name to search for — partial match, e.g. 'hunter' finds Hunter's Mark"),
@@ -205,7 +234,7 @@ server.tool("ddb_get_monster", "Get the full stat block for a specific monster f
     }
 });
 // ─── ddb_get_campaign ─────────────────────────────────────────────────────────
-server.tool("ddb_get_campaign", "Fetch campaign information including player characters from a D&D Beyond campaign.", {
+server.tool("ddb_get_campaign", "Fetch campaign information including player characters from a D&D Beyond campaign. Requires login — run ddb_login first if you haven't already.", {
     campaign_id: z.string().min(1).describe("The D&D Beyond campaign ID (found in the campaign URL)"),
 }, async ({ campaign_id }) => {
     try {
@@ -219,7 +248,7 @@ server.tool("ddb_get_campaign", "Fetch campaign information including player cha
     }
 });
 // ─── ddb_list_campaigns ───────────────────────────────────────────────────────
-server.tool("ddb_list_campaigns", "List all D&D Beyond campaigns you are part of (as DM or player).", {}, async () => {
+server.tool("ddb_list_campaigns", "List all D&D Beyond campaigns you are part of (as DM or player). Requires login — run ddb_login first if you haven't already.", {}, async () => {
     try {
         const data = await listMyCampaigns();
         return { content: [{ type: "text", text: data }] };
@@ -231,7 +260,7 @@ server.tool("ddb_list_campaigns", "List all D&D Beyond campaigns you are part of
     }
 });
 // ─── ddb_get_party ────────────────────────────────────────────────────────────
-server.tool("ddb_get_party", "Fetch a compact summary of every character in a campaign. Returns HP, AC, initiative, passive scores, ability scores, and skills for the whole party in one call.", {
+server.tool("ddb_get_party", "Fetch a compact summary of every character in a campaign. Returns HP, AC, initiative, passive scores, ability scores, and skills for the whole party in one call. Requires login — run ddb_login first if you haven't already.", {
     campaign_id: z.string().min(1).describe("The D&D Beyond campaign ID (found in the campaign URL)"),
 }, async ({ campaign_id }) => {
     try {
@@ -339,7 +368,7 @@ server.tool("ddb_search_site", "Search D&D Beyond for spells, monsters, magic it
     }
 });
 // ─── ddb_list_library ─────────────────────────────────────────────────────────
-server.tool("ddb_list_library", "List all books and sourcebooks you own in your D&D Beyond library.", {}, async () => {
+server.tool("ddb_list_library", "List all books and sourcebooks you own in your D&D Beyond library. Requires login — run ddb_login first if you haven't already.", {}, async () => {
     try {
         const context = await getSharedContext();
         const books = await listLibrary(context);
@@ -354,7 +383,7 @@ server.tool("ddb_list_library", "List all books and sourcebooks you own in your
     }
 });
 // ─── ddb_read_book ────────────────────────────────────────────────────────────
-server.tool("ddb_read_book", "Read a D&D Beyond book. Accepts either a slug (e.g. dnd/phb-2024) or a plain title (e.g. \"Player's Handbook\" or \"monster manual\") — the server resolves titles against your library automatically. Specify chapter_slug for a chapter, query to jump to a heading, and max_chars to control response size.", {
+server.tool("ddb_read_book", "Read a D&D Beyond book. Accepts either a slug (e.g. dnd/phb-2024) or a plain title (e.g. \"Player's Handbook\" or \"monster manual\") — the server resolves titles against your library automatically. Specify chapter_slug for a chapter, query to jump to a heading, and max_chars to control response size. Requires login — run ddb_login first if you haven't already.", {
     book_slug: z
         .string()
         .min(1)
@@ -451,7 +480,7 @@ server.tool("ddb_get_equipment", "Get the full stats and description of any item
         return { content: [{ type: "text", text: `Item lookup failed: ${msg}` }], isError: true };
     }
 });
-server.tool("ddb_search_races", "Search all D&D Beyond races and subraces (including homebrew). Not character-specific.", {
+server.tool("ddb_search_races", "Search all D&D Beyond races and subraces (including homebrew). Not character-specific. Requires login — run ddb_login first if you haven't already.", {
     name: z.string().optional().describe("Partial race name (e.g. 'elf', 'tiefling')"),
     limit: z.number().int().min(1).max(100).default(30).describe("Max results (default 30)"),
     offset: z.number().int().min(0).default(0).describe("Skip N results for pagination"),
@@ -466,7 +495,7 @@ server.tool("ddb_search_races", "Search all D&D Beyond races and subraces (inclu
         return { content: [{ type: "text", text: `Race search failed: ${msg}` }], isError: true };
     }
 });
-server.tool("ddb_search_classes", "Search all D&D Beyond classes with hit die, spellcasting, and subclasses.", {
+server.tool("ddb_search_classes", "Search all D&D Beyond classes with hit die, spellcasting, and subclasses. Requires login — run ddb_login first if you haven't already.", {
     name: z.string().optional().describe("Partial class name (e.g. 'fighter', 'wizard')"),
     limit: z.number().int().min(1).max(100).default(30).describe("Max results (default 30)"),
     offset: z.number().int().min(0).default(0).describe("Skip N results for pagination"),
@@ -481,7 +510,7 @@ server.tool("ddb_search_classes", "Search all D&D Beyond classes with hit die, s
         return { content: [{ type: "text", text: `Class search failed: ${msg}` }], isError: true };
     }
 });
-server.tool("ddb_search_backgrounds", "Search all D&D Beyond backgrounds (including homebrew).", {
+server.tool("ddb_search_backgrounds", "Search all D&D Beyond backgrounds (including homebrew). Requires login — run ddb_login first if you haven't already.", {
     name: z.string().optional().describe("Partial background name (e.g. 'sage', 'criminal')"),
     limit: z.number().int().min(1).max(100).default(30).describe("Max results (default 30)"),
     offset: z.number().int().min(0).default(0).describe("Skip N results for pagination"),
@@ -496,7 +525,7 @@ server.tool("ddb_search_backgrounds", "Search all D&D Beyond backgrounds (includ
         return { content: [{ type: "text", text: `Background search failed: ${msg}` }], isError: true };
     }
 });
-server.tool("ddb_search_feats", "Search feats by name or prerequisite text.", {
+server.tool("ddb_search_feats", "Search feats by name or prerequisite text. Requires login — run ddb_login first if you haven't already.", {
     name: z.string().optional().describe("Partial feat name (e.g. 'sharpshooter', 'magic')"),
     prerequisite: z.string().optional().describe("Filter by prerequisite text (e.g. 'spellcaster', 'level 4')"),
     limit: z.number().int().min(1).max(100).default(30).describe("Max results (default 30)"),
@@ -512,7 +541,7 @@ server.tool("ddb_search_feats", "Search feats by name or prerequisite text.", {
         return { content: [{ type: "text", text: `Feat search failed: ${msg}` }], isError: true };
     }
 });
-server.tool("ddb_search_class_features", "Search class features by name, class, or level gained.", {
+server.tool("ddb_search_class_features", "Search class features by name, class, or level gained. Requires login — run ddb_login first if you haven't already.", {
     name: z.string().optional().describe("Partial feature name (e.g. 'action surge', 'sneak attack')"),
     class_name: z.string().optional().describe("Class name filter (e.g. 'fighter', 'rogue')"),
     level: z.number().int().min(1).max(20).optional().describe("Level at which the feature is gained"),
@@ -529,7 +558,7 @@ server.tool("ddb_search_class_features", "Search class features by name, class,
         return { content: [{ type: "text", text: `Class feature search failed: ${msg}` }], isError: true };
     }
 });
-server.tool("ddb_search_racial_traits", "Search racial traits by name or race.", {
+server.tool("ddb_search_racial_traits", "Search racial traits by name or race. Requires login — run ddb_login first if you haven't already.", {
     name: z.string().optional().describe("Partial trait name (e.g. 'darkvision', 'breath weapon')"),
     race_name: z.string().optional().describe("Race name filter (e.g. 'elf', 'dragonborn')"),
     limit: z.number().int().min(1).max(100).default(30).describe("Max results (default 30)"),