squadds_mcp package

Subpackages

• squadds_mcp.prompts package
  • Submodules
  • squadds_mcp.prompts.workflows module
  • Module contents
    • Prompt sub-package for the SQuADDS MCP server.
• squadds_mcp.resources package
  • Submodules
  • squadds_mcp.resources.layout_guide module
  • squadds_mcp.resources.metadata module
  • Module contents
    • Resource sub-package for the SQuADDS MCP server.
• squadds_mcp.tools package
  • Submodules
  • squadds_mcp.tools.analysis module
  • squadds_mcp.tools.contribution module
  • squadds_mcp.tools.database module
  • squadds_mcp.tools.generation module
  • squadds_mcp.tools.interpolation module
  • Module contents
    • Tool sub-package for the SQuADDS MCP server.

Submodules

squadds_mcp.schemas module

Pydantic schemas for MCP tool inputs and outputs.

These models define the structured data contracts for all MCP tools. They enable:

• Automatic JSON Schema generation for MCP clients

• Input validation before tool execution

• Type-safe, documented responses

Adding a New Schema

1. Define a Pydantic BaseModel class with typed fields.

2. Use Field(...) to add descriptions — these become tool parameter docs.

3. Import and use the schema in your tool function’s type annotations.

class squadds_mcp.schemas.ClosestDesignsResult(*, designs, num_results, target_params, system_config)

Bases: BaseModel

Result set from find_closest_designs.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

designs: list[DesignResult]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

num_results: int

system_config: dict[str, Any]

target_params: dict[str, Any]

class squadds_mcp.schemas.ComponentListResult(*, items, count)

Bases: BaseModel

List of supported components or component names.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

count: int

