Mary's Lab

A computational color science laboratory. She knows everything about color. She has never seen it.

maryslab-nu.vercel.app

Named for Frank Jackson's thought experiment: Mary, the scientist who knows every physical fact about color but has only ever seen black and white. This lab works the way Mary does. Color arrives as spectra, matrices, and proofs, and the instruments built here do things the field's tooling has not done before.

What lives here

32 MCP tools any AI agent can call, over two engines that must agree: a TypeScript reference engine and a C++20 core behind a stable C ABI, held together by 401 shared golden vectors and a metamorphic relation suite that runs against both.

The interesting tools are the ones without precedent as software. Every existing color tool is forward and point-wise: spectrum in, number out. These work the other three directions:

Plus a correctness suite (crosscheck_color_implementations, generate_conformance_vectors) that metamorphically tests any color library against algebraic identities. It found a real bug in this repo's own engine on its first run.

Related MCP server: scicompute-mcp

Quick start

git clone https://github.com/JeetuSK0808/maryslab
cd maryslab && npm install
cd mcp && npm test && npm run build
claude mcp add maryslab -- node "$(pwd)/dist/server.js"

Then ask your agent to certify a palette, design a spectrum, or audit a colormap. Full tool reference: docs/mcp-tools.md.

Architecture

flowchart LR
    A[AI agents\nClaude Code, any MCP client] -->|MCP stdio| B[mcp/\nTypeScript server\n32 tools, zod schemas]
    B --> C[TS reference engine\nmcp/src/engine]
    B -.->|when built| D[core/\nC++20 engine\nstable C ABI]
    C <-->|401 golden vectors\n+ metamorphic relations| D
    E[data/\ningestion, quality gates] --> B
    F[web/\nAstro site] --> C

The two engines are not allowed to drift: core/tests/golden/conformance.csv is generated from the TypeScript engine and checked by the C++ test suite, and the same metamorphic relations (round trips, metric axioms, white-point preservation, spectral linearity) run against both. 171 TS tests, 79 native tests, all green.

The honesty rules

This lab's differentiator is that caveats travel with results.

• CVD compensation remaps for discriminability. It never claims to restore what dichromacy removed.

• Isotope matches and forensic scores are decision support, never authoritative identification. The forensics tool states in its own output that it was calibrated on synthetic negatives.

• Infeasible constraints fail loudly with the achieved bound, never silently relaxed.

• Certificates report when their own grid is too coarse to certify anything (grid_sufficient: false) instead of printing a hollow zero.

• Papers are in preparation. Nothing here cites a preprint that does not exist. See docs/PRD.md §5 for the ideas we cut because the math did not hold.

Repository map

Contributing

The highest-value contribution is a dataset source adapter with a verified license (see docs/dataset.md). Ground rules in CONTRIBUTING.md: conventional commits, coverage stays at 80 percent, golden vectors change only through a golden-update PR, and scientific claims cite their sources.

License

Code: Apache-2.0. Dataset records carry per-source licenses, tracked in data/catalogs/sources.yaml.