grayscale-mcp

GRAYSCALE MCP Server

A Model Context Protocol (MCP) server for optimizing Electron Cyclotron (EC) heating and Electron Cyclotron Current Drive (ECCD) configurations in fusion plasmas. Specifically designed for ITER scenarios with physics-based models and constraints.

Overview

This MCP server provides intelligent tools for:

• EC Configuration Optimization: Find optimal heating and current drive parameters
• Physics Validation: Ensure configurations meet ITER-relevant constraints
• Scenario Analysis: Access and analyze baseline ITER scenarios
• Parameter Sensitivity: Understand robustness and dependencies

Perfect for fusion researchers, plasma physicists, and anyone working with ITER heating systems.

Features

• 🎯 Scenario Recommendation - Get optimal EC configurations for specific physics goals
• ✅ Parameter Validation - Validate configurations against physics constraints
• 📊 Sensitivity Analysis - Analyze parameter dependencies and robustness
• ⚡ Configuration Optimization - Find optimal configurations for specific objectives
• 📚 Scenario Database - Access to ITER baseline scenarios
• 🔬 Physics Models - ECCD current scaling laws and ITER-relevant constraints

Installation

Option 1: Using pip (Recommended for MCP Clients)

Install the package to get the grayscale-mcp command:

pip install grayscale-mcp

Option 2: Using uv (Recommended for Development)

Install with uv for faster dependency management:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/prasad-sawantdesai/grayscale-mcp.git
cd grayscale-mcp
uv sync

Option 3: From Source

git clone https://github.com/prasad-sawantdesai/grayscale-mcp.git
cd grayscale-mcp
pip install -e .

Quick Start

For VS Code

Add this to your .vscode/mcp.json:

If installed via pip:

{
  "servers": {
    "grayscale_mcp": {
      "type": "stdio",
      "command": "grayscale-mcp"
    }
  }
}

If using uv (from cloned repo):

{
  "servers": {
    "grayscale_mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/grayscale-mcp", "-m", "grayscale_mcp"]
    }
  }
}

For Claude Desktop

Add to your claude_desktop_config.json:

If installed via pip:

{
  "mcpServers": {
    "grayscale_mcp": {
      "command": "grayscale-mcp"
    }
  }
}

If using uv:

{
  "mcpServers": {
    "grayscale_mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/grayscale-mcp", "-m", "grayscale_mcp"]
    }
  }
}

Example Prompts

Once configured, try these with your MCP client:

• "Recommend an EC configuration for MHD stability with 10 MW power budget"
• "Validate these EC parameters: power=8.5MW, location=0.5, sigma=0.15, prefactor=9.8"
• "Search scenarios for rotation control"
• "Show me the physics constraints for EC configuration"
• "Optimize EC configuration for maximum current drive at ρ=0.4"

Usage

Running the Server

With pip installation:

grayscale-mcp

With uv:

uv run -m grayscale_mcp

The server communicates via JSON-RPC over stdin/stdout and is designed to be used with MCP-compatible clients.

Available Tools

Tool	Description	Example Use Case
recommend_scenario	Get optimal EC configuration for a physics goal	"Recommend EC for off-axis current drive"
validate_parameters	Validate EC configuration against physics constraints	"Check if 12 MW at ρ=0.3 is valid"
search_scenarios	Search scenario database by criteria	"Find scenarios with rotation control"
sensitivity_analysis	Analyze how parameters affect outcomes	"How sensitive is current drive to location?"
optimize_config	Optimize configuration for specific objectives	"Maximize ECCD efficiency at ρ=0.5"
get_scenario_database	Access full ITER scenario database	"Show all available scenarios"
get_physics_constraints	Get physics constraint limits	"What are the power limits?"

Available Resources

Access specific data via MCP resources:

• grayscale://scenario/{scenario_name} - Get details for a specific scenario
• grayscale://constraints - Get all physics constraints and limits

Testing the Server

Manual Testing with MCP Inspector

The FastMCP library provides an inspector for testing:

# Install fastmcp if not already installed
pip install fastmcp

# Run the inspector
mcp dev grayscale-mcp

This will open a web interface where you can test the MCP tools interactively.

Testing via Python Script

You can also test the server functionality directly in Python:

from grayscale_mcp.server import GrayscaleServer

# Create server instance
server = GrayscaleServer()

# Get scenario recommendations
result = server.recommend_scenario(
    scenario_type="hybrid",
    physics_goal="current_drive",
    power_budget=10e6
)
print(result)

# Validate parameters
is_valid, warnings = server.validate_parameters({
    "ec_power": 8.5e6,
    "ec_gauss_location": 0.5,
    "ec_gauss_sigma": 0.15,
    "eccd_prefactor": 9.8
})
print(f"Valid: {is_valid}, Warnings: {warnings}")

# Search scenarios
results = server.search_scenarios(goal="current_drive")
print(results)

Physics Models

The server implements established fusion physics models:

ECCD Current Drive

Uses Gaussians for the EC heat deposition and ECCD profiles with prescribed deposited EC power, EC peak location and width. The ECCD profile is calculated in accordance with a GRAY-based scaling that has been derived by A. Polevoi.

Key features:

• Accounts for plasma parameters (density, temperature)
• Location-dependent efficiency
• Power and configuration optimization

Physics Constraints

ITER-relevant parameter bounds:

• Power: 0.1 - 20.0 MW
• Deposition Location (ρ): 0.0 - 1.0 (normalized radius)
• Deposition Width (σ): 0.05 - 0.3
• Geometry Factor: 5.0 - 12.0

Scenario Database

Curated ITER baseline scenarios:

• Hybrid scenarios
• Advanced tokamak modes
• MHD stability control
• Rotation control configurations

Development

Setting Up Development Environment

Using uv (recommended):

git clone https://github.com/prasad-sawantdesai/grayscale-mcp.git
cd grayscale-mcp
uv sync

Using pip:

git clone https://github.com/prasad-sawantdesai/grayscale-mcp.git
cd grayscale-mcp
pip install -e ".[dev]"

Running Tests

# With uv
uv run pytest tests/

# With pip
pytest tests/

# With coverage
uv run pytest tests/ --cov=grayscale_mcp --cov-report=html

Code Quality

Formatting:

uv run black grayscale_mcp/
uv run ruff check grayscale_mcp/

Type Checking:

uv run mypy grayscale_mcp/

Troubleshooting

Common Issues

"Command not found: grayscale-mcp"

• Make sure you've installed via pip: pip install grayscale-mcp
• Check that your Python scripts directory is in PATH

"Module not found" errors with uv

• Run uv sync to install dependencies
• Make sure you're in the correct directory

MCP client doesn't connect

• Verify the configuration file path is correct
• Check that the command path is absolute (for uv installations)
• Look at the MCP client logs for error messages

Physics validation failures

• Check parameter ranges in get_physics_constraints
• Ensure power is in MW, not W
• Location (ρ) should be normalized (0-1)

Getting Help

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Acknowledgments

• Built on the Model Context Protocol
• Physics models based on ITER research
• Inspired by fusion plasma optimization needs

References

C. Zucca et al., "Safety‐factor profile tailoring by improved electron cyclotron system for sawtooth control and reverse shear scenarios in ITER"
AIP Conference Proceedings 1069, 361 (2008)
https://doi.org/10.1063/1.3033728

D. Farina, "A Quasi-Optical Beam-Tracing Code for Electron Cyclotron Absorption and Current Drive: GRAY"
Fusion Sci. Technol. 52 154 (2007)
https://doi.org/10.13182/FST07-A1494

---