Imas MCP Server

IMAS Codex服务器

  ](https://www.python.org/downloads/)    

模型上下文协议（MCP）服务器，通过自然语言搜索和优化路径索引为AI助手提供对IMAS（集成建模与分析套件）数据结构的访问。

MCP服务器

IMAS Codex提供了一个统一的MCP服务器：

imas-codex serve

该单一服务器提供IMAS数据字典知识、语义搜索和远程设施探索。

只读模式： 使用 --read-only 抑制写工具（Python REPL、图突变）——非常适合容器和公共部署：

# Read-only mode (for container deployments)
imas-codex serve --read-only --transport streamable-http

快速开始

选择与您的环境相匹配的设置方法：

• HTTP（托管）：零安装。连接到运行ITER组织最新标记的MCP服务器的公共端点。
• UV（本地）：在您自己的Python环境中安装并运行，以进行可编辑开发。
• Docker：运行一个带有预构建索引的隔离容器。
• Slurm/HPC（STDIO）：在集群分配内启动，不打开网络端口。

选择托管以实现即时访问；为自定义或受控资源选择本地选项。

HTTP（远程公共端点）

连接到公共ITER组织托管的服务器——无需本地安装。

VS代码（交互式）

1. Ctrl+Shift+P → “MCP:添加服务器”
2. 选择“HTTP服务器”
3. 姓名： imas
4. 网址： https://imas-dd.iter.org/mcp

VS代码（手动JSON）

工作区 .vscode/mcp.json （或内部 "mcp" 在用户设置中）：

{
  "servers": {
    "imas": { "type": "http", "url": "https://imas-dd.iter.org/mcp" }
  }
}

Claude桌面配置

为您的操作系统选择路径：

窗户： %APPDATA%\\Claude\\claude_desktop_config.json\ macOS： ~/Library/Application Support/Claude/claude_desktop_config.json\ Linux： ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "imas-codex-hosted": {
      "command": "npx",
      "args": ["mcp-remote", "https://imas-dd.iter.org/mcp"]
    }
  }
}

OP客户（待澄清）

占位符：澄清“op”指的是什么（例如OpenAI、Operator），以添加定制指令。

UV本地安装

安装时使用 紫外线:

# Standard installation (includes sentence-transformers)
uv tool install imas-codex

# Add to a project env
uv add imas-codex

数据字典版本

IMAS数据字典版本决定了使用哪些模式定义。版本按优先级顺序解析：

配置：

在中设置默认DD版本 pyproject.toml:

[tool.imas-codex.data-dictionary]
version = "4.1.0"

运行时覆盖：

# Via CLI option
imas-codex --dd-version 3.42.2

# Via environment variable
IMAS_DD_VERSION=3.42.2 imas-codex

# Docker build
docker build --build-arg IMAS_DD_VERSION=3.42.2 ...

版本验证：

服务器验证请求的DD版本是否不超过已安装的可用最大版本 imas-data-dictionaries 包裹。如果您请求的版本不可用，您将看到：

ValueError: Requested DD version 5.0.0 exceeds maximum available version 4.1.0.
Update imas-data-dictionaries dependency or use a lower version.

嵌入配置

IMAS Codex服务器使用Qwen3-Embedded-8B生成256个暗嵌入：

配置：

嵌入模型在中配置 pyproject.toml 在...之下 [tool.imas-codex]:

[tool.imas-codex]
imas-embedding-model = "Qwen/Qwen3-Embedding-8B"
embedding-dimensions = 256

环境变量覆盖pyproject.toml设置：

export IMAS_CODEX_EMBEDDING_MODEL="Qwen/Qwen3-Embedding-8B"

路径包含设置：

控制哪些IMAS路径被索引和搜索。这些设置会影响模式生成、嵌入和语义搜索：

pyproject.toml配置示例：

[tool.imas-codex]
include-ggd = true
include-error-fields = false

环境变量覆盖：

export IMAS_CODEX_INCLUDE_GGD=false     # Exclude GGD paths
export IMAS_CODEX_INCLUDE_ERROR_FIELDS=true  # Include error fields

错误处理：

如果模型加载失败，则会引发一个错误，其中包含模型名称和原因。

VS代码(.vscode/mcp.json):

{
  "servers": {
    "imas-codex-uv": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "imas-codex", "serve", "--transport", "stdio"]
    }
  }
}

克劳德桌面：

{
  "mcpServers": {
    "imas-codex-uv": {
      "command": "uv",
      "args": ["run", "imas-codex", "serve", "--transport", "stdio"]
    }
  }
}

SSH控制主机设置（推荐）

对于设施探索期间快速重复的SSH连接，请配置SSH ControlMaster。这使连接保持活跃，将后续命令的延迟从约1-2秒减少到约100毫秒。

