咪酱-MCP服务器

Name: 咪酱-MCP服务器
Author: iterorganization

作者：iterorganization2 星标更新：2025-10-28

安装使用来源：spider==github.com

项目介绍

IMAS MCP 服务器

[![预提交检查][pre-commit-badge]][pre-commit-link] [![Ruff代码风格检查][ruff-badge]][ruff-link] [![Python版本][python-badge]][python-link] [![CI/CD状态][build-deploy-badge]][build-deploy-link] [![测试覆盖率][codecov-badge]][codecov-link] [![文档][docs-badge]][docs-link] [![性能基准测试][asv-badge]][asv-link]

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

快速开始

选择适合您环境的安装方法：

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

选择托管选项以即时访问；选择本地选项进行定制或控制资源。

HTTP | UV | Docker | Slurm / HPC

HTTP（远程公共端点）

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

VS Code（交互式）

Ctrl+Shift+P → "MCP: 添加服务器"
选择 "HTTP 服务器"
名称：imas
URL：https://imas-dd.iter.org/mcp

VS Code（手动JSON）

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

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

Claude Desktop 配置

选择您的操作系统路径：

Windows: %APPDATA%\\Claude\\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

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

OP 客户端（待澄清）

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

UV 本地安装

使用 uv 进行安装：

# 标准安装（需要嵌入式API密钥）
uv tool install imas-mcp

# 带有本地嵌入支持的安装（包括sentence-transformers）
uv tool install "imas-mcp[transformers]"

# 将带有transformers支持的包添加到项目环境
uv add "imas-mcp[transformers]"

嵌入配置

IMAS MCP服务器支持两种生成嵌入的方式：

基于API的嵌入（默认）：通过OpenRouter使用远程嵌入API
- 需要 OPENAI_API_KEY 和 OPENAI_BASE_URL 环境变量
- 不需要本地依赖项
- 示例模型：openai/text-embedding-3-small
本地嵌入：使用sentence-transformers库
- 使用 [transformers] 扩展安装：pip install imas-mcp[transformers]
- 在本地运行模型，无需API调用
- 示例模型：all-MiniLM-L6-v2（默认）

配置：

# 基于API（需要API密钥）
export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export IMAS_MCP_EMBEDDING_MODEL="openai/text-embedding-3-small"

# 本地transformers（需要[transformers]扩展）
export IMAS_MCP_EMBEDDING_MODEL="all-MiniLM-L6-v2"

错误处理：

如果您尝试使用未安装 [transformers] 扩展的本地嵌入，将会看到：

ImportError: sentence-transformers 是本地嵌入模型所必需的，但未安装。

解决方法：
1. 安装带有transformers支持的包：pip install imas-mcp[transformers]
2. 设置API密钥以使用远程嵌入：
   - 设置 OPENAI_API_KEY 环境变量
   - 设置 OPENAI_BASE_URL 环境变量（例如，https://openrouter.ai/api/v1）
   - 设置 IMAS_MCP_EMBEDDING_MODEL 为API模型（例如，openai/text-embedding-3-small）

VS Code：

{
  "servers": {
    "imas-mcp-uv": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--active", "imas-mcp", "--no-rich"]
    }
  }
}

Claude Desktop：

{
  "mcpServers": {
    "imas-mcp-uv": {
      "command": "uv",
      "args": ["run", "--active", "imas-mcp", "--no-rich"]
    }
  }
}

Docker 设置

在容器中本地运行（包含预构建索引）：

docker run -d \
  --name imas-mcp \
  -p 8000:8000 \
  ghcr.io/iterorganization/imas-mcp:latest-streamable-http

# 可选：验证
docker ps --filter name=imas-mcp --format "table {{.Names}}\t{{.Status}}"

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "imas-mcp-docker": { "type": "http", "url": "http://localhost:8000/mcp" }
  }
}

Claude Desktop：

{
  "mcpServers": {
    "imas-mcp-docker": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8000/mcp"]
    }
  }
}

Slurm / HPC（STDIO）

辅助脚本：scripts/imas_mcp_slurm_stdio.sh

VS Code（.vscode/mcp.json，JSONC也适用）：

