imas-standard-names 0.7.0rc3

A collection of Standard Names used in the Fusion Conventions and logic for creating a static website for documentation.

IMAS Standard Names

Grammar library and read-only MCP server for IMAS Standard Names — a controlled vocabulary for fusion data variables.

Quick Start

MCP Server

Configure your AI assistant to use the standard names tools:

# Install the MCP server
uv tool install imas-standard-names

# Or with pip
pip install imas-standard-names

Add to your MCP configuration (e.g., Claude Desktop, VS Code):

{
  "mcpServers": {
    "imas-standard-names": {
      "command": "standard-names-mcp"
    }
  }
}

Python Library

from imas_standard_names import StandardNameCatalog

catalog = StandardNameCatalog()
entry = catalog.get("electron_temperature")
print(f"{entry.name}: {entry.unit} — {entry.description}")

Installation

The tools and catalog are distributed separately:

Package	Purpose
imas-standard-names	Grammar library, validation, read-only MCP server
imas-standard-names-catalog	Standard names catalog (YAML + SQLite)

Basic Installation

# Tools + catalog (recommended)
pip install imas-standard-names[catalog]

# Tools only
pip install imas-standard-names

Catalog Options

The catalog can be accessed in several ways:

# Option 1: Install catalog package (recommended)
pip install imas-standard-names-catalog

# Option 2: Download pre-built database
wget https://github.com/iterorganization/imas-standard-names-catalog/releases/latest/download/catalog.db
export STANDARD_NAMES_CATALOG_DB=./catalog.db

# Option 3: Clone catalog repository (for development)
git clone https://github.com/iterorganization/imas-standard-names-catalog.git
export STANDARD_NAMES_CATALOG_ROOT=./imas-standard-names-catalog/standard_names

Development Setup

git clone https://github.com/iterorganization/imas-standard-names.git
cd imas-standard-names
uv sync

Architecture

This project uses a two-repository architecture:

• imas-standard-names (this repo): Grammar library, validation, read-only MCP server, Python API
• imas-standard-names-catalog: YAML source files and pre-built SQLite database

Name generation is handled by imas-codex, which uses ISN's grammar API to mint candidates.

This separation allows independent versioning — catalog content, tooling, and generation logic evolve separately.

Documentation

Full documentation: iterorganization.github.io/IMAS-Standard-Names

• Grammar Reference — naming rules and vocabulary
• Guidelines — patterns and conventions
• Quick Start — getting started
• Architecture — project boundary and API contract

MCP Tools

The MCP server provides read-only tools for AI assistants to work with standard names:

Grammar & Schema

Tool	Purpose
get_grammar	Grammar rules, patterns, and composition guidance
get_schema	Entry schema for understanding catalog entry structure
compose_standard_name	Build valid names from structured parts
parse_standard_name	Parse names into grammatical components
get_vocabulary	Controlled vocabulary tokens by grammar segment

Catalog Query

Tool	Purpose
search_standard_names	Find names by concept using semantic search
list_standard_names	List names with filtering by status, tags, kind
fetch_standard_names	Get complete metadata for specific names
check_standard_names	Fast batch validation of name existence

Reference & Validation

Tool	Purpose
validate_catalog	Check catalog integrity and grammar compliance
get_tokamak_parameters	Reference tokamak machine parameters

License

MIT