# Create socket directory
mkdir -p ~/.ssh/sockets
chmod 700 ~/.ssh/sockets

增添 ~/.ssh/config:

# EPFL / Swiss Plasma Center
Host tcv
    HostName spcepfl.epfl.ch
    User your_username
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600

# Add other facilities as needed
Host ipp
    HostName gateway.ipp.mpg.de
    User your_username
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600

它是如何工作的：

• 第一次连接：~1-2秒（建立主连接）
• 后续连接：~100ms（重用现有套接字）
• ControlPersist 600：上次使用后保持连接10分钟

验证设置：

# Check if master connection is active
ssh -O check tcv

# Manually close master connection
ssh -O exit tcv

设施勘探指挥部

配置SSH后，直接从终端浏览设施：

# Execute commands on remote facility
uv run imas-codex tcv "python --version"
uv run imas-codex tcv "ls /common/tcv/codes"

# View session history
uv run imas-codex tcv --status

# Persist learnings when done
uv run imas-codex tcv --finish  MATCH (n:FacilityPath) RETURN n.facility_id, count(n)

仅IMAS图

对于没有特定设施数据的IMAS数据字典访问：

pip install imas-codex
imas-codex graph init imas
imas-codex graph pull --dd-only
imas-codex serve

这将绘制一个仅包含IMAS数据字典模式、路径和语义集群的轻量级图。使用 --registry ghcr.io/ 从特定注册表中提取。

位置感知连接

这 host 每个配置文件上的字段记录了Neo4j物理运行的位置。在连接时， is_local_host(host) 确定直接通道与隧道通道：

• ITER: resolve_neo4j("iter") 检测本地计算机→ bolt://localhost:7687 （直接）
• 关于WSL: resolve_neo4j("iter") 检测远程主机→ 使用SSH隧道→ bolt://localhost:7687

对于双实例设置（本地+隧道），在中设置隧道端口覆盖 .env:

IMAS_CODEX_TUNNEL_BOLT_ITER=17687
# Then: ssh -f -N -L 17687:localhost:7687 iter

ssh隧道

# Start tunnel to remote graph (reads profile host/port)
imas-codex graph tunnel start iter

# With custom local port (for dual-instance)
imas-codex graph tunnel start iter --local-bolt-port 17687

# Show active tunnels
imas-codex graph tunnel status

# Stop tunnel
imas-codex graph tunnel stop iter

备份和恢复

# Create a neo4j-admin dump backup
imas-codex graph backup

# Restore from backup (interactive selection)
imas-codex graph restore

# Restore specific file
imas-codex graph restore ~/.local/share/imas-codex/backups/iter-20260213.dump

# Clear graph (auto-backup first)
imas-codex graph clear

GHCR注册

# Push (requires GHCR_TOKEN with write:packages scope)
imas-codex graph push              # Release push (requires git tag)
imas-codex graph push --dev        # Dev push (auto-increments revision)
imas-codex graph push --facility tcv --dev  # Per-facility push

# Pull
imas-codex graph pull              # Pull latest unified graph
imas-codex graph pull --facility tcv  # Pull per-facility graph

# List and cleanup
imas-codex graph tags              # List available versions
imas-codex graph prune --dev      # Remove all dev tags
imas-codex graph prune --backups --older-than 30d  # Clean old backups

每个设施联合会

完整图表包含所有设施。通过转储和清理提取每个设施的图表：

# Dump filtered to a single facility (keeps IMAS DD nodes)
imas-codex graph export --facility tcv

# Push to per-facility GHCR package
imas-codex graph push --facility tcv --dev

这创造了 ghcr.io/iterorganization/imas-codex-graph-tcv 仅包含TCV数据和共享的IMAS数据字典。

发布工作流

发布CLI实现了一个双态机器（稳定↔ RC模式） 语义版本控制与图形数据发布。

# Check current release state and permitted commands
imas-codex release status

# Start a major release candidate
imas-codex release --bump major -m "IMAS DD 4.1.0 support"

# Iterate on the RC after fixes
imas-codex release -m "Fix signal mapping edge case"

# Finalize: promote RC to stable release
imas-codex release --final -m "Production release"

# Abandon current RC, start a different bump level
imas-codex release --bump minor -m "New approach"

# Direct release (skip RC)
imas-codex release --bump patch --final -m "Hotfix"

# Preview without executing
imas-codex release --bump major --dry-run -m "Test"

释放管道：

1. 从最新的git标签（状态机）计算下一个版本
2. 验证图形数据是否不包含私有字段
3. 使用发布元数据标记DDVersion节点
4. 将所有图形变体（仅dd、完整、每个设施）推送到GHCR
5. 创建并推送git标签（触发CI构建）

图形包变体：

