SCAPS-1D

scaps-mcp

用于 SCAPS-1D 的 MCP 服务。SCAPS-1D 是根特大学开发的一维太阳能电池模拟器。它可在无界面模式下驱动你自己的 SCAPS 安装，并为任何 MCP 客户端提供器件设计、模拟、批处理、曲线拟合、结果分析和真实性检查功能。

SCAPS 不包含在内。请按照 SCAPS 网站上的说明向其作者申请，并遵守其使用条件，其中包括在出版物中引用 SCAPS。

功能

• 器件：描述任意 .def 文件，使用所有 SCAPS set 命令编辑，向层中加载 .material 文件，从头创建器件（最多 7 层、每层 7 个缺陷、每个界面 3 个缺陷），并设置脚本无法访问的求解器数值参数。
• 模拟：J-V、QE、C-V 和 C-f，可使用任意工作点、光照侧、光谱或生成模型、ND 滤光片和截止波长；能带、产生-复合和 AC 分布。
• 批处理：针对任意 set 或 action 键进行网格或成对扫描，包括温度、光强和偏压。
• 拟合与优化：使用有界 Nelder-Mead 算法拟合一条或多条测量曲线（光照和暗态 J-V、QE、C-V），或将效率、Voc、Jsc 或 FF 优化至最大值、最小值或目标值。
• 输入文件：导入共享的 .def、.material、吸收率、光谱、生成、滤光片、渐变和测量文件；也可从数据生成这些文件，并进行单位换算（吸收率可由 alpha 或消光系数 k 得出）。
• 分析：所用光谱下吸收层的 Shockley-Queisser 极限、QE 积分得到的 Jsc、Mott-Schottky 内建电压和掺杂浓度、每个界面的能带偏移。
• 真实性检查：结果超过详细平衡极限、缺少辐射复合、理想界面、能带尖峰和悬崖、补偿缺陷、不合理的态密度、默认吸收模型，以及其他导致 SCAPS 研究结果不符合物理实际的常见原因。
• 作业：长时间运行的任务会在后台继续执行，并支持查看进度、等待和取消。
• 验证：在启动 SCAPS 前，会根据已安装 SCAPS 版本的命令列表检查每个键和值。

要求

• SCAPS-1D 3.3（已使用 3.3.12 测试）
• Python 3.11 或更高版本

在 Windows 上设置

使用安装程序将 SCAPS 安装到你有写入权限的文件夹中。SCAPS 会将其安装文件夹用作工作文件夹，其作者建议不要安装到 Program Files。将 SCAPS 更新文件复制并覆盖已安装的文件，然后检查服务是否能找到它：

uvx scaps-mcp doctor

在 Linux 上设置（可选）

SCAPS 是 Windows 程序；在 Linux 上，它通过 Wine 和 Xvfb 以无界面模式运行。请安装两者（适用于 Debian 和 Ubuntu）：

sudo dpkg --add-architecture i386
sudo apt update
sudo apt install wine wine32:i386 xvfb

创建 32 位前缀，并从解压后的 SCAPS 安装程序所在文件夹将 SCAPS 安装到该前缀中：

export WINEARCH=win32 WINEPREFIX="$HOME/scaps/prefix"
xvfb-run -a bash -c 'wineboot -i && wineserver -w'
xvfb-run -a bash -c 'wine setup.exe /q /AcceptLicenses yes /r:n && wineserver -w'

将 SCAPS 更新文件复制并覆盖已安装的文件，然后检查服务是否能找到它：

uvx scaps-mcp doctor

查找 SCAPS

如果未设置 SCAPS_HOME，服务会在以下位置向下查找一到两层，寻找名称包含“scaps”的文件夹；该文件夹必须包含 scapsXXXX.exe 以及 def、results 和 script 文件夹：

• Windows：系统驱动器、用户文件夹、Documents、Desktop、Downloads、Program Files 和 Program Files (x86)。
• Linux：主目录，以及 Wine 前缀中的 drive_c 和 Program Files 文件夹：~/.wine、$WINEPREFIX、$SCAPS_WINEPREFIX、winetricks 前缀，以及主目录中名称类似 scaps 的文件夹内的前缀。

如果找到多个安装版本，则使用最新的 SCAPS 版本。scaps_status 和 doctor 会显示正在使用的文件夹及其他文件夹。设置 SCAPS_HOME 可自行选择一个安装目录。

配置

