dbc-query

MCP (Model Context Protocol) server for querying World of Warcraft DBC (Database Client) files directly.

Overview

This tool allows AI assistants to query WoW DBC files without requiring SQL import. It reads WDBC format files directly and provides a query interface through the MCP protocol.

Why use this instead of SQL?

• ✅ No manual DBC→SQL conversion needed
• ✅ Automatically works with DBC file updates
• ✅ Accesses all 246 DBC files, not just imported ones
• ✅ Lightweight - no database overhead
• ✅ Portable across AzerothCore installations

Features

• Direct WDBC file parsing (WoW 3.3.5 / WotLK format)
• Automatic format detection from AzerothCore DBCfmt.h
• Field name mappings extracted from DBCStructure.h (85 DBCs, 982 fields)
• Multiple query modes: by ID, row index, or field filters
• Column selection for optimized results
• DBC caching for performance
• 246 DBC files supported out of the box

Requirements

• Python 3.7+
• AzerothCore DBC files (typically in env/dist/bin/dbc/)
• AzerothCore source code (for DBCfmt.h format definitions)
• Claude Code (for MCP integration)

Installation

1. Clone this repository:

   git clone https://github.com/YOUR_USERNAME/dbc-query.git ~/dbc-query
   cd ~/dbc-query

2. Verify Python version:

   python3 --version  # Should be 3.7 or higher

3. Generate field mappings (optional - already included):

   # Field mappings are pre-generated, but you can regenerate them:
   python3 struct_parser.py
   # This creates field_mappings.json from DBCStructure.h

4. Test the standalone tools:

   # Test format parser
   python3 format_parser.py
   
   # Test DBC reader
   python3 dbc_reader.py SkillLineAbility 0
   
   # Test MCP server
   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | python3 server.py

5. Configure Claude Code MCP server:

   Add to your ~/.claude.json in the mcpServers section:

   {
     "mcpServers": {
       "dbc_query": {
         "type": "stdio",
         "command": "python3",
         "args": ["/root/dbc-query/server.py"],
         "env": {
           "DBC_PATH": "/root/azerothcore-wotlk/env/dist/bin/dbc",
           "DBC_FORMAT_FILE": "/root/azerothcore-wotlk/src/server/shared/DataStores/DBCfmt.h"
         }
       }
     }
   }

   Important: Update the paths to match your installation:

   • DBC_PATH: Location of your .dbc files
   • DBC_FORMAT_FILE: Path to DBCfmt.h in your AzerothCore source

6. Restart Claude Code to load the MCP server

Usage

Standalone Command-Line Usage

Query by DBC name and row index:

python3 dbc_reader.py Spell 0
python3 dbc_reader.py SkillLineAbility 1550

List available formats:

python3 format_parser.py

Test integration:

./test_integration.sh

MCP Tool Usage (from Claude Code)

After configuration, Claude will have access to these tools:

1. Query DBC Files (query_dbc)

Get record by ID:

# Find spell 2567
mcp__dbc_query__query_dbc(dbc_name="Spell", id=2567)

Get record by row index:

mcp__dbc_query__query_dbc(dbc_name="SkillLineAbility", row_index=0)

Filter by field values:

# Find all SkillLineAbility entries for spell 2567
# Field 2 = spell ID
mcp__dbc_query__query_dbc(
    dbc_name="SkillLineAbility",
    filter={"2": 2567}
)

Select specific columns:

# Only return fields 0, 1, 2, 3, 4
mcp__dbc_query__query_dbc(
    dbc_name="SkillLineAbility",
    filter={"2": 2567},
    columns=[0, 1, 2, 3, 4]
)

Get DBC file info:

mcp__dbc_query__query_dbc(dbc_name="Spell", info=true)

2. List Available DBCs (list_dbcs)

List all DBCs:

mcp__dbc_query__list_dbcs()

Search for specific DBCs:

mcp__dbc_query__list_dbcs(search="Spell")
mcp__dbc_query__list_dbcs(search="Talent")

3. Describe DBC Fields (describe_fields)

Get field names and types for a DBC:

# Get all field information for Spell.dbc
mcp__dbc_query__describe_fields(dbc_name="Spell")

# Returns:
# {
#   "dbc": "Spell",
#   "field_count": 234,
#   "mapped_fields": 184,    # Fields with known names
#   "unmapped_fields": 50,   # Fields named "FieldN"
#   "fields": [
#     {"index": 0, "name": "Id", "type": "uint32", "format_char": "n", "has_mapping": true},
#     {"index": 136, "name": "SpellName[0]", "type": "string_array", "format_char": "s", "has_mapping": true},
#     {"index": 153, "name": "Rank[0]", "type": "string_array", "format_char": "s", "has_mapping": true},
#     ...
#   ]
# }

Example usage - Find spell name field:

# Describe fields to find the name field
fields = mcp__dbc_query__describe_fields(dbc_name="Spell")

# Look for "Name" in field names
name_fields = [f for f in fields["result"]["fields"] if "Name" in f["name"]]
# Returns: SpellName[0] at index 136

# Now query just the fields you need
spell = mcp__dbc_query__query_dbc(
    dbc_name="Spell",
    id=133,
    columns=[0, 136, 153]  # ID, Name, Rank
)

Benefits:

• 🔍 Discover field meanings without consulting external documentation
• 📊 See field types (uint32, float, string, etc.)
• ✅ Know which fields are mapped vs unnamed
• 🎯 Optimize queries by selecting only needed columns

