2d6-mcp-core

name: 2d6-mcp-core description: Master reference for the 2d6mcp MCP server — all tools, workflows, and environment configuration for 2d6 TTRPGs (sci-fi and fantasy).

2D6 MCP Server — Agent Instructions

You have access to the 2d6mcp MCP server. It provides a mechanical engine, dice roller, and rules reference for 2d6-based tabletop RPGs, supporting sci-fi (OGL/Cepheus Engine), fantasy (Dungeon World), percentile (Basic Roleplaying), and d20 fantasy (5E-compatible) games.

Deployment Modes

2d6mcp has two deployment modes:

1. Self-Hosted MCP Server (packages/server/) — traditional MCP stdio server, local MLX, BYOD, session DB, 32 tools
2. Hosted Discord Bot (apps/worker/) — Cloudflare Worker with Discord slash commands and Workers AI (Whisper + Qwen3 MoE)

Both modes share rules databases, dice engine, prompt templates, and quality filters via packages/shared/.

Tool loyalty: Once you invoke 2d6mcp tools (particularly BYOD — query_local_byod, get_byod_chunk, synthesize_ruling), continue using them for all game content queries. Do not switch to external file-reading MCP tools unless the user explicitly asks you to examine a file outside the indexed BYOD content.

Available Tools

Discord Bot Commands (Hosted, apps/worker/)

Key Principles

• System-agnostic language: Use generic descriptors — "2d6 sci-fi RPG", "2d6 fantasy RPG", "starship", "star system", "characteristic", "move", "front", "monster". Never use third-party trademarked terms.
• Task resolution by system:
  • 2d6 systems (OGL, DW): 2d6 + modifier vs. target number (typically 8+). Effect margin = total - target. Use roll_2d6.
  • d20 systems (5E, Orcus): d20 + modifier vs. AC/DC. Natural 20 = critical hit, natural 1 = fumble. Supports advantage/disadvantage. Use roll_d20.
  • d100 systems (BRP, CoC): Roll under target percentile. ≤5% of target = critical success, 96-100 = fumble. Use roll_percentile.
  • Damage: Use roll_damage("2d6+3 fire") for damage with type labels.
• d66 tables: Roll two d6s and treat them as tens (first die) and ones (second die), producing 11-66. Use roll_table with "dice_type": "d66".
• The OGL database is pre-populated with Cepheus Engine SRD content. It covers rules, skills, careers, equipment, combat, starship operations, and world building. Always try query_ogl_rules before falling back to BYOD search.
• The DW database is pre-populated with Dungeon World content (CC-BY-3.0, by Sage LaTorra and Adam Koebel). It covers moves, classes, spells, equipment, monsters, and GM tools (agendas, principles, fronts, dangers). Use query_dw_rules for fantasy RPG content.
• The BRP database is pre-populated with Basic Roleplaying SRD. It covers characteristics, skills, professions, weapons, armor, spot rules, and sample foes. Use query_brp_rules for percentile RPG content.
• The 5E-compatible database covers d20 fantasy (spells, monsters, classes, feats). Use query_5ecompatible_rules.
• The Orcus database is pre-populated with Orcus 4e-compatible SRD. It covers classes, monsters, feats, and core rules. Use query_orcus_rules for 4e-compatible content.
• BYOD search is for your personal files. It requires consent (AGREE_BYOD_USE="true") and a configured BYOD_PATH. Files must be synced before they are searchable. Each BYOD_PATH gets its own isolated database. A shared content cache deduplicates identical files across workspaces.

When to Use Each Tool

Dice Rolling

• Use roll_2d6 for standard 2d6 task resolution (skill checks, attack rolls, characteristic checks)
• Use roll_d20 for d20-based fantasy RPG resolution (5E, 4E, Orcus, OSE) — supports advantage/disadvantage, AC comparison, critical hits/fumbles
• Use roll_percentile for BRP/percentile RPG resolution (Call of Cthulhu, Basic Roleplaying, Against the Darkmaster, Pendragon) — supports roll-under with critical success/fumble
• Use roll_damage for damage dice with optional type labels ("2d6+3 fire", "1d8 piercing", "4d6")
• Use roll_custom for non-standard dice (damage dice, 1d6 tables, character creation 2d6 across six characteristics)
• Use roll_table for random tables — this looks up the result in the OGL database

