DD Inspector
vinod-th-17317/dd-inspector
Consulte schemas de banco sem gastar contexto com XML bruto
Ver no GitHubMCP 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-inspector1 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
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.
| Approach | Tokens (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:
| Variable | Default | Purpose |
|---|---|---|
DD_WORKSPACE | Parent folder of dd-inspector/ | Workspace root to scan |
DD_RESCAN_MIN | 15 | Full file-list rescan interval (minutes) |
Tools
| Tool | Arguments | Use |
|---|---|---|
find_table(pattern) | pattern: name substring | Locate 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 disambiguator | Full 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 filter | Which tables contain a matching column |
table_relations(table, direction="both") | direction: out, in, or both | FK 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:
- Identify the bug in
dd_index.py - Fix and save the file
- Wait ~1–2 seconds (watcher checks every second)
- 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.pychanges 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
| Scenario | Expected | Status |
|---|---|---|
| Partial match, lowercase | Returns all tables containing the substring | ✅ |
| Partial match, UPPERCASE | Same results (case-insensitive) | ✅ |
| Pattern with 25+ hits | Shows first 25 + (+N more, refine pattern) | ✅ |
| No match | no table matching '...' | ✅ |
describe_table
| Scenario | Expected | Status |
|---|---|---|
| Columns with correct types | BIGINT, CHAR(n), DECIMAL(n), BOOLEAN, SIGNEDTINYINT, INTEGER | ✅ |
| Not-null columns | NN flag shown | ✅ |
| Default values | =value shown | ✅ |
| Allowed values (enum) | {1,2,3,5} shown | ✅ |
| Auto-generated PK | gen flag shown | ✅ |
| PK columns | PK flag shown | ✅ |
| Single FK on column | FK->Table.Col shown | ✅ |
| Multiple FKs on same column | All targets shown: FK->Table1.Col,Table2.Col | ✅ Fixed |
| Composite FK | Both local columns shown in auto-idx | ✅ |
| Explicit indexes | idx: NAME(col1,col2); ... | ✅ |
| Auto-indexes (PK/FK-derived) | auto-idx (N): PRIMARY(pk); FKName(col); ... | ✅ |
| Unique keys | uk: NAME(col); ... | ✅ |
| FK constraints referencing columns not in column list | FK auto-idx shown correctly | ✅ |
| Table in multiple namespaces | Both entries returned | ✅ |
find_column
| Scenario | Expected | Status |
|---|---|---|
| Column pattern alone | All tables with that column + type | ✅ |
| Column pattern + table_pattern | Filtered to matching tables | ✅ |
| Column exists but not in filtered table | Helpful redirect message | ✅ |
| No match | no column matching '...' | ✅ |
table_relations
| Scenario | Expected | Status |
|---|---|---|
direction=out | All FK constraints with names and local→ref col mapping | ✅ |
direction=in | All tables referencing this table, with FK name | ✅ |
direction=both | Combined out + in sections | ✅ |
| Table not found | table '...' not found. Try find_table first. | ✅ |
dd_stats
| Scenario | Expected | Status |
|---|---|---|
| Healthy index | File count, table count, column count, per-repo breakdown | ✅ |
| Parse errors | Listed under parse errors (N): | ✅ |
Hot-reload
| Scenario | Expected | Status |
|---|---|---|
Edit dd_index.py, same session | Change 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:
-
Reproduce — call the tool, note the wrong output
-
Verify against XML — use Python directly to check ground truth:
python3 dd_index.py /path/to/workspace describe <TableName> -
Locate the bug — look at these methods in
dd_index.py:Wrong output Where to look Missing / wrong column _parse_column()Missing / wrong FK _parse_table()→ foreign-keys sectionMissing / wrong index _parse_table()→ indexes sectionWrong PK _parse_table()→ primary-key sectionWrong FK display in describe _describe_one()→fk_localdictWrong relation in table_relations_rebuild()→refs_indictTable not found _rebuild()dedup logic /_fallback_namespace()Stale data refresh()mtime logic -
Fix and save
dd_index.py— hot-reload picks it up in ~1–2s -
Retry the same tool call in the same thread — no restart needed
-
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/andsubprojects/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..15onInvoiceItemTable) are still shown inauto-idx— they represent real DB constraints defined at the schema level.