convez.ai
MCP ServerDados & AnalyticsIntermediário
vinod-th-17317

DD Inspector

vinod-th-17317/dd-inspector

Consulte schemas de banco sem gastar contexto com XML bruto

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP Server que indexa arquivos de dicionário de dados (data-dictionary*.xml) em toda a workspace e responde perguntas sobre schemas com plaintext compacto e eficiente em tokens. Elimina a necessidade de copiar XML bruto em prompts, reduzindo consumo de contexto em até 96%.

Instalação

$npx convez-ai vinod-th-17317/dd-inspector

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Validar estrutura de tabelas antes de escrever migrações
  • Encontrar colunas e relacionamentos FK em grandes bases de dados
  • Responder perguntas sobre dependências entre tabelas com eficiência de tokens

Veredito

Ferramenta prática para equipes que gerenciam muitos dicionários de dados XML. A economia de tokens (96% por query) é real em projetos grandes, mas depende de ter data-dictionaries bem organizados na workspace. Implementação funcional, sem overhead.

README

A tradução para o português deste README ainda está na fila.

dd-inspector

MCP server that indexes every data-dictionary*.xml across the workspace repos and answers schema questions with compact, token-cheap plaintext. No more pasting table XML into prompts.

Current coverage: 336 files · ~1,540 tables · ~28k columns. Startup scan ~8s, after that lookups are instant (in-memory index, mtime-based refresh).


Why this saves tokens

Without the MCP, answering "what columns does InvoiceTable have?" means either:

  • Pasting the raw XML block (~8k tokens for InvoiceTable alone), or
  • Grepping manually and narrating findings (slow, error-prone)

With the MCP, the same question costs ~300 tokens — just the compact output.

ApproachTokens (InvoiceTable)
Paste raw XML~8,000
describe_table("InvoiceTable")~300
Savings per lookup~96%

At scale (a feature touching 5–10 tables), this is the difference between burning half a context window on schema and having room for actual code.

The MCP also prevents mistakes: instead of Claude guessing column names or FK targets from memory, it reads the authoritative source — the same XML the DB migrations are generated from.


Setup for team members

zohobooks_server ships a .mcp.json that registers dd-inspector automatically. You only need to do this once per machine.

Step 1 — Clone dd-inspector as a sibling of zohobooks_server:

workspace/
  zohobooks_server/   ← you already have this
  dd-inspector/       ← clone here
cd <your-workspace>
git clone <dd-inspector-repo-url> dd-inspector

Step 2 — Install the one dependency:

pip install fastmcp

Step 3 — Open zohobooks_server in Claude Code. On first open, Claude Code will prompt you to approve the MCP servers from .mcp.json. Approve dd-inspector — that's it. CLI now has all 6 tools available.

Step 4 (optional) — Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dd-inspector": {
      "command": "python3",
      "args": ["/absolute/path/to/your/workspace/dd-inspector/server.py"]
    }
  }
}

Restart Desktop once.

Why absolute path for Desktop? The Desktop app doesn't set CWD to the project root, so relative paths don't work there. Use your machine's actual path.

Environment variables:

VariableDefaultPurpose
DD_WORKSPACEParent folder of dd-inspector/Workspace root to scan
DD_RESCAN_MIN15Full file-list rescan interval (minutes)

Tools

ToolArgumentsUse
find_table(pattern)pattern: name substringLocate tables by name (case-insensitive). Returns name, namespace, repo, column count. Use this first when unsure of the exact table name.
describe_table(table, namespace="")table: exact name; namespace: optional disambiguatorFull schema: columns with type / NN / default / allowed-values / PK / FK targets, explicit indexes, auto-indexes (PK/FK-derived), unique keys
find_column(pattern, table_pattern="")pattern: column name substring; table_pattern: optional table filterWhich tables contain a matching column
table_relations(table, direction="both")direction: out, in, or bothFK graph: out = tables this table references; in = tables that reference this table
dd_stats()—Index health: file/table/column counts per repo, last scan time, parse errors
rescan()—Force a full rescan (use when new .xml files were added)

Output legend: NN = not-null · =x = default value · gen = auto-generated PK · {...} = allowed values · FK->Table.Col = foreign key target · idx: = explicit DB index · auto-idx: = PK/FK-derived index (named after the FK constraint)


Hot-reload (fix MCP bugs without restarting the session)

The server watches dd_index.py for file changes using a background thread. When you save a fix to dd_index.py, the module is reloaded in-process — the MCP stdio connection stays alive and the same conversation thread picks up the new code immediately.

Workflow when you hit a wrong result:

  1. Identify the bug in dd_index.py
  2. Fix and save the file
  3. Wait ~1–2 seconds (watcher checks every second)
  4. Ask Claude to retry the same tool call in the same thread

