Cookbook - a web playground for spectro-kernel¶

A minimal browser page that lets you drop a spectrum into the kernel without leaving the address bar. Useful for demos, for collaborators who don't run Python locally, or as a starting point for a richer in-house tool.

Lives in the repo at website/playground/index.html, a single self-contained HTML file, no build step.

Architecture¶

[ browser : playground/index.html ]
        │ JSON-RPC over HTTP
        ▼
[ spectro-mcp --http  (your machine or DO) ]
        │ in-process
        ▼
[ spectro-kernel  (the catalogue) ]

The page never touches a FITS file itself: it asks the MCP server to load it (load_spectrum), then chains algorithm tools (snr_der, normalize_polynomial, fit_gaussian_line …). The server reads the FITS from a path it can see locally.

Run it locally in two terminals¶

Terminal A - start the MCP server:

pip install "spectro-kernel[mcp]"
spectro-mcp --http --host 127.0.0.1 --port 8000

Terminal B - serve the playground:

cd website/playground
python3 -m http.server 8888

Open http://localhost:8888 in a browser, hit Check /health - you should see connected. Then fill in a FITS path the MCP server can read (e.g. /Users/you/data/deneb.fits) and click an action.

Securing it for a public deployment¶

When you publish the MCP server (DigitalOcean, Render…), turn on the auth guardrails:

export SPECTRO_MCP_API_KEY="sk-live-…"          # require an X-API-Key header
export SPECTRO_MCP_RATE_PER_MINUTE=60           # sliding-window per key
export SPECTRO_MCP_REDIS_URL="redis://…/0"      # cross-instance sessions
spectro-mcp --http --port 8000

Then enter the same API key in the playground's "API key" field - every request goes out with the X-API-Key header.

Known limitations¶

Browser-side FITS upload is not implemented. The load_spectrum tool takes a path the server can read. A real upload flow needs an additional upload_spectrum MCP tool (with a presigned S3 / DO Spaces URL) - that is the natural next step, scaffolded but not built in v0.1.
CORS. The MCP server does not set Access-Control-Allow-Origin. For a cross-origin browser, put the MCP behind a reverse proxy (nginx / Caddy) that adds the CORS headers, or run the playground on the same host:port.
MCP transport. The page talks vanilla JSON-RPC over HTTP. Streaming (SSE) is not used - the playground is request/response only.

What it gives you¶

A 4-action shelf:

Button	What it runs
`snr_der`	DER_SNR estimator.
`normalise + snr_der`	Continuum-normalise, then SNR.
`normalise + detect_lines (balmer)`	Look for hydrogen lines after normalisation.
`fit H-α`	Normalise then fit a Gaussian to H-alpha at 6562.79 Å.

Output is rendered as raw JSON - perfect for a demo, easy to copy into the next script. Read website/playground/index.html to see how each call is wired (the callTool function is ~10 lines).