{
  "servers": {
    "imas-slurm-stdio": {
      "type": "stdio",
      "command": "scripts/imas_mcp_slurm_stdio.sh"
    }
  }
}

启动行为：

如果存在 SLURM_JOB_ID → 在当前分配内启动。
否则请求节点并使用 srun --pty 启动服务器（无缓冲标准I/O）。

资源调整（在客户端启动前导出）：

变量	目的	默认值
`IMAS_MCP_SLURM_TIME`	壁钟时间	`08:00:00`
`IMAS_MCP_SLURM_CPUS`	每任务CPU数	`1`
`IMAS_MCP_SLURM_MEM`	内存（例如 `4G`）	Slurm 默认值
`IMAS_MCP_SLURM_PARTITION`	分区	集群默认值
`IMAS_MCP_SLURM_ACCOUNT`	账户/项目	用户默认值
`IMAS_MCP_SLURM_EXTRA`	额外的原始 `srun` 标志	（空）
`IMAS_MCP_USE_ENTRYPOINT`	使用 `imas-mcp` 入口点 vs `python -m`	`0`

示例：

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

直接CLI：

scripts/imas_mcp_slurm_stdio.sh --ids-filter "core_profiles equilibrium"

为什么是STDIO？避免打开网络端口；所有流量都通过现有的srun伪终端。

示例 IMAS 查询

一旦您配置了IMAS MCP服务器，就可以使用自然语言查询与其互动。使用 @imas 前缀将查询定向到IMAS服务器：

基本搜索示例

查找与等离子体温度相关的数据路径
搜索电子密度测量数据
可用于磁场分析的数据有哪些？
显示核心等离子体剖面

物理概念探索

解释等离子体物理中的平衡重建意味着什么
压力与磁场之间的关系是什么？
传输系数如何与等离子体约束相关？
描述电流驱动机制背后的物理原理

数据结构分析

分析核心剖面IDS的结构
平衡与核心剖面之间的关系是什么？
展示运输数据的标识符模式
导出平衡、核心剖面和运输IDS的批量数据

高级查询

找到不同IDS中包含温度测量的所有路径
IMAS数据字典覆盖哪些物理领域？
展示用于聚变功率计算的测量依赖性
探索加热与约束之间的跨域关系

工作流和集成

如何从IMAS数据中访问电子温度剖面？
等离子体平衡分析的推荐工作流是什么？
展示诊断标识符模式的分支逻辑
导出用于全面传输分析的物理领域数据

IMAS MCP服务器提供了8种专门工具，用于不同类型查询：

搜索：跨IMAS数据路径的自然语言和结构化搜索
解释：具有IMAS上下文和领域专业知识的物理概念
概述：关于IMAS结构和可用数据的一般信息
分析：特定IDS的详细结构分析
探索：发现数据路径和物理领域之间的关系
标识符：枚举选项和分支逻辑的探索
批量导出：多个IDS及其关系的综合导出
领域导出：具有测量依赖性的物理领域特定数据

文档搜索

服务器集成了对文档库的搜索，IMAS-Python作为默认索引库。此功能使AI助手能够使用自然语言查询搜索文档来源。

可用的MCP工具函数

search_docs：搜索任何已索引的文档库
- 参数：query（必需），library（可选），limit（可选，1-20），version（可选）
- 支持多个文档库
- 返回综合版本和库信息
search_imas_python_docs：在IMAS-Python文档中搜索
- 参数：query（必需），limit（可选），version（可选）
- 自动使用IMAS-Python库
- IMAS特定搜索优化
list_docs：列出所有可用的文档库或获取特定库的版本
- 参数：library（可选）
- 当未指定库时：返回所有可用库的列表
- 当指定了库时：返回该特定库的版本
- 显示所有已索引的版本和最新版本

CLI命令

add-docs：通过命令行添加新的文档库
- 使用：add-docs LIBRARY URL [OPTIONS]
- 需要：OpenRouter API密钥和嵌入式模型配置
- 支持自定义最大页面数和最大深度设置
- 包括 --ignore-errors 标志（默认启用）以优雅地处理有问题的页面
- 见下面的例子

文档搜索示例

# 搜索IMAS-Python文档
search_imas_python_docs "平衡计算"
search_imas_python_docs "IDS数据结构" limit=5
search_imas_python_docs "磁场" version="2.0.1"

