# IMAS MCP Server
[![pre-commit][pre-commit-badge]][pre-commit-link]
[![Ruff][ruff-badge]][ruff-link]
[![Python versions][python-badge]][python-link]
[![CI/CD status][build-deploy-badge]][build-deploy-link]
[![Coverage status][codecov-badge]][codecov-link]
[![Documentation][docs-badge]][docs-link]
[![ASV][asv-badge]][asv-link]
A Model Context Protocol (MCP) server providing AI assistants with access to IMAS (Integrated Modelling & Analysis Suite) data structures through natural language search and optimized path indexing.
## Quick Start
Select the setup method that matches your environment:
- HTTP (Hosted): Zero install. Connect to the public endpoint running the latest tagged MCP server from the ITER Organization.
- UV (Local): Install and run in your own Python environment for editable development.
- Docker : Run an isolated container with pre-built indexes.
- Slurm / HPC (STDIO): Launch inside a cluster allocation without opening network ports.
Choose hosted for instant access; choose a local option for customization or controlled resources.
[HTTP](#http-remote-public-endpoint) | [UV](#uv-local-install) | [Docker](#docker-setup) | [Slurm / HPC](#slurm--hpc-stdio)
### HTTP (Remote Public Endpoint)
Connect to the public ITER Organization hosted server—no local install.
#### VS Code (Interactive)
1. `Ctrl+Shift+P` → "MCP: Add Server"
2. Select "HTTP Server"
3. Name: `imas`
4. URL: `https://imas-dd.iter.org/mcp`
#### VS Code (Manual JSON)
Workspace `.vscode/mcp.json` (or inside `"mcp"` in user settings):
```json
{
"servers": {
"imas": { "type": "http", "url": "https://imas-dd.iter.org/mcp" }
}
}
```
#### Claude Desktop config
Pick path for your OS:
Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`
macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Linux: `~/.config/claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"imas-mcp-hosted": {
"command": "npx",
"args": ["mcp-remote", "https://imas-dd.iter.org/mcp"]
}
}
}
```
#### OP Client (Pending Clarification)
Placeholder: clarify what "op" refers to (e.g. OpenAI, Operator) to add tailored instructions.
### UV Local Install
Install with [uv](https://docs.astral.sh/uv/):
```bash
uv tool install imas-mcp
# or add to a project env
uv add imas-mcp
```
VS Code:
```json
{
"servers": {
"imas-mcp-uv": {
"type": "stdio",
"command": "uv",
"args": ["run", "--active", "imas-mcp", "--no-rich"]
}
}
}
```
Claude Desktop:
```json
{
"mcpServers": {
"imas-mcp-uv": {
"command": "uv",
"args": ["run", "--active", "imas-mcp", "--no-rich"]
}
}
}
```
### Docker Setup
Run locally in a container (pre-built indexes included):
```bash
docker run -d \
--name imas-mcp \
-p 8000:8000 \
ghcr.io/iterorganization/imas-mcp:latest-streamable-http
# Optional: verify
docker ps --filter name=imas-mcp --format "table {{.Names}}\t{{.Status}}"
```
VS Code (`.vscode/mcp.json`):
```json
{
"servers": {
"imas-mcp-docker": { "type": "http", "url": "http://localhost:8000/mcp" }
}
}
```
Claude Desktop:
```json
{
"mcpServers": {
"imas-mcp-docker": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:8000/mcp"]
}
}
}
```
### Slurm / HPC (STDIO)
Helper script: `scripts/imas_mcp_slurm_stdio.sh`
VS Code (`.vscode/mcp.json`, JSONC ok):
```jsonc
{
"servers": {
"imas-slurm-stdio": {
"type": "stdio",
"command": "scripts/imas_mcp_slurm_stdio.sh"
}
}
}
```
Launch behavior:
1. If `SLURM_JOB_ID` present → start inside current allocation.
2. Else requests node with `srun --pty` then starts server (unbuffered stdio).
Resource tuning (export before client starts):
| Variable | Purpose | Default |
| -------------------------- | ---------------------------------------- | --------------- |
| `IMAS_MCP_SLURM_TIME` | Walltime | `08:00:00` |
| `IMAS_MCP_SLURM_CPUS` | CPUs per task | `1` |
| `IMAS_MCP_SLURM_MEM` | Memory (e.g. `4G`) | Slurm default |
| `IMAS_MCP_SLURM_PARTITION` | Partition | Cluster default |
| `IMAS_MCP_SLURM_ACCOUNT` | Account/project | User default |
| `IMAS_MCP_SLURM_EXTRA` | Extra raw `srun` flags | (empty) |
| `IMAS_MCP_USE_ENTRYPOINT` | Use `imas-mcp` entrypoint vs `python -m` | `0` |
Example:
```bash
export IMAS_MCP_SLURM_TIME=02:00:00
export IMAS_MCP_SLURM_CPUS=4
export IMAS_MCP_SLURM_MEM=8G
export IMAS_MCP_SLURM_PARTITION=compute
```
Direct CLI:
```bash
scripts/imas_mcp_slurm_stdio.sh --ids-filter "core_profiles equilibrium"
```
Why STDIO? Avoids opening network ports; all traffic rides the existing `srun` pseudo-TTY.
---
## Example IMAS Queries
Once you have the IMAS MCP server configured, you can interact with it using natural language queries. Use the `@imas` prefix to direct queries to the IMAS server:
### Basic Search Examples
```text
@imas Find data paths related to plasma temperature
@imas Search for electron density measurements
@imas What data is available for magnetic field analysis?
@imas Show me core plasma profiles
```
### Physics Concept Exploration
```text
@imas Explain what equilibrium reconstruction means in plasma physics
@imas What is the relationship between pressure and magnetic fields?
@imas How do transport coefficients relate to plasma confinement?
@imas Describe the physics behind current drive mechanisms
```
### Data Structure Analysis
```text
@imas Analyze the structure of the core_profiles IDS
@imas What are the relationships between equilibrium and core_profiles?
@imas Show me identifier schemas for transport data
@imas Export bulk data for equilibrium, core_profiles, and transport IDS
```
### Advanced Queries
```text
@imas Find all paths containing temperature measurements across different IDS
@imas What physics domains are covered in the IMAS data dictionary?
@imas Show me measurement dependencies for fusion power calculations
@imas Explore cross-domain relationships between heating and confinement
```
### Workflow and Integration
```text
@imas How do I access electron temperature profiles from IMAS data?
@imas What's the recommended workflow for equilibrium analysis?
@imas Show me the branching logic for diagnostic identifier schemas
@imas Export physics domain data for comprehensive transport analysis
```
The IMAS MCP server provides 8 specialized tools for different types of queries:
- **Search**: Natural language and structured search across IMAS data paths
- **Explain**: Physics concepts with IMAS context and domain expertise
- **Overview**: General information about IMAS structure and available data
- **Analyze**: Detailed structural analysis of specific IDS
- **Explore**: Relationship discovery between data paths and physics domains
- **Identifiers**: Exploration of enumerated options and branching logic
- **Bulk Export**: Comprehensive export of multiple IDS with relationships
- **Domain Export**: Physics domain-specific data with measurement dependencies
## Development
For local development and customization:
### Setup
```bash
# Clone repository
git clone https://github.com/iterorganization/imas-mcp.git
cd imas-mcp
# Install development dependencies (search index build takes ~8 minutes first time)
uv sync --all-extras
```
### Build Dependencies
This project requires additional dependencies during the build process that are not part of the runtime dependencies:
- **`imas-data-dictionary`** - Git development package, required only during wheel building for parsing latest DD changes
- **`rich`** - Used for enhanced console output during build processes
**For runtime:** The `imas-data-dictionaries` PyPI package is now a core dependency and provides access to stable DD versions (e.g., 4.0.0). This eliminates the need for the git package at runtime and ensures reproducible builds.
**For developers:** Build-time dependencies are included in the `[build-system.requires]` section for wheel building. The git package is only needed when building wheels with latest DD changes.
```bash
# Regular development - uses imas-data-dictionaries (PyPI)
uv sync --all-extras
# Set DD version for building (defaults to 4.0.0)
export IMAS_DD_VERSION=4.0.0
uv run build-schemas
```
**Location in configuration:**
- **Build-time dependencies**: Listed in `[build-system.requires]` in `pyproject.toml`
- **Runtime dependencies**: `imas-data-dictionaries>=4.0.0` in `[project.dependencies]`
**Note:** The `IMAS_DD_VERSION` environment variable controls which DD version is used for building schemas and embeddings. Docker containers have this set to `4.0.0` by default.
### Development Commands
```bash
# Run tests
uv run pytest
# Run linting and formatting
uv run ruff check .
uv run ruff format .
# Build schema data structures from IMAS data dictionary
uv run build-schemas
# Build document store and semantic search embeddings
uv run build-embeddings
# Run the server locally (default: streamable-http on port 8000)
uv run --active imas-mcp --no-rich
# Run with stdio transport for MCP clients
uv run --active imas-mcp --no-rich --transport stdio
```
### Build Scripts
The project includes two separate build scripts for creating the required data structures:
**`build-schemas`** - Creates schema data structures from IMAS XML data dictionary:
- Transforms XML data into optimized JSON format
- Creates catalog and relationship files
- Use `--ids-filter "core_profiles equilibrium"` to build specific IDS
- Use `--force` to rebuild even if files exist
**`build-embeddings`** - Creates document store and semantic search embeddings:
- Builds in-memory document store from JSON data
- Generates sentence transformer embeddings for semantic search
- Caches embeddings for fast loading
- Use `--model-name "all-mpnet-base-v2"` for different models
- Use `--force` to rebuild embeddings cache
- Use `--no-normalize` to disable embedding normalization
- Use `--half-precision` to reduce memory usage
- Use `--similarity-threshold 0.1` to set similarity score thresholds
**Note:** The build hook creates JSON data. Build embeddings separately using `build-embeddings` for better control and performance.
### Local Development MCP Configuration
#### VS Code
The repository includes a `.vscode/mcp.json` file with pre-configured development server options. Use the `imas-local-stdio` configuration for local development.
#### Claude Desktop
Add to your config file:
```json
{
"mcpServers": {
"imas-local-dev": {
"command": "uv",
"args": ["run", "--active", "imas-mcp", "--no-rich", "--auto-build"],
"cwd": "/path/to/imas-mcp"
}
}
}
```
## How It Works
1. **Installation**: During package installation, the index builds automatically when the module first imports
2. **Build Process**: The system parses the IMAS data dictionary and creates comprehensive JSON files with structured data
3. **Embedding Generation**: Creates semantic embeddings using sentence transformers for advanced search capabilities
4. **Serialization**: The system stores indexes in organized subdirectories:
- **JSON data**: `imas_mcp/resources/schemas/` (LLM-optimized structured data)
- **Embeddings cache**: Pre-computed sentence transformer embeddings for semantic search
5. **Import**: When importing the module, the pre-built index and embeddings load in ~1 second
## Optional Dependencies and Runtime Requirements
The IMAS MCP server now includes `imas-data-dictionaries` as a core dependency, providing stable DD version access (default: 4.0.0). The git development package (`imas-data-dictionary`) is used during wheel building when parsing latest DD changes.
### Package Installation Options
- **Runtime**: `uv add imas-mcp` - Includes all transports (stdio, sse, streamable-http)
- **Full installation**: `uv add imas-mcp` - Recommended for all users
### Data Dictionary Access
The system uses composable accessors to access IMAS Data Dictionary version and metadata:
1. **Environment Variable**: `IMAS_DD_VERSION` (highest priority) - Set to specify DD version (e.g., "4.0.0")
2. **Metadata File**: JSON metadata stored alongside indexes
3. **Index Name Parsing**: Extracts version from index filename
4. **Package Default**: Falls back to `imas-data-dictionaries` package (4.0.0)
This design ensures the server can:
- **Build indexes** using the version specified by `IMAS_DD_VERSION`
- **Run with pre-built indexes** using version metadata
- **Access stable DD versions** through `imas-data-dictionaries` PyPI package
### Index Building vs Runtime
- **Index Building**: Requires `imas-data-dictionary` package to parse XML and create indexes
- **Runtime Search**: Only requires pre-built indexes and metadata, no IMAS package dependency
- **Version Access**: Uses composable accessor pattern with multiple fallback strategies
## Implementation Details
### Search Implementation
The search system is the core component that provides fast, flexible search capabilities over the IMAS Data Dictionary. It combines efficient indexing with IMAS-specific data processing and semantic search to enable different search modes:
#### Search Methods
1. **Semantic Search** (`SearchMode.SEMANTIC`):
- AI-powered semantic understanding using sentence transformers
- Natural language queries with physics context awareness
- Finds conceptually related terms even without exact keyword matches
- Best for exploratory research and concept discovery
2. **Lexical Search** (`SearchMode.LEXICAL`):
- Fast text-based search with exact keyword matching
- Boolean operators (`AND`, `OR`, `NOT`)
- Wildcards (`*` and `?` patterns)
- Field-specific searches (e.g., `documentation:plasma ids:core_profiles`)
- Fastest performance for known terminology
3. **Hybrid Search** (`SearchMode.HYBRID`):
- Combines semantic and lexical approaches
- Provides both exact matches and conceptual relevance
- Balanced performance and comprehensiveness
4. **Auto Search** (`SearchMode.AUTO`):
- Intelligent search mode selection based on query characteristics
- Automatically chooses optimal search strategy
- Adaptive performance optimization
#### Key Capabilities
- **Search Mode Selection**: Choose between semantic, lexical, hybrid, or auto modes
- **Performance Caching**: TTL-based caching system with hit rate monitoring
- **Semantic Embeddings**: Pre-computed sentence transformer embeddings for fast semantic search
- **Physics Context**: Domain-aware search with IMAS-specific terminology
- **Advanced Query Parsing**: Supports complex search expressions and field filtering
- **Relevance Ranking**: Results sorted by match quality and physics relevance
## Future Work
### MCP Resources Implementation (Phase 2 - Planned)
We plan to implement MCP resources to provide efficient access to pre-computed IMAS data:
#### Planned Resource Features
- **Static JSON IDS Data**: Pre-computed IDS catalog and structure data served as MCP resources
- **Physics Measurement Data**: Domain-specific measurement data and relationships
- **Usage Examples**: Code examples and workflow patterns for common analysis tasks
- **Documentation Resources**: Interactive documentation and API references
#### Resource Types
- `ids://catalog` - Complete IDS catalog with metadata
- `ids://structure/{ids_name}` - Detailed structure for specific IDS
- `ids://physics-domains` - Physics domain mappings and relationships
- `examples://search-patterns` - Common search patterns and workflows
### MCP Prompts Implementation (Phase 3 - Planned)
Specialized prompts for physics analysis and workflow automation:
#### Planned Prompt Categories
- **Physics Analysis Prompts**: Specialized prompts for plasma physics analysis tasks
- **Code Generation Prompts**: Generate Python analysis code for IMAS data
- **Workflow Automation Prompts**: Automate complex multi-step analysis workflows
- **Data Validation Prompts**: Create validation approaches for IMAS measurements
#### Prompt Templates
- `physics-explain` - Generate comprehensive physics explanations
- `measurement-workflow` - Create measurement analysis workflows
- `cross-ids-analysis` - Analyze relationships between multiple IDS
- `imas-python-code` - Generate Python code for data analysis
### Performance Optimization (Phase 4 - In Progress)
Continued optimization of search and tool performance:
#### Current Optimizations (Implemented)
- ✅ **Search Mode Selection**: Multiple search modes (semantic, lexical, hybrid, auto)
- ✅ **Search Caching**: TTL-based caching with hit rate monitoring for search operations
- ✅ **Semantic Embeddings**: Pre-computed sentence transformer embeddings
- ✅ **ASV Benchmarking**: Automated performance monitoring and regression detection
#### Planned Optimizations
- **Advanced Caching Strategy**: Intelligent cache management for all MCP operations (beyond search)
- **Performance Monitoring**: Enhanced metrics tracking and analysis across all tools
- **Multi-Format Export**: Optimized export formats (raw, structured, enhanced)
- **Selective AI Enhancement**: Conditional AI enhancement based on request context
### Testing and Quality Assurance (Phase 5 - Planned)
Comprehensive testing strategy for all MCP components:
#### Test Implementation Goals
- **MCP Tool Testing**: Complete test coverage using FastMCP 2 testing framework
- **Resource Testing**: Validation of all MCP resources and data integrity
- **Prompt Testing**: Automated testing of prompt templates and responses
- **Performance Testing**: Benchmarking and regression detection for all tools
## Docker Usage
The server is available as a pre-built Docker container with the index already built:
```bash
# Pull and run the latest container
docker run -d -p 8000:8000 ghcr.io/iterorganization/imas-mcp:latest
# Or use Docker Compose
docker-compose up -d
```
See [DOCKER.md](DOCKER.md) for detailed container usage, deployment options, and troubleshooting.
[python-badge]: https://img.shields.io/badge/python-3.12-blue
[python-link]: https://www.python.org/downloads/
[ruff-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json
[ruff-link]: https://docs.astral.sh/ruff/
[pre-commit-badge]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
[pre-commit-link]: https://github.com/pre-commit/pre-commit
[build-deploy-badge]: https://img.shields.io/github/actions/workflow/status/simon-mcintosh/imas-mcp/test.yml?branch=main&color=brightgreen&label=CI%2FCD
[build-deploy-link]: https://github.com/iterorganization/imas-mcp/actions/workflows/test.yml
[codecov-badge]: https://codecov.io/gh/simon-mcintosh/imas-mcp/graph/badge.svg
[codecov-link]: https://codecov.io/gh/simon-mcintosh/imas-mcp
[docs-badge]: https://img.shields.io/badge/docs-online-brightgreen
[docs-link]: https://simon-mcintosh.github.io/imas-mcp/
[asv-badge]: https://img.shields.io/badge/ASV-Benchmarks-blue?style=flat&logo=speedtest&logoColor=white
[asv-link]: https://simon-mcintosh.github.io/imas-mcp/benchmarks/
Raw data
{
"_id": null,
"home_page": null,
"name": "imas-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.12",
"maintainer_email": null,
"keywords": "Data Dictionary, Fusion, IMAS, ITER, MCP, Model Context Protocol, Plasma Physics",
"author": null,
"author_email": "Simon McIntosh <simon.mcintosh@iter.org>",
"download_url": "https://files.pythonhosted.org/packages/f2/12/e92fe8276daaeb091d25b4f9ac7bd0653efee7cd5ea5dc629c6a3f061bf1/imas_mcp-3.1.0.tar.gz",
"platform": null,
"description": "# IMAS MCP Server\n\n[![pre-commit][pre-commit-badge]][pre-commit-link]\n[![Ruff][ruff-badge]][ruff-link]\n[![Python versions][python-badge]][python-link]\n[![CI/CD status][build-deploy-badge]][build-deploy-link]\n[![Coverage status][codecov-badge]][codecov-link]\n[![Documentation][docs-badge]][docs-link]\n[![ASV][asv-badge]][asv-link]\n\nA Model Context Protocol (MCP) server providing AI assistants with access to IMAS (Integrated Modelling & Analysis Suite) data structures through natural language search and optimized path indexing.\n\n## Quick Start\n\nSelect the setup method that matches your environment:\n\n- HTTP (Hosted): Zero install. Connect to the public endpoint running the latest tagged MCP server from the ITER Organization.\n- UV (Local): Install and run in your own Python environment for editable development.\n- Docker : Run an isolated container with pre-built indexes.\n- Slurm / HPC (STDIO): Launch inside a cluster allocation without opening network ports.\n\nChoose hosted for instant access; choose a local option for customization or controlled resources.\n\n[HTTP](#http-remote-public-endpoint) | [UV](#uv-local-install) | [Docker](#docker-setup) | [Slurm / HPC](#slurm--hpc-stdio)\n\n### HTTP (Remote Public Endpoint)\n\nConnect to the public ITER Organization hosted server\u2014no local install.\n\n#### VS Code (Interactive)\n\n1. `Ctrl+Shift+P` \u2192 \"MCP: Add Server\"\n2. Select \"HTTP Server\"\n3. Name: `imas`\n4. URL: `https://imas-dd.iter.org/mcp`\n\n#### VS Code (Manual JSON)\n\nWorkspace `.vscode/mcp.json` (or inside `\"mcp\"` in user settings):\n\n```json\n{\n \"servers\": {\n \"imas\": { \"type\": \"http\", \"url\": \"https://imas-dd.iter.org/mcp\" }\n }\n}\n```\n\n#### Claude Desktop config\n\nPick path for your OS:\n\nWindows: `%APPDATA%\\\\Claude\\\\claude_desktop_config.json` \nmacOS: `~/Library/Application Support/Claude/claude_desktop_config.json` \nLinux: `~/.config/claude/claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"imas-mcp-hosted\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"https://imas-dd.iter.org/mcp\"]\n }\n }\n}\n```\n\n#### OP Client (Pending Clarification)\n\nPlaceholder: clarify what \"op\" refers to (e.g. OpenAI, Operator) to add tailored instructions.\n\n### UV Local Install\n\nInstall with [uv](https://docs.astral.sh/uv/):\n\n```bash\nuv tool install imas-mcp\n# or add to a project env\nuv add imas-mcp\n```\n\nVS Code:\n\n```json\n{\n \"servers\": {\n \"imas-mcp-uv\": {\n \"type\": \"stdio\",\n \"command\": \"uv\",\n \"args\": [\"run\", \"--active\", \"imas-mcp\", \"--no-rich\"]\n }\n }\n}\n```\n\nClaude Desktop:\n\n```json\n{\n \"mcpServers\": {\n \"imas-mcp-uv\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--active\", \"imas-mcp\", \"--no-rich\"]\n }\n }\n}\n```\n\n### Docker Setup\n\nRun locally in a container (pre-built indexes included):\n\n```bash\ndocker run -d \\\n --name imas-mcp \\\n -p 8000:8000 \\\n ghcr.io/iterorganization/imas-mcp:latest-streamable-http\n\n# Optional: verify\ndocker ps --filter name=imas-mcp --format \"table {{.Names}}\\t{{.Status}}\"\n```\n\nVS Code (`.vscode/mcp.json`):\n\n```json\n{\n \"servers\": {\n \"imas-mcp-docker\": { \"type\": \"http\", \"url\": \"http://localhost:8000/mcp\" }\n }\n}\n```\n\nClaude Desktop:\n\n```json\n{\n \"mcpServers\": {\n \"imas-mcp-docker\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"http://localhost:8000/mcp\"]\n }\n }\n}\n```\n\n### Slurm / HPC (STDIO)\n\nHelper script: `scripts/imas_mcp_slurm_stdio.sh`\n\nVS Code (`.vscode/mcp.json`, JSONC ok):\n\n```jsonc\n{\n \"servers\": {\n \"imas-slurm-stdio\": {\n \"type\": \"stdio\",\n \"command\": \"scripts/imas_mcp_slurm_stdio.sh\"\n }\n }\n}\n```\n\nLaunch behavior:\n\n1. If `SLURM_JOB_ID` present \u2192 start inside current allocation.\n2. Else requests node with `srun --pty` then starts server (unbuffered stdio).\n\nResource tuning (export before client starts):\n\n| Variable | Purpose | Default |\n| -------------------------- | ---------------------------------------- | --------------- |\n| `IMAS_MCP_SLURM_TIME` | Walltime | `08:00:00` |\n| `IMAS_MCP_SLURM_CPUS` | CPUs per task | `1` |\n| `IMAS_MCP_SLURM_MEM` | Memory (e.g. `4G`) | Slurm default |\n| `IMAS_MCP_SLURM_PARTITION` | Partition | Cluster default |\n| `IMAS_MCP_SLURM_ACCOUNT` | Account/project | User default |\n| `IMAS_MCP_SLURM_EXTRA` | Extra raw `srun` flags | (empty) |\n| `IMAS_MCP_USE_ENTRYPOINT` | Use `imas-mcp` entrypoint vs `python -m` | `0` |\n\nExample:\n\n```bash\nexport IMAS_MCP_SLURM_TIME=02:00:00\nexport IMAS_MCP_SLURM_CPUS=4\nexport IMAS_MCP_SLURM_MEM=8G\nexport IMAS_MCP_SLURM_PARTITION=compute\n```\n\nDirect CLI:\n\n```bash\nscripts/imas_mcp_slurm_stdio.sh --ids-filter \"core_profiles equilibrium\"\n```\n\nWhy STDIO? Avoids opening network ports; all traffic rides the existing `srun` pseudo-TTY.\n\n---\n\n## Example IMAS Queries\n\nOnce you have the IMAS MCP server configured, you can interact with it using natural language queries. Use the `@imas` prefix to direct queries to the IMAS server:\n\n### Basic Search Examples\n\n```text\n@imas Find data paths related to plasma temperature\n@imas Search for electron density measurements\n@imas What data is available for magnetic field analysis?\n@imas Show me core plasma profiles\n```\n\n### Physics Concept Exploration\n\n```text\n@imas Explain what equilibrium reconstruction means in plasma physics\n@imas What is the relationship between pressure and magnetic fields?\n@imas How do transport coefficients relate to plasma confinement?\n@imas Describe the physics behind current drive mechanisms\n```\n\n### Data Structure Analysis\n\n```text\n@imas Analyze the structure of the core_profiles IDS\n@imas What are the relationships between equilibrium and core_profiles?\n@imas Show me identifier schemas for transport data\n@imas Export bulk data for equilibrium, core_profiles, and transport IDS\n```\n\n### Advanced Queries\n\n```text\n@imas Find all paths containing temperature measurements across different IDS\n@imas What physics domains are covered in the IMAS data dictionary?\n@imas Show me measurement dependencies for fusion power calculations\n@imas Explore cross-domain relationships between heating and confinement\n```\n\n### Workflow and Integration\n\n```text\n@imas How do I access electron temperature profiles from IMAS data?\n@imas What's the recommended workflow for equilibrium analysis?\n@imas Show me the branching logic for diagnostic identifier schemas\n@imas Export physics domain data for comprehensive transport analysis\n```\n\nThe IMAS MCP server provides 8 specialized tools for different types of queries:\n\n- **Search**: Natural language and structured search across IMAS data paths\n- **Explain**: Physics concepts with IMAS context and domain expertise\n- **Overview**: General information about IMAS structure and available data\n- **Analyze**: Detailed structural analysis of specific IDS\n- **Explore**: Relationship discovery between data paths and physics domains\n- **Identifiers**: Exploration of enumerated options and branching logic\n- **Bulk Export**: Comprehensive export of multiple IDS with relationships\n- **Domain Export**: Physics domain-specific data with measurement dependencies\n\n## Development\n\nFor local development and customization:\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/iterorganization/imas-mcp.git\ncd imas-mcp\n\n# Install development dependencies (search index build takes ~8 minutes first time)\nuv sync --all-extras\n```\n\n### Build Dependencies\n\nThis project requires additional dependencies during the build process that are not part of the runtime dependencies:\n\n- **`imas-data-dictionary`** - Git development package, required only during wheel building for parsing latest DD changes\n- **`rich`** - Used for enhanced console output during build processes\n\n**For runtime:** The `imas-data-dictionaries` PyPI package is now a core dependency and provides access to stable DD versions (e.g., 4.0.0). This eliminates the need for the git package at runtime and ensures reproducible builds.\n\n**For developers:** Build-time dependencies are included in the `[build-system.requires]` section for wheel building. The git package is only needed when building wheels with latest DD changes.\n\n```bash\n# Regular development - uses imas-data-dictionaries (PyPI)\nuv sync --all-extras\n\n# Set DD version for building (defaults to 4.0.0)\nexport IMAS_DD_VERSION=4.0.0\nuv run build-schemas\n```\n\n**Location in configuration:**\n\n- **Build-time dependencies**: Listed in `[build-system.requires]` in `pyproject.toml`\n- **Runtime dependencies**: `imas-data-dictionaries>=4.0.0` in `[project.dependencies]`\n\n**Note:** The `IMAS_DD_VERSION` environment variable controls which DD version is used for building schemas and embeddings. Docker containers have this set to `4.0.0` by default.\n\n### Development Commands\n\n```bash\n# Run tests\nuv run pytest\n\n# Run linting and formatting\nuv run ruff check .\nuv run ruff format .\n\n# Build schema data structures from IMAS data dictionary\nuv run build-schemas\n\n# Build document store and semantic search embeddings\nuv run build-embeddings\n\n# Run the server locally (default: streamable-http on port 8000)\nuv run --active imas-mcp --no-rich\n\n# Run with stdio transport for MCP clients\nuv run --active imas-mcp --no-rich --transport stdio\n```\n\n### Build Scripts\n\nThe project includes two separate build scripts for creating the required data structures:\n\n**`build-schemas`** - Creates schema data structures from IMAS XML data dictionary:\n\n- Transforms XML data into optimized JSON format\n- Creates catalog and relationship files\n- Use `--ids-filter \"core_profiles equilibrium\"` to build specific IDS\n- Use `--force` to rebuild even if files exist\n\n**`build-embeddings`** - Creates document store and semantic search embeddings:\n\n- Builds in-memory document store from JSON data\n- Generates sentence transformer embeddings for semantic search\n- Caches embeddings for fast loading\n- Use `--model-name \"all-mpnet-base-v2\"` for different models\n- Use `--force` to rebuild embeddings cache\n- Use `--no-normalize` to disable embedding normalization\n- Use `--half-precision` to reduce memory usage\n- Use `--similarity-threshold 0.1` to set similarity score thresholds\n\n**Note:** The build hook creates JSON data. Build embeddings separately using `build-embeddings` for better control and performance.\n\n### Local Development MCP Configuration\n\n#### VS Code\n\nThe repository includes a `.vscode/mcp.json` file with pre-configured development server options. Use the `imas-local-stdio` configuration for local development.\n\n#### Claude Desktop\n\nAdd to your config file:\n\n```json\n{\n \"mcpServers\": {\n \"imas-local-dev\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--active\", \"imas-mcp\", \"--no-rich\", \"--auto-build\"],\n \"cwd\": \"/path/to/imas-mcp\"\n }\n }\n}\n```\n\n## How It Works\n\n1. **Installation**: During package installation, the index builds automatically when the module first imports\n2. **Build Process**: The system parses the IMAS data dictionary and creates comprehensive JSON files with structured data\n3. **Embedding Generation**: Creates semantic embeddings using sentence transformers for advanced search capabilities\n4. **Serialization**: The system stores indexes in organized subdirectories:\n - **JSON data**: `imas_mcp/resources/schemas/` (LLM-optimized structured data)\n - **Embeddings cache**: Pre-computed sentence transformer embeddings for semantic search\n5. **Import**: When importing the module, the pre-built index and embeddings load in ~1 second\n\n## Optional Dependencies and Runtime Requirements\n\nThe IMAS MCP server now includes `imas-data-dictionaries` as a core dependency, providing stable DD version access (default: 4.0.0). The git development package (`imas-data-dictionary`) is used during wheel building when parsing latest DD changes.\n\n### Package Installation Options\n\n- **Runtime**: `uv add imas-mcp` - Includes all transports (stdio, sse, streamable-http)\n- **Full installation**: `uv add imas-mcp` - Recommended for all users\n\n### Data Dictionary Access\n\nThe system uses composable accessors to access IMAS Data Dictionary version and metadata:\n\n1. **Environment Variable**: `IMAS_DD_VERSION` (highest priority) - Set to specify DD version (e.g., \"4.0.0\")\n2. **Metadata File**: JSON metadata stored alongside indexes\n3. **Index Name Parsing**: Extracts version from index filename\n4. **Package Default**: Falls back to `imas-data-dictionaries` package (4.0.0)\n\nThis design ensures the server can:\n\n- **Build indexes** using the version specified by `IMAS_DD_VERSION`\n- **Run with pre-built indexes** using version metadata\n- **Access stable DD versions** through `imas-data-dictionaries` PyPI package\n\n### Index Building vs Runtime\n\n- **Index Building**: Requires `imas-data-dictionary` package to parse XML and create indexes\n- **Runtime Search**: Only requires pre-built indexes and metadata, no IMAS package dependency\n- **Version Access**: Uses composable accessor pattern with multiple fallback strategies\n\n## Implementation Details\n\n### Search Implementation\n\nThe search system is the core component that provides fast, flexible search capabilities over the IMAS Data Dictionary. It combines efficient indexing with IMAS-specific data processing and semantic search to enable different search modes:\n\n#### Search Methods\n\n1. **Semantic Search** (`SearchMode.SEMANTIC`):\n\n - AI-powered semantic understanding using sentence transformers\n - Natural language queries with physics context awareness\n - Finds conceptually related terms even without exact keyword matches\n - Best for exploratory research and concept discovery\n\n2. **Lexical Search** (`SearchMode.LEXICAL`):\n\n - Fast text-based search with exact keyword matching\n - Boolean operators (`AND`, `OR`, `NOT`)\n - Wildcards (`*` and `?` patterns)\n - Field-specific searches (e.g., `documentation:plasma ids:core_profiles`)\n - Fastest performance for known terminology\n\n3. **Hybrid Search** (`SearchMode.HYBRID`):\n\n - Combines semantic and lexical approaches\n - Provides both exact matches and conceptual relevance\n - Balanced performance and comprehensiveness\n\n4. **Auto Search** (`SearchMode.AUTO`):\n - Intelligent search mode selection based on query characteristics\n - Automatically chooses optimal search strategy\n - Adaptive performance optimization\n\n#### Key Capabilities\n\n- **Search Mode Selection**: Choose between semantic, lexical, hybrid, or auto modes\n- **Performance Caching**: TTL-based caching system with hit rate monitoring\n- **Semantic Embeddings**: Pre-computed sentence transformer embeddings for fast semantic search\n- **Physics Context**: Domain-aware search with IMAS-specific terminology\n- **Advanced Query Parsing**: Supports complex search expressions and field filtering\n- **Relevance Ranking**: Results sorted by match quality and physics relevance\n\n## Future Work\n\n### MCP Resources Implementation (Phase 2 - Planned)\n\nWe plan to implement MCP resources to provide efficient access to pre-computed IMAS data:\n\n#### Planned Resource Features\n\n- **Static JSON IDS Data**: Pre-computed IDS catalog and structure data served as MCP resources\n- **Physics Measurement Data**: Domain-specific measurement data and relationships\n- **Usage Examples**: Code examples and workflow patterns for common analysis tasks\n- **Documentation Resources**: Interactive documentation and API references\n\n#### Resource Types\n\n- `ids://catalog` - Complete IDS catalog with metadata\n- `ids://structure/{ids_name}` - Detailed structure for specific IDS\n- `ids://physics-domains` - Physics domain mappings and relationships\n- `examples://search-patterns` - Common search patterns and workflows\n\n### MCP Prompts Implementation (Phase 3 - Planned)\n\nSpecialized prompts for physics analysis and workflow automation:\n\n#### Planned Prompt Categories\n\n- **Physics Analysis Prompts**: Specialized prompts for plasma physics analysis tasks\n- **Code Generation Prompts**: Generate Python analysis code for IMAS data\n- **Workflow Automation Prompts**: Automate complex multi-step analysis workflows\n- **Data Validation Prompts**: Create validation approaches for IMAS measurements\n\n#### Prompt Templates\n\n- `physics-explain` - Generate comprehensive physics explanations\n- `measurement-workflow` - Create measurement analysis workflows\n- `cross-ids-analysis` - Analyze relationships between multiple IDS\n- `imas-python-code` - Generate Python code for data analysis\n\n### Performance Optimization (Phase 4 - In Progress)\n\nContinued optimization of search and tool performance:\n\n#### Current Optimizations (Implemented)\n\n- \u2705 **Search Mode Selection**: Multiple search modes (semantic, lexical, hybrid, auto)\n- \u2705 **Search Caching**: TTL-based caching with hit rate monitoring for search operations\n- \u2705 **Semantic Embeddings**: Pre-computed sentence transformer embeddings\n- \u2705 **ASV Benchmarking**: Automated performance monitoring and regression detection\n\n#### Planned Optimizations\n\n- **Advanced Caching Strategy**: Intelligent cache management for all MCP operations (beyond search)\n- **Performance Monitoring**: Enhanced metrics tracking and analysis across all tools\n- **Multi-Format Export**: Optimized export formats (raw, structured, enhanced)\n- **Selective AI Enhancement**: Conditional AI enhancement based on request context\n\n### Testing and Quality Assurance (Phase 5 - Planned)\n\nComprehensive testing strategy for all MCP components:\n\n#### Test Implementation Goals\n\n- **MCP Tool Testing**: Complete test coverage using FastMCP 2 testing framework\n- **Resource Testing**: Validation of all MCP resources and data integrity\n- **Prompt Testing**: Automated testing of prompt templates and responses\n- **Performance Testing**: Benchmarking and regression detection for all tools\n\n## Docker Usage\n\nThe server is available as a pre-built Docker container with the index already built:\n\n```bash\n# Pull and run the latest container\ndocker run -d -p 8000:8000 ghcr.io/iterorganization/imas-mcp:latest\n\n# Or use Docker Compose\ndocker-compose up -d\n```\n\nSee [DOCKER.md](DOCKER.md) for detailed container usage, deployment options, and troubleshooting.\n\n[python-badge]: https://img.shields.io/badge/python-3.12-blue\n[python-link]: https://www.python.org/downloads/\n[ruff-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json\n[ruff-link]: https://docs.astral.sh/ruff/\n[pre-commit-badge]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white\n[pre-commit-link]: https://github.com/pre-commit/pre-commit\n[build-deploy-badge]: https://img.shields.io/github/actions/workflow/status/simon-mcintosh/imas-mcp/test.yml?branch=main&color=brightgreen&label=CI%2FCD\n[build-deploy-link]: https://github.com/iterorganization/imas-mcp/actions/workflows/test.yml\n[codecov-badge]: https://codecov.io/gh/simon-mcintosh/imas-mcp/graph/badge.svg\n[codecov-link]: https://codecov.io/gh/simon-mcintosh/imas-mcp\n[docs-badge]: https://img.shields.io/badge/docs-online-brightgreen\n[docs-link]: https://simon-mcintosh.github.io/imas-mcp/\n[asv-badge]: https://img.shields.io/badge/ASV-Benchmarks-blue?style=flat&logo=speedtest&logoColor=white\n[asv-link]: https://simon-mcintosh.github.io/imas-mcp/benchmarks/\n",
"bugtrack_url": null,
"license": "CC BY-ND 4.0",
"summary": "An IMAS Data Dictionary MCP server",
"version": "3.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/iterorganization/imas-mcp/issues",
"Documentation": "https://github.com/iterorganization/imas-mcp#readme",
"Homepage": "https://github.com/iterorganization/imas-mcp",
"Repository": "https://github.com/iterorganization/imas-mcp"
},
"split_keywords": [
"data dictionary",
" fusion",
" imas",
" iter",
" mcp",
" model context protocol",
" plasma physics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dafcc5d01ffa5c7c4787f0c02306e267953b52cd3709368f0ea74abfbe7b7f9b",
"md5": "07028ab9f4e4d8939eb3d88d546fd9e4",
"sha256": "e91f1a8dceda6a7e0e69c6fb2462938b96bd7627627fce8cc9593109165b7624"
},
"downloads": -1,
"filename": "imas_mcp-3.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "07028ab9f4e4d8939eb3d88d546fd9e4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.12",
"size": 1561097,
"upload_time": "2025-10-28T06:31:30",
"upload_time_iso_8601": "2025-10-28T06:31:30.200474Z",
"url": "https://files.pythonhosted.org/packages/da/fc/c5d01ffa5c7c4787f0c02306e267953b52cd3709368f0ea74abfbe7b7f9b/imas_mcp-3.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f212e92fe8276daaeb091d25b4f9ac7bd0653efee7cd5ea5dc629c6a3f061bf1",
"md5": "e1b4b7ca6e277d5f5873aa0c39269bbb",
"sha256": "0290e69c9e2aa8e696885df4062683b58ff928bc3254dd826f8926b877927ae1"
},
"downloads": -1,
"filename": "imas_mcp-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e1b4b7ca6e277d5f5873aa0c39269bbb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.12",
"size": 439995,
"upload_time": "2025-10-28T06:31:32",
"upload_time_iso_8601": "2025-10-28T06:31:32.156035Z",
"url": "https://files.pythonhosted.org/packages/f2/12/e92fe8276daaeb091d25b4f9ac7bd0653efee7cd5ea5dc629c6a3f061bf1/imas_mcp-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 06:31:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iterorganization",
"github_project": "imas-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "imas-mcp"
}
JSON
