TDC MCP Server

An MCP server that exposes True Dungeon Companion game data — tokens, set/group bonuses, and rulebook pages — as tools for Claude and other MCP clients.

Tools

| Tool | Description | |------|-------------| | search_tokens | Search tokens by name, slot, rarity, or class | | advanced_search_tokens | Build arbitrary AND/OR filter trees across 29 fields (abilities, stats, damage, etc.) | | get_token | Get full detail for a single token (effects, slots, damage wheel, etc.) | | list_set_bonuses | List all set bonuses with tier effects | | get_set_bonus | Get a single set bonus by id | | list_group_bonuses | List all group bonuses with tier effects | | get_group_bonus | Get a single group bonus by id | | list_rulebook_pages | List all rulebook pages (title + path) | | get_rulebook_page | Get the full text content of a rulebook page | | get_api_version | Get the running TDC API build version and start time |

Quick start (npx)

No install or build needed. Add to your .claude/settings.json:

{
  "mcpServers": {
    "tdc": {
      "command": "npx",
      "args": ["@tdcompanion/mcp-server"],
      "env": {
        "TDC_API_KEY": "tdc_live_<your-key>"
      }
    }
  }
}

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | TDC_API_BASE_URL | https://api.tdcompanion.app | API base URL (must point at the API host, not the web app) | | TDC_API_KEY | (none) | Optional bearer key for higher rate limits (600 req/min vs 60) |

The server works without an API key (anonymous access), but authenticated keys get 10x the rate limit. Generate one from your profile's Developer tab at https://tdcompanion.app/profile.

Development

cd src/MCP/@tdcompanion/mcp-server
npm install
npm run build     # compile TypeScript → dist/
npm start         # run locally via stdio

Publishing

npm run build
npm publish

The prepublishOnly script runs the build automatically. The files field in package.json ensures only dist/ is included in the published package.

Changelog

1.1.0

• Added get_set_bonus, get_group_bonus, and get_api_version tools.
• Stricter input validation: pagination is clamped (skip >= 0, take 1–200), and slot / rarity / class reject unknown values up front.
• advanced_search_tokens validates the filter JSON is a FilterExpression object before sending.
• All tools return a clean { isError: true } result on failure instead of throwing.
• Rulebook HTML stripping now handles numeric entities (&#x…;, &#…;) and preserves list structure.
• List-style tools truncate output over ~20k chars with a clear "…N more truncated" footer.