Search crystal structures (formula, mineral, compound) and fetch CIF atomic data from the Crystallography Open Database via @pipeworx/mcp-crystallography

@pipeworx/mcp-crystallography v0.1.0 — Crystallography Open Database (COD) MCP

Package: @pipeworx/mcp-crystallography (npm) Architecture: Library-style export {tools, callTool} — NOT a stdio server. TypeScript source only (src/index.ts, no dist). Requires node --experimental-strip-types --no-warnings. Copy source outside node_modules first (ESM guard). API: Crystallography Open Database (https://crystallography.net/cod) — ~500K+ crystal structures, free, no auth. Tools: 3

Tool inventory

Critical gotchas

1. ⚠️ Formula format: elements MUST be alphabetically sorted, space-separated — O2 Si not Si O2 or SiO2. This is COD convention. Wrong order returns 0 results silently.
2. ⚠️ Mineral field is SPARSELY populated — searching mineral: 'quartz' and mineral: 'Calcite' both return 0 results. Use query (text search) instead: query: 'calcite' works.
3. At least one of query/formula/mineral required — empty search returns error 'provide query, formula, or mineral'.
4. Formula search is MUCH faster than text search — formula: ~200-1300ms vs text query: ~2000-4000ms (COD does full-text index scan).
5. `get_cif` strips non-numeric chars from cod_id — safe to pass with/without formatting.
6. CIF files are small (typically 2-5KB) — capped at 40KB with truncated: true flag.
7. limit defaults to 20, max 100 — large text queries (e.g. 'oxide' with limit:100) take ~15s.

Verified execution trace (22 calls, 100% success)

search_structures — text query:

// Search for quartz-related structures
callTool('search_structures', { query: 'quartz', limit: 3 })
→ { count: 3, structures: [{ cod_id: '1009000', formula: '- As Ga O4 -', space_group: 'P 31 2 1', cell: { a: '4.994', b: '4.994', c: '11.3871', alpha: '90', beta: '90', gamma: '120' }, year: '1999', cif_url: 'https://www.crystallography.net/cod/1009000.cif' }, ...] } // 4171ms

// Search for silicon dioxide
callTool('search_structures', { query: 'silicon dioxide', limit: 3 })
→ { count: 3 } // structures[0]: { formula: '- O2 Si -', mineral: 'Cristobalite high' } // 2448ms

// Search for perovskite structures
callTool('search_structures', { query: 'perovskite', limit: 5 })
→ { count: 5 } // structures[0]: { formula: '- Ca O3 Ti -' } (actual perovskite CaTiO3) // 3856ms

// Search for diamond structures
callTool('search_structures', { query: 'diamond', limit: 3 })
→ { count: 3 } // first result Fd-3m structure // 2919ms

// Unicode in query
callTool('search_structures', { query: 'α-quartz', limit: 3 })
→ { count: 2 } // Unicode α handled correctly // 2204ms

search_structures — formula (alphabetical order!):

// SiO2 — CORRECT format: O2 Si (alphabetical)
callTool('search_structures', { formula: 'O2 Si', limit: 3 })
→ { count: 3 } // structures[0]: { formula: '- O2 Si -', space_group: ... } // 1318ms

// SiO2 — WRONG format: SiO2 (no spaces)
callTool('search_structures', { formula: 'SiO2', limit: 3 })
→ { count: 0 } // SILENT FAILURE — 0 results // 427ms

// NaCl — WRONG format
callTool('search_structures', { formula: 'Na Cl', limit: 3 })
→ { count: 0 } // Wrong order — should be 'Cl Na' // 183ms

// CaTiO3 — CORRECT: Ca O3 Ti
callTool('search_structures', { formula: 'Ca O3 Ti', limit: 3 })
→ { count: 3 } // structures[0]: { space_group: 'P b n m' } (orthorhombic perovskite) // 961ms

// Carbon
callTool('search_structures', { formula: 'C', limit: 5 })
→ { count: 5 } // 5 polymorphs: R-3m:H (graphite), P63mc (wurtzite), Fd-3m:1 (diamond) // 1235ms

// Fe2O3 (hematite)
callTool('search_structures', { formula: 'Fe2 O3', limit: 3 })
→ { count: 3 } // stru