No /exit, no session restart needed. Only server.py changes require a session restart.

Note for Claude Desktop: Restart the Desktop app once after changing server.py. dd_index.py changes are hot-reloaded there too once the session is live.


Known test cases (verified against XML ground truth)

These cases were validated by comparing MCP tool output against the actual data-dictionary*.xml source files.

find_table

ScenarioExpectedStatus
Partial match, lowercaseReturns all tables containing the substring✅
Partial match, UPPERCASESame results (case-insensitive)✅
Pattern with 25+ hitsShows first 25 + (+N more, refine pattern)✅
No matchno table matching '...'✅

describe_table

ScenarioExpectedStatus
Columns with correct typesBIGINT, CHAR(n), DECIMAL(n), BOOLEAN, SIGNEDTINYINT, INTEGER✅
Not-null columnsNN flag shown✅
Default values=value shown✅
Allowed values (enum){1,2,3,5} shown✅
Auto-generated PKgen flag shown✅
PK columnsPK flag shown✅
Single FK on columnFK->Table.Col shown✅
Multiple FKs on same columnAll targets shown: FK->Table1.Col,Table2.Col✅ Fixed
Composite FKBoth local columns shown in auto-idx✅
Explicit indexesidx: NAME(col1,col2); ...✅
Auto-indexes (PK/FK-derived)auto-idx (N): PRIMARY(pk); FKName(col); ...✅
Unique keysuk: NAME(col); ...✅
FK constraints referencing columns not in column listFK auto-idx shown correctly✅
Table in multiple namespacesBoth entries returned✅

find_column

ScenarioExpectedStatus
Column pattern aloneAll tables with that column + type✅
Column pattern + table_patternFiltered to matching tables✅
Column exists but not in filtered tableHelpful redirect message✅
No matchno column matching '...'✅

table_relations

ScenarioExpectedStatus
direction=outAll FK constraints with names and local→ref col mapping✅
direction=inAll tables referencing this table, with FK name✅
direction=bothCombined out + in sections✅
Table not foundtable '...' not found. Try find_table first.✅

dd_stats

ScenarioExpectedStatus
Healthy indexFile count, table count, column count, per-repo breakdown✅
Parse errorsListed under parse errors (N):✅

Hot-reload

ScenarioExpectedStatus
Edit dd_index.py, same sessionChange reflected in next tool call within ~2s✅

Updating the MCP when results are wrong

When a tool returns unexpected data, the problem is almost always in dd_index.py (the parser and query logic). server.py is just the thin MCP wrapper.

Typical fix cycle:

  1. Reproduce — call the tool, note the wrong output

  2. Verify against XML — use Python directly to check ground truth:

    python3 dd_index.py /path/to/workspace describe <TableName>
    
  3. Locate the bug — look at these methods in dd_index.py:

    Wrong outputWhere to look
    Missing / wrong column_parse_column()
    Missing / wrong FK_parse_table() → foreign-keys section
    Missing / wrong index_parse_table() → indexes section
    Wrong PK_parse_table() → primary-key section
    Wrong FK display in describe_describe_one() → fk_local dict
    Wrong relation in table_relations_rebuild() → refs_in dict
    Table not found_rebuild() dedup logic / _fallback_namespace()
    Stale datarefresh() mtime logic
  4. Fix and save dd_index.py — hot-reload picks it up in ~1–2s

  5. Retry the same tool call in the same thread — no restart needed

  6. Add the scenario to the test table above once fixed


Architecture

server.py          — FastMCP wrapper; registers tools; hosts the hot-reload watcher thread
dd_index.py        — all logic: XML parser, in-memory index, query methods
data-dictionary*.xml — source of truth (never read directly in prompts)

dd_index.py is stdlib-only and can be exercised without MCP:

python3 dd_index.py <workspace_root> find Invoice
python3 dd_index.py <workspace_root> describe InvoiceTable
python3 dd_index.py <workspace_root> column CustomerID
python3 dd_index.py <workspace_root> relations InvoiceTable
python3 dd_index.py <workspace_root> stats

Notes

  • Fragment files (bare <table> roots), DOCTYPE internal subsets, and &FOO_DATA_DICTIONARY; include-entities are all handled transparently.
  • Identical tables under both subrepo/ and subprojects/ are deduplicated by content signature; genuinely divergent copies are kept and both shown.
  • FK constraints that reference columns not present in the table's <columns> section (e.g. ClassOptionID1..15 on InvoiceItemTable) are still shown in auto-idx — they represent real DB constraints defined at the schema level.
Ver o original no GitHub

Bom para

Relacionados