设置： 集 GHCR_TOKEN 和 write:packages 范围。添加上游远程： git remote add upstream https://github.com/iterorganization/imas-codex.git

Docker Compose

# Default ports (iter convention: bolt=7687, http=7474)
docker compose --profile graph up

# Custom ports for another facility
BOLT_PORT=7688 HTTP_PORT=7475 docker compose --profile graph up

发展

对于本地开发和定制：

设置

# Clone repository
git clone https://github.com/iterorganization/imas-codex.git
cd imas-codex

# Install development dependencies (search index build takes ~8 minutes first time)
uv sync --all-extras

建立依赖关系

此项目在构建过程中需要其他不属于运行时依赖项的依赖项：

• imas-data-dictionary -Git开发包，仅在构建轮子时需要，用于解析最新的DD更改
• rich -用于在构建过程中增强控制台输出

对于运行时： 这 imas-data-dictionaries PyPI包现在是一个核心依赖项，可以访问稳定的DD版本（例如4.0.0）。这消除了在运行时对git包的需求，并确保了可重复的构建。

对于开发者： 构建时依赖关系包含在 [build-system.requires] 车轮制造部分。仅在构建具有最新DD更改的车轮时才需要git包。

# 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

配置中的位置：

• 构建时间依赖关系：列在 [build-system.requires] 在 pyproject.toml
• 运行时依赖关系: imas-data-dictionaries>=4.0.0 在 [project.dependencies]

注： 这 IMAS_DD_VERSION 环境变量控制哪个DD版本用于构建模式和嵌入。Docker容器将此设置为 4.0.0 默认情况下。

开发命令

# 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 imas-codex serve

# Run with stdio transport for MCP clients
uv run imas-codex serve --transport stdio

# Read-only mode (suppresses write tools and Python REPL)
uv run imas-codex serve --read-only

生成脚本

该项目包括两个单独的构建脚本，用于创建所需的数据结构：

build-schemas -从IMAS XML数据字典创建模式数据结构：

• 将XML数据转换为优化的JSON格式
• 创建目录和关系文件
• 使用 --ids-filter "core_profiles equilibrium" 构建特定的IDS
• 使用 --force 即使文件存在，也要进行重建

build-embeddings -创建文档存储和语义搜索嵌入：

• 从JSON数据构建内存中的文档存储
• 生成用于语义搜索的句子变换器嵌入
• 缓存嵌入以实现快速加载
• 使用 --model-name "all-mpnet-base-v2" 适用于不同型号
• 使用 --force 重建嵌入缓存
• 使用 --no-normalize 禁用嵌入规范化
• 使用 --half-precision 减少内存使用
• 使用 --similarity-threshold 0.1 设置相似性得分阈值

注： 构建钩子创建JSON数据。使用单独构建嵌入 build-embeddings 以获得更好的控制和性能。

本地开发MCP配置

VS代码

存储库包括 .vscode/mcp.json 带有预先配置的开发服务器选项的文件。使用 imas-local-stdio 当地发展的配置。

克劳德桌面版

添加到您的配置文件中：

{
  "mcpServers": {
    "imas-local-dev": {
      "command": "uv",
      "args": ["run", "imas-codex", "serve", "--transport", "stdio"],
      "cwd": "/path/to/imas-codex"
    }
  }
}

运作原理

1. 安装：在包安装过程中，当模块首次导入时，索引会自动构建
2. 构建过程：系统解析IMAS数据字典，并创建包含结构化数据的全面JSON文件
3. 嵌入生成：使用句子变换器创建语义嵌入，以实现高级搜索功能
4. 序列化：系统将索引存储在有组织的子目录中：

- JSON数据: imas_codex/resources/schemas/ （LLM优化结构化数据） - 嵌入缓存：用于语义搜索的预先计算的句子变换器嵌入

1. 导入：导入模块时，预构建的索引和嵌入将在约1秒内加载

可选依赖关系和运行时要求

IMAS Codex服务器现在包括 imas-data-dictionaries 作为核心依赖，提供稳定的DD版本访问（默认值：4.0.0）。git开发包(imas-data-dictionary)在解析最新DD更改时，在车轮制造过程中使用。

软件包安装选项

• 运行时: uv add imas-codex -包括所有传输（stdio、sse、可流式传输http）
• 完整安装: uv add imas-codex -推荐给所有用户

数据字典访问

该系统使用可组合的访问器来访问IMAS数据字典版本和元数据：

1. 环境变量: IMAS_DD_VERSION （最高优先级）-设置为指定DD版本（例如“4.0.0”）
2. 元数据文件：JSON元数据与索引一起存储
3. 索引名称解析：从索引文件名中提取版本
4. 包默认值：回落到 imas-data-dictionaries 软件包（4.0.0）