Field name coverage:

• Spell.dbc: 184/234 fields (78.6%)
• SkillLineAbility.dbc: 10/14 fields (71.4%)
• Item.dbc: Varies by DBC
• Total: 85 DBCs with field mappings

Unmapped fields: Fields without mappings are shown as FieldN (e.g., Field42). These are typically unused fields or fields without comments in the AzerothCore source code.

Architecture

Core Modules

• server.py - MCP server implementation

  • JSON-RPC 2.0 protocol handler
  • Tool registration and execution
  • DBC caching for performance

• dbc_reader.py - WDBC binary file parser

  • Header parsing (signature, record count, etc.)
  • Binary data section parsing
  • String table resolution
  • Query interface (filter, columns, ID/row lookup)

• format_parser.py - DBCfmt.h format string parser

  • Extracts format strings from C++ header
  • DBC name mapping (e.g., Spell → SpellEntry)
  • Field count and record size calculation

• struct_parser.py - DBCStructure.h field name extractor

  • Parses C++ struct definitions to extract field names and types
  • Handles array fields spanning multiple indices (e.g., SpellName[0-15])
  • Generates field_mappings.json with 85 DBCs, 982 fields
  • Run manually: python3 struct_parser.py to regenerate mappings

Field Name Extraction

Field names are extracted from DBCStructure.h by parsing C++ struct comments:

// From DBCStructure.h:
struct SpellEntry {
    uint32 Id;                                    // 0
    uint32 Category;                              // 1
    std::array<char const*, 16> SpellName;        // 136-151
    std::array<char const*, 16> Rank;             // 153-168
    ...
};

The struct_parser.py tool extracts these definitions and creates a JSON mapping:

{
  "Spell": {
    "0": {"name": "Id", "type": "uint32"},
    "136": {"name": "SpellName[0]", "type": "string_array"},
    "153": {"name": "Rank[0]", "type": "string_array"}
  }
}

This mapping is loaded at runtime and used by the describe_fields tool.

WDBC File Format

Header (20 bytes):
  - Signature: 'WDBC' (4 bytes)
  - RecordCount: uint32 (4 bytes)
  - FieldCount: uint32 (4 bytes)
  - RecordSize: uint32 (4 bytes)
  - StringBlockSize: uint32 (4 bytes)

Data Section: RecordCount × RecordSize bytes
String Table: StringBlockSize bytes (null-terminated strings)

Format String Characters

• i, n, d, l = uint32 (4 bytes)
• f = float (4 bytes)
• s = string offset into string table (4 bytes)
• b = uint8 (1 byte)
• x = skip/unused (4 bytes)
• X = skip/unused (1 byte)

Examples

Example 1: Investigating Spell 2567 Bug

# Get spell info
result = mcp__dbc_query__query_dbc(dbc_name="Spell", id=2567, columns=[0, 136])
# Returns: {0: 2567, 136: "Thrown"}

# Check class restrictions in SkillLineAbility
result = mcp__dbc_query__query_dbc(
    dbc_name="SkillLineAbility",
    filter={"2": 2567},
    columns=[0, 1, 2, 3, 4]
)
# Returns: {0: 1550, 1: 176, 2: 2567, 3: 0, 4: 0}
# ClassMask=0 confirms the bug!

Example 2: Finding All Talents for a Class

# List talent-related DBCs
mcp__dbc_query__list_dbcs(search="Talent")

# Query talents (field 8 = class ID, 0 = all classes)
mcp__dbc_query__query_dbc(
    dbc_name="Talent",
    filter={"8": 1},  # Warrior class
    limit=50
)

Example 3: Exploring Zone Data

# Get zone name and info
mcp__dbc_query__query_dbc(dbc_name="AreaTable", id=1519)
# Returns zone data including name strings

Troubleshooting

MCP server not appearing in Claude Code:

• Ensure paths in ~/.claude.json are correct
• Restart Claude Code after configuration changes
• Check DBC_PATH points to directory containing .dbc files
• Verify DBC_FORMAT_FILE points to DBCfmt.h

"No format found for DBC" error:

• Check DBC name spelling (case-sensitive)
• Try adding "Entry" suffix (e.g., "SpellEntry" instead of "Spell")
• Run python3 format_parser.py to see available formats

"File not found" error:

• Verify DBC file exists in DBC_PATH
• Check file permissions (should be readable)
• Ensure DBC_PATH in environment is correct

Format string mismatch:

• DBC file may be from different WoW version
• Check DBCfmt.h is from matching AzerothCore version
• Verify DBC wasn't corrupted during extraction

Performance

• First query: ~100-500ms (loads and caches DBC)
• Subsequent queries: ~1-10ms (from cache)
• Memory usage: ~10-50MB per cached DBC
• Supported DBC count: 246 files

Tested DBCs

Successfully tested with:

• Spell.dbc: 49,839 records, 234 fields
• SkillLineAbility.dbc: 10,219 records, 14 fields
• AreaTable.dbc: 2,307 records, 36 fields
• Item.dbc: 46,096 records, 8 fields
• Talent.dbc: 892 records, 23 fields
• Achievement.dbc: 1,817 records, 62 fields

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

License

This project is licensed under the GNU AGPL v3 License - see the LICENSE file for details.

Acknowledgments

• AzerothCore team for DBC format documentation
• Model Context Protocol specification
• WDBXEditor for DBC format insights