<div align="center">

<img src="docs/assets/logo.svg" width="110" alt="Mary's Lab: an outlined eye whose iris is the only color" />

Mary's Lab

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

maryslab-nu.vercel.app

</div>

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:

Instrument	What it does that nothing else does
certify_illuminant_robustness	Guaranteed lower bound on palette discriminability over an entire convex family of illuminants, not a spot check
design_spectral_palette	Designs reflectance spectra (not colors) whose separation survives observers and illuminants jointly
design_discrimination_test	Computes optimal color-vision test stimuli; plates have been built by trial and error for a century
synthesize_adversarial_illuminant	Finds the physically realizable light that breaks a palette; the attack to the certificate's defense
audit_colormap_topology	Persistent-homology certificate of the features a colormap invents or destroys, per observer, CVD included
sample_metamers + map_metamer_stratification	Walks the convex metamer set and maps where its combinatorial structure changes across color space
audit_spectrum_provenance	Measurement forensics: is this spectrum measured, or interpolated and passed off as measured?
generate_metamer_benchmark	Physically realizable confusion pairs: identical under one light, split under another

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.

<div align="center"> <img src="docs/assets/metamer-atlas.svg" width="30%" alt="Many metameric reflectance curves collapsing to a single color swatch" /> <img src="docs/assets/design-discrimination-test.svg" width="30%" alt="Ishihara-style dot field generated from engine-computed confusable pair" /> <img src="docs/assets/audit-colormap-topology.svg" width="30%" alt="Lightness profiles and colormap strips for viridis and jet" /> <br/> _{Every figure in this repo and on the site is generated by the instruments themselves. No stock art.} </div>

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

Path	What	Verify with
mcp/	MCP server + TS reference engine	cd mcp && npm test
core/	C++20 engine, C ABI in include/mary/mary.h	cmake --preset release && ctest --preset release
data/	Spectral ingestion pipeline, quality gates Q1-Q6	cd data && uv run pytest
web/	The lab's website (Astro)	cd web && npm run build
bindings/	node N-API, WASM, Python scaffolds	builds in CI
papers/	Paper threads with pinned artifacts	in preparation
docs/	PRD, architecture, tool reference, ABI rules	start at docs/PRD.md

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.