Rules Lookup

• Use query_ogl_rules as primary sci-fi rules reference. Specify a category for targeted results (skills, careers, equipment, combat, starships, worlds, tables, categories, list_tables)
• Use query_dw_rules for fantasy/Dungeon World content. Specify a category for targeted results (moves, classes, spells, equipment, monsters, gm_tools, rules)
• Use query_brp_rules for percentile RPG content. Specify a category for targeted results (characteristics, skills, professions, weapons, armor, spot_rules, foes)
• Use query_5ecompatible_rules for d20 fantasy content. Specify a category for targeted results (spells, monsters, classes, feats, rules)
• Use query_orcus_rules for 4e-compatible content. Specify a category for targeted results (classes, monsters, feats, rules)
• Use query_local_byod when you need content from your personal files (supplements, house rules, campaign notes)
• Use roll_table with a table name to both roll on it AND see the full table entries. Use the system parameter to specify the rules database (ogl/dw/brp/5ecompatible/orcus).

Character Handling

• Use parse_character to read a character sheet file and extract UPP, characteristics, skills, name, and career

BYOD Management

• Use sync_byod after adding or modifying files in your BYOD directory
• Use list_byod_files to see what's indexed and available for search
• Use inspect_byod_file to see how a file was chunked (page breaks, heading structure)
• Use clear_byod to reset the index completely
• Use sync_file to index a single file by relative path (for large files that timeout in bulk sync, or selective indexing)
• Use get_byod_chunk to retrieve full chunk content after query_local_byod returns snippets — pass file path and chunk index

Session Management

• Use session_start to begin a new game session — logs transcripts, rulings, and context for continuity
• Use log_transcript to record what was said at the table during play (with speaker, source, and intent)
• Use get_session_context to recall the last N minutes of game context (transcripts + rulings)
• Use search_transcript to search what was said about a specific topic across the full session
• Use session_list to browse all recorded sessions
• Use session_end to close the active session
• Use session_summarize to generate an AI summary of the full session transcript (requires MLX LLM)

Ruling Synthesis

• Use synthesize_ruling to ask a rules question and get an AI-generated ruling with OGL/DW/BRP/5E-compatible/BYOD citations (requires mlx_lm.generate)
• Use resolve_from_context to run the full producer pipeline: take recent transcript, detect rules question, look up rules, synthesize ruling, and log it to the session
• Use transcribe_audio to convert recorded audio to text using local MLX Whisper (requires mlx_whisper)

Discord Posting

• Use discord_post to send messages to Discord webhooks — supports smart routing based on context tags and rich embeds
• Use discord_add_webhook to configure a new webhook with name, URL, and routing tags
• Use discord_remove_webhook to remove a stored webhook
• Use discord_list_webhooks to view all configured webhooks
• Use discord_test_webhook to verify connectivity to a specific webhook

Common Workflows

Resolving a Task

1. Determine the appropriate characteristic or skill modifier
2. Apply any difficulty modifiers (easy +2, routine +1, difficult -2, etc.)
3. Call roll_2d6 with the modifier and target_number
4. Report the total, individual dice, and effect margin
5. Interpret: margin 0–5 = marginal success, 6+ = exceptional success; margin -1 to -5 = marginal failure, -6 or worse = exceptional failure

Looking Up Rules

1. Call query_ogl_rules with a descriptive search_term for sci-fi content
2. Call query_dw_rules with a descriptive search_term for fantasy content
3. If the result is empty or insufficient, try a different search term or add a category
4. For combat mechanics, use category: "combat". For starships, use category: "starships". For world building, use category: "worlds"
5. For DW monsters, use category: "monsters". For GM tools, use category: "gm_tools"
6. For specific tables, use category: "tables" or roll_table directly

Reference Round — Turn 0

When starting a session, ensure knowledge is available:

1. Call list_byod_files to know what personal content is indexed
2. Call sync_byod if you added files recently
3. Pre-load relevant rules with query_ogl_rules for the session's expected activities

Environment Variables

Self-Hosted MCP Server (packages/server/)

Hosted Cloudflare Worker (apps/worker/)

Security: Never commit secrets. Worker secrets must be set via wrangler secret put.