变量	含义	默认值
SCAPS_HOME	包含 scapsXXXX.exe 的 SCAPS 文件夹	自动查找
SCAPS_EXE	可执行文件名称	最新的 scaps*.exe
SCAPS_TIMEOUT	每次 SCAPS 运行的秒数	300
SCAPS_RUNS_DIR	保存运行输入和结果的位置	用户缓存文件夹
SCAPS_WINEPREFIX	仅限 Linux：Wine 前缀	包含 SCAPS 文件夹的前缀
SCAPS_WINE、SCAPS_WINESERVER	仅限 Linux：Wine 二进制文件	在系统中查找
SCAPS_XVFB	仅限 Linux：设为 0 时使用当前显示器，而不是 Xvfb	1

绘图需要可选依赖：uvx --with matplotlib scaps-mcp，或安装 scaps-mcp[plot]。

客户端

Claude Code：

claude mcp add --transport stdio scaps -- uvx scaps-mcp

直接从代码仓库运行，而不是从 PyPI 安装：

claude mcp add --transport stdio scaps -- uvx --from git+https://github.com/asiff00/scaps-mcp scaps-mcp

如果 SCAPS 位于服务不会搜索的位置，请在 scaps 前添加 --env SCAPS_HOME=<folder>。

项目配置（.mcp.json），为批处理和拟合设置较长的工具超时时间：

{
  "mcpServers": {
    "scaps": {
      "command": "uvx",
      "args": ["scaps-mcp"],
      "timeout": 3600000
    }
  }
}

其他 MCP 客户端启动相同的命令；仅当 SCAPS 位于服务不会搜索的位置时，才需在服务环境中设置 SCAPS_HOME。

工具

工具	用途
scaps_status	安装、版本、运行文件夹、绘图支持、正在运行的作业
scaps_list_files	定义、材料、光谱、吸收、渐变、测量及其他文件
scaps_script_reference	搜索已安装的 SCAPS 命令列表
scaps_describe_device	层、缺陷、带偏移的界面、接触、真实性检查
scaps_edit_device	设置命令、材料和求解器数值参数，并另存为新定义
scaps_create_device	根据层、缺陷、界面和接触描述创建设备
scaps_import_file	添加共享的 SCAPS 文件并报告缺失的引用文件
scaps_write_data	根据数据写入吸收、光谱、生成、滤光、渐变或测量文件
scaps_simulate	执行一次模拟，并提供指标、曲线、剖面、分析和检查
scaps_batch	对设置键和操作键执行网格或成对扫描
scaps_optimize	拟合测量曲线或优化品质因数
scaps_jobs	列出、检查、等待或取消运行
scaps_results	从任意结果文件获取分页表格
scaps_plot	绘制结果曲线和剖面的 PNG 图
scaps_run_script	用于记录器、数学运算、循环和叠层工作流的经过验证的 SCAPS 脚本
scaps_sq_limit	给定带隙和光谱时的详细平衡极限

定义和运行文件也可作为 scaps://definitions/{name} 和 scaps://runs/{run_id}/{file} 资源使用。

约定

键和单位遵循 SCAPS 脚本语言：厚度以 um 为单位，密度以 cm^-3 为单位，界面密度以 cm^-2 为单位，迁移率以 cm^2/Vs 为单位，速度以 cm/s 为单位，截面以 cm^2 为单位，能量以 eV 为单位，温度以 K 为单位。层、缺陷和界面从 1 开始计数，第 1 层与左侧（背面）接触相邻。接触通过 contactleft 和 contactright 指定。

脚本无法向某一层添加第一个体缺陷；scaps_create_device 会插入一个并进行配置。渐变定律、多价缺陷的逐能级参数以及 GUI 曲线拟合器没有对应的脚本命令；请使用渐变文件、scaps_optimize 和在 GUI 中创建的定义。

安全

每个安装一次只运行一个 SCAPS 进程，并通过文件锁加以保护（Linux 上使用 fcntl，Windows 上使用 msvcrt）；所有进程都会遵守此锁。停止服务（包括使用 SIGTERM 停止）会终止该服务启动的 SCAPS 进程；崩溃后遗留的进程会在下次运行时终止。文件名必须是 SCAPS 文件夹内不含路径的名称。脚本不得运行系统命令或打开阻塞式对话框。为实现隔离，请移除前缀中将主机根目录映射为 Wine 驱动器的设置。

配套技能

scaps-1d 技能会教 Agent 使用 SCAPS 工作流并遵循真实性规则。它可独立运行，也会在可用时使用这些工具。

开发

uv sync
uv run pytest
uv run pytest -m scaps
uv run ruff check src tests

引用

使用 SCAPS 进行的模拟应引用 M. Burgelman、P. Nollet 和 S. Degrave 的《多晶半导体太阳能电池建模》，Thin Solid Films 361-362（2000）527-532，doi:10.1016/S0040-6090(99)00825-1。

许可证

MIT