MCP reference¶

The spectro-kernel MCP server, version 0.8.1: 142 tools (13 session / discovery tools and 129 algorithm tools), 3 resources and 2 resource templates. This page is generated from the server at build time, so it is exactly what a client sees after tools/list and resources/list; Using it as an MCP server explains sessions, transports and the hardened HTTP mode. The same inventory, with the full JSON schemas, is available as mcp-tools.json.

How the server introduces itself¶

The instructions a client receives on initialize:

spectro-kernel exposes a catalogue of astronomical spectroscopy algorithms.

Typical workflow:
  1. create_session()                       -> session_id
  2. load_spectrum(session_id, path)        load a FITS/ASCII spectrum
  3. call analysis tools (normalize_polynomial, snr_der, fit_gaussian_line, ...)
     each one takes session_id and an optional params object
  4. get_session_state(session_id)          inspect accumulated results

Use list_algorithms / describe_algorithm to discover tools and their parameters, or
run_preset to execute a whole pipeline at once. The catalogue is also readable as
resources: spectro://algorithms, spectro://algorithms/{name}, spectro://recipes,
spectro://recipes/{name} and spectro://llms.txt (a short map of this server).

Session and discovery tools¶

These tools manage the working session (one WorkContext kept alive between calls), load spectra and expose the catalogue.

create_session¶

Create a new working session and return its id.

Every other tool needs a session_id. Call this first.

This tool takes no arguments.

end_session¶

Discard a working session and free its memory.

load_spectrum¶

Load a spectrum file (FITS or ASCII, local path or http(s) URL) into a session.

The spectrum becomes the session's working spectrum, ready for the analysis tools.

load_spectrum_from_url¶

Download a spectrum from url and load it as the session's working spectrum.

Use after request_upload_url (with the returned download_url) or with any reachable http(s) URL. The file type is inferred from the URL suffix; pass format_hint ("fits" or "ascii") to override.

request_upload_url¶

Return a presigned URL the client can PUT a file to, plus the GET URL.

Use this when a spectrum is too large to inline in MCP. The client uploads with HTTP PUT, then calls load_spectrum_from_url with the returned download_url. Requires SPECTRO_MCP_S3_BUCKET (+ optional endpoint) configured on the server.

get_session_state¶

Return a summary of everything currently held in a session's context.

get_spectrum_preview¶

Return a downsampled preview of the session's current spectrum (50 samples).

get_spectrum_data¶

Return the session spectrum as JSON arrays, at most max_points samples.

Heavier than get_spectrum_preview — use this when the caller needs to plot or re-analyse the spectrum client-side and the 50-point preview is too coarse. Returns {wavelength, flux, uncertainty, wavelength_unit, flux_unit, meta, downsampled, npix_total, npix_returned, stride}. Spectra longer than max_points (default 20000) are stride-downsampled (every k-th sample) and flagged downsampled: true; pass max_points=0 to get every pixel.

list_algorithms¶

List the available spectroscopy algorithms, optionally filtered by category.

describe_algorithm¶

Return the full details (parameters, inputs, outputs) of one algorithm.

get_algorithm_source¶

Return the source code of one algorithm's wrapper class.

Useful when the agent (or its user) wants to audit what the wrapper does — especially for algorithms backed by an external library (astropy, easyspec, scipy). The response carries the repository- relative path, a GitHub permalink, the declared backend, and the source as a UTF-8 string. The absolute path on disk (path) is only filled in when the server runs locally (stdio mode).

list_presets¶

List every preset available on this server (bundled + installed collections).

This tool takes no arguments.

run_preset¶

Run a complete preset pipeline against a session's context in one call.

variables binds the preset's declared variables (its instrument / observer profile); list_presets says how many a preset declares and describe them via the preset's page or spectro preset show.

Algorithm tools¶

Every algorithm of the catalogue is a tool of the same name. All of them take the same two arguments and return the same response shape; the algorithm's parameters go in params and are documented on its page (the tool description carries the same text).

Response (outputSchema is an open object; the fields are always these):

{
  "algorithm": "<name>",
  "success": true,
  "message": "<human-readable summary or null>",
  "error": "<error message when success is false, else null>",
  "metrics": {
    "<metric>": 0.0
  },
  "artifacts": {
    "<key>": "<JSON-safe value>"
  },
  "context": {
    "has_spectrum": true,
    "metrics": {},
    "line_fits": [],
    "n_history": 0
  }
}

metrics is the session's whole metrics dict after the run (not only this tool's), context is WorkContext.summary(). Non-finite numbers are serialised as null.

Input / output¶

Master frames¶

Preprocessing (2-D image)¶

Cosmic-ray rejection¶

Extraction (2-D to 1-D)¶

Wavelength calibration¶

Flux calibration¶

Continuum¶

Smoothing¶

Resampling¶

Transforms¶

Quality / SNR¶

Line detection¶

Line fitting¶

Corrections¶

Radial velocity¶

Time series¶

Stacking¶

Embeddings¶

Nebular diagnostics¶

Kinematics¶

Spectral classification¶

Stellar activity¶

External catalogues¶

Visualisation¶

Export¶

Advanced¶

Resources¶

Read-only views of the catalogue, backed by the same builders as the published JSON (algorithms.json, presets.json). Read them with resources/read; no session is needed.

An unknown {name} returns an MCP error whose message names the catalogue resource to read; in shared (HTTP) mode a recipe found on SPECTRO_PRESET_PATH reports its source as path rather than the directory.

Error behaviour¶

• A missing or expired session_id, a refused path or URL and an unknown algorithm or recipe raise a tool error whose message reaches the client even when the server masks unexpected exceptions (--http).
• A load that fails (unreadable file, empty spectrum, refused URL) returns {"error": "..."} instead of raising, so the agent can recover.
• An algorithm that fails returns success: false with error set; the session context is unchanged.
• In --http mode unexpected exceptions are masked (mask_error_details), local filesystem paths are refused and URLs go through the SSRF guard.

The same catalogue, every door¶

The tools are generated from the registry, so the Python API and the CLI expose the same algorithms with the same parameters.