SPEDAS MCP

spedas_mcp is the SPEDAS organization MCP server for agentic heliophysics workflows. It presents one SPEDAS-facing data layer and organizes capabilities by data source category instead of by the internal backend packages used to implement them.

The current design follows Jason's A+B direction:

• A. SPEDAS data layer — one unified entry point for source categories such as cdaweb, pds, and spice/geometry.
• B. SPEDAS science workflow layer — high-level planning tools that let Claude Code, Codex, OpenCode, LingTai, or another agent start from a science question before choosing source-specific operations.

The xhelio-* packages are implementation backends. They should stay visible to maintainers, but they should not be the user's first mental model.

Repository

• Official repo: <https://github.com/spedas/spedas_mcp>
• Python package name: spedas-mcp
• Python module / CLI module: spedas_mcp
• Current MCP tool count: 26

Layered capability map

1. Data layer tools

Start here when the user asks for data, datasets, parameters, products, archives, or cache status.

• browse_data_sources(source_type="all", query=None) — browse SPEDAS data source categories, or drill into one category.
• load_data_source(source_type, source_id) — load source context, e.g. a CDAWeb observatory, PDS mission, or SPICE mission/frame context.
• browse_data_parameters(source_type, dataset_id, dataset_ids=None) — browse parameters/metadata for CDAWeb or PDS datasets; for SPICE, returns geometry/frame context.
• fetch_data_product(source_type, dataset_id, parameters, start=None, stop=None, output_dir=None, format="csv", limit=None) — unified measurement/archive data fetch for CDAWeb/PDS. SPICE requests are routed to geometry tools instead. limit is currently a CDAWeb-oriented safety control; PDS fetches should be narrowed by time/parameters.
• manage_data_cache(source_type="all", action="status", cache_dir=None, mission=None) — unified cache status/maintenance for the source categories. Per-call cache_dir is reported as guidance only; backend cache roots are configured by the MCP server environment.

Supported source_type values:

2. Science workflow tools

Start here for open-ended science requests.

• spedas_overview() — compact map of capability groups and recommended workflow.
• search_spedas_data_sources(question, target=None, observables=None) — recommend which data source categories should lead a request.
• plan_spedas_observation(science_goal, start=None, stop=None, target=None, observables=None, data_sources=None) — produce a source-specific plan before fetching data.
• compare_cdaweb_pds_spice(science_goal="") — explain source boundaries and choose the right source family.
• create_spedas_analysis_bundle(study_name, output_dir, ...) — create a request/provenance scaffold with requests/, data/, plots/, provenance/, and notes/ folders.

3. Geometry tools

SPICE is exposed as a data source category, but geometry operations are clearer as explicit tools:

• list_spice_missions()
• get_ephemeris(mission, target, start, stop, step="1h", frame="J2000", observer=None)
• compute_distance(mission, target, observer, start, stop, step="1h")
• transform_coordinates(mission, coordinates, from_frame, to_frame, epoch=None)
• list_coordinate_frames(mission=None)
• manage_spice_kernels(action, mission=None, cache_dir=None)

4. Compatibility low-level tools

These remain available for clients that already know the source-specific operations:

• CDAWeb: browse_observatories, load_observatory, browse_parameters, fetch_data, manage_cdaweb_cache
• PDS: browse_pds_missions, load_pds_mission, browse_pds_parameters, fetch_pds_data, manage_pds_cache
• SPICE: the geometry tools above plus manage_spice_kernels

Compatibility tools are supported for existing clients, but their MCP descriptions now mark them as compatibility entries and point to the unified alternatives. Hiding, renaming, or moving them would be a breaking API pass and should not happen without maintainer review. See docs/public_api_strategy.md for the compatibility map and deprecation guidance.

Recommended agent workflow

1. Call spedas_overview().
2. For a natural-language science request, call search_spedas_data_sources(...) or plan_spedas_observation(...).
3. Use the data layer:

• browse_data_sources(source_type="all")
• browse_data_sources(source_type="cdaweb" | "pds" | "spice")
• load_data_source(...)
• browse_data_parameters(...)
• fetch_data_product(...) for CDAWeb/PDS measurement/archive products

1. Use geometry tools directly for SPICE ephemeris, distance, frame, and coordinate-transform work.
2. For any real analysis, call create_spedas_analysis_bundle(...) and write fetched files under the generated data/ directory.
3. Return compact summaries and file paths. Do not paste large science arrays into chat.

Quick start for local development

git clone https://github.com/spedas/spedas_mcp.git
cd spedas_mcp
uv sync --extra dev --extra mcp
uv run --extra mcp python -m spedas_mcp

Run tests and smoke checks:

uv run --extra dev --extra mcp python -m pytest -q
uv run --extra mcp python scripts/smoke_mcp_list_tools.py --json
uv run --extra dev --extra mcp python scripts/validate_plugin_packages.py

The list-tools smoke starts the stdio MCP server with isolated temporary cache directories, performs MCP initialize + list_tools, and verifies the expected advertised tool names. It does not fetch CDAWeb/PDS data or download SPICE kernels.

MCP client configuration

Example stdio configuration:

{
  "mcpServers": {
    "spedas": {
      "command": "uv",
      "args": ["run", "--extra", "mcp", "python", "-m", "spedas_mcp"],
      "cwd": "/path/to/spedas_mcp"
    }
  }
}

For plugin-style distribution, the canonical standalone wrappers now live in separate SPEDAS org repos:

• <https://github.com/spedas/spedas_claude> — Claude Code plugin wrapper.
• <https://github.com/spedas/spedas_codex> — Codex plugin wrapper.

The in-repo plugins/spedas-claude/ and .agents/plugins/spedas-codex/ directories remain lightweight development examples and compatibility fixtures; runtime-specific packaging should evolve in the standalone repos while this repository owns the MCP server itself.

Maintainer-facing positioning

spedas_mcp should be thick at the SPEDAS data/workflow layer and thin at the backend implementation layer:

• Users see one SPEDAS MCP and one data layer.
• Data source categories are scientific concepts: CDAWeb, PDS, SPICE/geometry.
• Backend packages remain maintainable internal implementation surfaces.
• Higher-level tools should encode reusable SPEDAS scientific method: source selection, planning, provenance, and artifact discipline.

See docs/maintainer_note.md and docs/examples/agent_workflow.md for the current framing.

• docs/examples/juno_pds_spice_workflow.md — Juno MAG/PDS discovery plus SPICE geometry planning, including current caveats.