items: list[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class squadds_mcp.schemas.ConfigListResult(*, configs, count)

Bases: BaseModel

List of dataset configuration strings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

configs: list[str]

count: int

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class squadds_mcp.schemas.ContributorInfo(*, uploader=None, PI=None, group=None, institution=None)

Bases: BaseModel

Information about a data contributor.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

PI: str | None

group: str | None

institution: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

uploader: str | None

class squadds_mcp.schemas.ContributorsResult(*, contributors, count)

Bases: BaseModel

List of contributors.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

contributors: list[ContributorInfo]

count: int

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class squadds_mcp.schemas.DatasetEntry(*, data)

Bases: BaseModel

A single row from a SQuADDS dataset, serialized as a dict.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

data: dict[str, Any]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class squadds_mcp.schemas.DatasetInfoResult(*, config, num_rows, features, description='', size_bytes=None)

Bases: BaseModel

Metadata about a SQuADDS dataset.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

config: str

description: str

features: dict[str, str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

num_rows: int

size_bytes: int | None

class squadds_mcp.schemas.DatasetResult(*, rows, total_rows, offset, limit, component, component_name, data_type)

Bases: BaseModel

Paginated dataset result.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

component: str

component_name: str

data_type: str

limit: int

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

offset: int

rows: list[dict[str, Any]]

total_rows: int

class squadds_mcp.schemas.DatasetSummaryResult(*, datasets, count)

Bases: BaseModel

Summary table of all available datasets.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

count: int

datasets: list[DatasetSummaryRow]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class squadds_mcp.schemas.DatasetSummaryRow(*, component, component_name, data_type)

Bases: BaseModel

Summary of a single available dataset.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

component: str

component_name: str

data_type: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class squadds_mcp.schemas.DesignResult(*, rank, design_options, hamiltonian_params, metadata=<factory>)

Bases: BaseModel

Result from a closest-design search.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

design_options: dict[str, Any]

hamiltonian_params: dict[str, Any]

metadata: dict[str, Any]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

rank: int

class squadds_mcp.schemas.HamiltonianKeysResult(*, keys, system_type)

Bases: BaseModel

Valid Hamiltonian parameter keys for a given system type.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

keys: list[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

system_type: str

class squadds_mcp.schemas.InterpolatedDesignResult(*, design_options, qubit_options, cavity_options, coupler_type=None, scaling_info=<factory>)

Bases: BaseModel

Result from scaling interpolation.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

cavity_options: dict[str, Any]

coupler_type: str | None

design_options: dict[str, Any]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

qubit_options: dict[str, Any]

scaling_info: dict[str, Any]

class squadds_mcp.schemas.MeasuredDeviceResult(*, name, design_code=None, paper_link=None, foundry=None, fabrication_recipe=None)

Bases: BaseModel

Information about a measured (experimental) device.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

design_code: str | None

fabrication_recipe: Any | None

foundry: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

paper_link: str | None

class squadds_mcp.schemas.SystemConfig(*, system_type, qubit='TransmonCross', cavity='RouteMeander', resonator_type='quarter')

Bases: BaseModel

Configuration for selecting a quantum system in SQuADDS.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

cavity: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

qubit: str

resonator_type: str

system_type: str

class squadds_mcp.schemas.TargetParams(*, qubit_frequency_GHz=None, anharmonicity_MHz=None, cavity_frequency_GHz=None, kappa_kHz=None, g_MHz=None, resonator_type=None)

Bases: BaseModel

Target Hamiltonian parameters for a design search.

Not all fields are required — which ones to set depends on system_type: - qubit: qubit_frequency_GHz, anharmonicity_MHz - cavity_claw: cavity_frequency_GHz, kappa_kHz, resonator_type - qubit_cavity: all of the above plus g_MHz

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

anharmonicity_MHz: float | None

cavity_frequency_GHz: float | None

g_MHz: float | None

kappa_kHz: float | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

qubit_frequency_GHz: float | None

resonator_type: str | None

to_search_dict()

Convert to a plain dict, dropping None values.

Return type:

dict[str, Any]

class squadds_mcp.schemas.VersionResult(*, squadds_version, mcp_server_version, repo_name)

Bases: BaseModel

SQuADDS version information.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

mcp_server_version: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

repo_name: str

squadds_version: str

squadds_mcp.server module

squadds_mcp.utils module

Shared utilities for the SQuADDS MCP server.

Helpers for serialization, formatting, and error handling used across all tools and resources.

Adding a New Utility

1. Add your function here.

2. Keep it stateless — no imports of SQuADDS_DB or Analyzer at module level.

3. Add a docstring with Args/Returns so AI agents can understand usage.

squadds_mcp.utils.build_error_response(message, details=None)

Build a formatted error message for tool responses.

Parameters:

• message (str) – Human-readable error message.

• details (dict[str, Any] | None) – Optional extra context.

Returns:

Formatted error string.

Return type:

str

squadds_mcp.utils.dataframe_to_records(df, limit=50, offset=0)

Convert a DataFrame slice to a list of JSON-safe dicts.

Parameters:

• df (DataFrame) – The pandas DataFrame.

• limit (int) – Maximum number of rows to return.

• offset (int) – Starting row index.

Returns:

List of dicts, one per row, with numpy types converted to Python builtins.

Return type:

list[dict[str, Any]]

squadds_mcp.utils.extract_h_params_from_row(row, h_param_keys)

Extract Hamiltonian parameter values from a DataFrame row.

Parameters:

• row (Series) – A single row from the analysis DataFrame.

• h_param_keys (list[str]) – List of H-parameter column names.

Returns:

Dict of parameter name → value.

Return type:

dict[str, Any]

squadds_mcp.utils.format_design_options(design_options)

Format a design options dict as a human-readable JSON string.

Parameters:

design_options (dict[str, Any]) – The raw design options dictionary.

Returns:

Pretty-printed JSON string.

Return type:

str

squadds_mcp.utils.safe_get(obj, *keys, default=None)

Safely traverse nested dicts/objects.

Parameters:

• obj (Any) – The root object to traverse.

• *keys (str) – Sequence of keys to follow.

• default (Any) – Value to return if any key is missing.

Returns:

The value at the nested path, or default.

Return type:

Any

squadds_mcp.utils.sanitize_for_json(obj)

Recursively convert numpy/pandas types to JSON-serializable Python types.

Handles: ndarray, int64/float64, NaN, Timestamp, bytes, sets.

Parameters:

obj (Any) – Any Python object that may contain numpy/pandas types.

Returns:

A JSON-safe version of the object.

Return type:

Any

Module contents

SQuADDS MCP Server

Model Context Protocol (MCP) server for the SQuADDS (Superconducting Qubit And Device Design and Simulation) database.

This package provides a thin MCP wrapper around the SQuADDS Python library, exposing database queries, design search, and interpolation capabilities to AI agents and human developers via the standardized MCP protocol.

Usage:

# Run via CLI squadds-mcp

# Or run via uv uv run squadds-mcp

# Or import and run programmatically from squadds_mcp.server import create_server server = create_server() server.run(transport=”stdio”)