这种设计确保服务器可以：

• 构建索引 使用由指定的版本 IMAS_DD_VERSION
• 使用预先构建的索引运行 使用版本元数据
• 访问稳定的DD版本 通过 imas-data-dictionaries PyPI包

索引构建与运行时

• 建立索引：需要 imas-data-dictionary 用于解析XML和创建索引的包
• 运行时搜索：只需要预先构建的索引和元数据，不依赖IMAS包
• 版本访问：使用具有多种回退策略的可组合访问器模式

实现细节

搜索实施

搜索系统是通过IMAS数据字典提供快速、灵活搜索功能的核心组件。它将高效的索引与IMAS特定的数据处理和语义搜索相结合，以实现不同的搜索模式：

搜索方法

1. 语义搜索 (SearchMode.SEMANTIC):

- 使用句子变换器的人工智能语义理解 - 具有物理上下文感知的自然语言查询 - 即使没有精确的关键字匹配，也能查找概念上相关的术语 - 最适合探索性研究和概念发现

1. 词汇搜索 (SearchMode.LEXICAL):

- 基于文本的快速搜索，具有精确的关键字匹配 - 布尔运算符AND, OR, NOT) - 通配符(* 和 ? 图案） - 字段特定搜索（例如。， documentation:plasma ids:core_profiles) - 已知术语的最快性能

1. 混合搜索 (SearchMode.HYBRID):

- 结合语义和词汇方法 - 提供精确匹配和概念相关性 - 平衡的性能和全面性

1. 自动搜索 (SearchMode.AUTO):

- 基于查询特征的智能搜索模式选择 - 自动选择最佳搜索策略 - 自适应性能优化

关键能力

• 搜索模式选择：在语义、词汇、混合或自动模式之间进行选择
• 性能缓存：基于TTL的缓存系统，具有命中率监控功能
• 语义嵌入：用于快速语义搜索的预先计算的句子变换器嵌入
• 物理背景：使用IMAS特定术语进行领域感知搜索
• 高级查询解析：支持复杂的搜索表达式和字段筛选
• 相关性排序：结果按匹配质量和物理相关性排序

未来工作

MCP资源实施（第2阶段-计划）

我们计划实施MCP资源，以提供对预先计算的IMAS数据的有效访问：

计划资源特征

• 静态JSON IDS数据：预先计算的IDS目录和结构数据作为MCP资源
• 物理测量数据：特定领域的测量数据和关系
• 用法示例：常见分析任务的代码示例和工作流模式
• 文献资源：交互式文档和API参考资料

资源类型

• ids://catalog -包含元数据的完整IDS目录
• ids://structure/{ids_name} -特定IDS的详细结构
• ids://physics-domains -物理域映射和关系
• examples://search-patterns -常见的搜索模式和工作流程

MCP提示实施（第3阶段-计划中）

物理分析和工作流程自动化的专业提示：

计划提示类别

• 物理分析提示：等离子体物理分析任务的专门提示
• 代码生成提示：为IMAS数据生成Python分析代码
• 工作流自动化提示：自动化复杂的多步骤分析工作流程
• 数据验证提示：创建IMAS测量的验证方法

提示模板

• physics-explain -生成全面的物理解释
• measurement-workflow -创建测量分析工作流
• cross-ids-analysis -分析多个IDS之间的关系
• imas-python-code -生成用于数据分析的Python代码

性能优化（第4阶段-进行中）

持续优化搜索和工具性能：

当前优化（已实施）

• ✅ 搜索模式选择：多种搜索模式（语义、词汇、混合、自动）
• ✅ 搜索缓存：基于TTL的缓存，具有搜索操作的命中率监控功能
• ✅ 语义嵌入：预先计算的句子变换器嵌入
• ✅ ASV基准测试：自动性能监控和回归检测

计划优化

• 高级缓存策略：所有MCP操作的智能缓存管理（搜索之外）
• 性能监控：增强了所有工具的指标跟踪和分析
• 多格式导出：优化导出格式（原始、结构化、增强）
• 选择性人工智能增强：基于请求上下文的条件AI增强

测试和质量保证（第5阶段-计划）

所有MCP组件的全面测试策略：

测试实施目标

• MCP工具测试：使用FastMCP 2测试框架完成测试覆盖
• 资源测试：验证所有MCP资源和数据完整性
• 快速测试：自动测试提示模板和响应
• 性能测试：所有工具的基准测试和回归检测

Docker使用

服务器可以作为预构建的Docker容器使用，索引已经构建：

# Pull and run the latest container
docker run -d -p 8000:8000 ghcr.io/iterorganization/imas-codex:latest

# Or use Docker Compose
docker-compose up -d

看 医生.md 有关容器使用、部署选项和故障排除的详细信息。