# 搜索任何文档库
search_docs "神经网络" library="numpy"
search_docs "数据可视化" library="matplotlib"

# 列出所有可用库
list_docs

# 获取特定库的版本
list_docs "imas-python"

# 使用CLI添加新文档
add-docs udunits https://docs.unidata.ucar.edu/udunits/current/
add-docs pandas https://pandas.pydata.org/docs/ --version 2.0.1 --max-pages 500
add-docs imas-python https://imas-python.readthedocs.io/en/stable/ --no-ignore-errors

设置说明

生产（Docker）

IMAS-Python文档在构建期间自动抓取。

docker-compose up --build

本地开发

# 1. 启动docs-mcp-server
python scripts/start_docs_server.py

# 2. 在另一个终端中启动IMAS-MCP服务器
python -m imas_mcp

# 3. 抓取IMAS-Python文档（仅首次）
python scripts/scrape_imas_docs.py

API密钥配置

为了具备文档抓取能力，您需要一个OpenRouter API密钥：

对于本地开发：

# 设置环境变量（从env.example创建.env文件）
cp env.example .env
# 编辑.env文件，添加您的OpenRouter API密钥

对于CI/CD（GitHub Actions）：

转到您的仓库设置：设置 → 机密和变量 → 操作
添加一个新的仓库机密：
- 名称：OPENAI_API_KEY
- 值：您的OpenRouter API密钥

📖 详细设置指南：参见 .github/SECRETS_SETUP.md 以获取完整的配置GitHub仓库机密和故障排除说明。

构建行为：

有OPENAI_API_KEY：构建期间完全抓取文档
没有OPENAI_API_KEY：跳过文档抓取，继续构建
无论抓取状态如何，容器都能正常工作

本地Docker构建：

# 使用API密钥构建
docker build --build-arg OPENAI_API_KEY=your_key_here .

# 不使用API密钥构建（跳过抓取）
docker build .

添加新的文档库

使用 add-docs CLI命令添加新的文档库：

# 添加文档库
add-docs udunits https://docs.unidata.ucar.edu/udunits/current/
add-docs numpy https://numpy.org/doc/stable/ --max-pages 500 --max-depth 3

注意：需要设置OPENAI_API_KEY环境变量（参见上面的API密钥配置）。

故障排除

如果文档搜索不可用：

检查docs-mcp-server是否正在运行：curl http://localhost:6280/api/ping
验证环境：echo $DOCS_SERVER_URL
检查日志中的连接错误
按照错误消息中的设置说明操作

开发

对于本地开发和定制：

设置

# 克隆仓库
git clone https://github.com/iterorganization/imas-mcp.git
cd imas-mcp

# 安装开发依赖项（搜索索引构建大约需要8分钟，首次）
uv sync --all-extras

构建依赖项

此项目在构建过程中需要额外的依赖项，这些依赖项不是运行时依赖项的一部分：

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

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

对于开发者：构建时依赖项包含在pyproject.toml中的[build-system.requires]部分，用于构建轮子。当构建带有最新DD更改的轮子时，需要git包。

# 正常开发 - 使用imas-data-dictionaries（PyPI）
uv sync --all-extras

# 设置DD版本用于构建（默认为4.0.0）
export IMAS_DD_VERSION=4.0.0
uv run build-schemas

位置在配置中：

构建时依赖项：列在pyproject.toml中的[build-system.requires]
运行时依赖项：imas-data-dictionaries>=4.0.0在[project.dependencies]

注意：环境变量IMAS_DD_VERSION控制构建模式和嵌入时使用的DD版本。Docker容器默认设置为4.0.0。

开发命令

# 运行测试
uv run pytest

# 运行代码检查和格式化
uv run ruff check .
uv run ruff format .

# 从IMAS数据字典构建模式数据结构
uv run build-schemas

# 构建文档存储和语义搜索嵌入
uv run build-embeddings

# 在本地运行服务器（默认：streamable-http端口8000）
uv run --active imas-mcp --no-rich

# 使用stdio传输运行MCP客户端
uv run --active imas-mcp --no-rich --transport stdio

构建脚本

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

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

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

**`build-