内容
# apsim-mcp
MCP 服务器，允许大型语言模型（LLM）驱动 [APSIM Next Gen](https://www.apsim.info) 农业系统模拟器，使用自然语言。任何支持 [MCP](https://modelcontextprotocol.io) 的客户端理论上都可以使用，但目前仅在 Claude（Claude Desktop 和 Claude Code）上进行了测试。
打开一个捆绑模型、作物、牧场、种植园、裸土水平衡模型或您自己的 `.apsimx` 文件，然后检查、编辑任何节点、附加天气和土壤、添加您想要的输出、运行它（单次运行或因子分析），并读取结果。每个模型都是一个会话，记录每一次编辑，因此报告的是实际运行的内容。
该工具是一个薄驱动程序，而不是数据管道：**您提供输入**。携带一个完整的 `.apsimx` 文件，或连接您自己的天气（`.met`）和土壤，它将继续使用提供的内容。
> [!注意]
> 请注意，商业 LLM（Claude/GPT）不是 APSIM 的最佳驱动程序，因此建议谨慎并仔细审查输出。
<p align="center">
<img src="docs/demo.gif" alt="通过 apsim-mcp 驱动玉米氮因子分析并绘制产量分布" width="100%">
</p>
<p align="center">
<sub>在 Claude Code 中驱动的会话：打开玉米示例，将时钟设置为 1961–2000 年，运行氮率因子分析，读取每季产量，并渲染产量分布的岭线图。</sub>
</p>
## 工具
通过会话操作任何模型：
| 工具 | 功能 |
|---|---|
| `list_models(filter?)` | 列出捆绑的示例模型以打开。 |
| `open_model(source, source_type?)` | 加载示例或 `.apsimx` 文件；返回其结构。 |
| `inspect(session_id, path?, node_type?)` | 整个结构、单个节点的参数或某种类型的每个节点。 |
| `edit(session_id, node_path, changes)` | 设置节点的属性（管理器、土壤层、时钟）。 |
| `set_weather(session_id, …)` | 附加您自己的 `.met` 文件，或获取 NASA POWER 气候数据。 |
| `set_soil(session_id, lat, lon)` | 获取某点的 SoilGrids 配置文件。 |
| `list_variables(session_id, node_path)` | 列出节点的报告成员（`LAI`、`SWmm`）以构建 `add_output` 表达式。 |
| `add_output(session_id, variables, …)` | 添加报告变量，以便运行产生所需的输出。 |
| `run_model(session_id, factors?)` | 运行；返回结果表的清单。传递 `factors` 以运行因子分析。 |
| `run_points(source, points, …)` | 在多个地理参考点运行基本模型；返回一个可映射表格，每个点一个指标。 |
| `read_output(session_id, …)` | 读取结果 - 总结、分页、重采样、聚合或写入 CSV 文件。 |
| `save_model(session_id, path)` | 将配置的模型写入 `.apsimx` 文件。 |
| `close_model(session_id)` | 关闭会话并释放其临时文件。 |
大多数工具是只读的或仅影响本地引擎；`save_model` 写入您命名的文件，而 `set_weather`/`set_soil` 在您请求获取数据时才访问网络。
## 安装
纯 Python 层（工具逻辑和测试）仅需要 Python。引擎层添加 APSIM 以进行模拟。
纯 Python 层：
```bash
python -m venv .venv && .venv/bin/pip install -e ".[dev]" # Windows: .venv\Scripts\pip
python -m pytest -q
```
引擎层：
1. 安装 [APSIM Next Gen](https://registration.apsim.info) （免费，非商业用途；自带 .NET）。标准安装会自动检测；如果不是，请设置 `APSIM_BIN_PATH`。
2. `pip install -e ".[engine,serve]"`
3. 可选 `.env`：`APSIM_MCP_WORKDIR`（本地、非云同步目录；默认为临时目录）和 `APSIM_MCP_UPLOAD_DIR`（允许读取和保存您自己的 `.apsimx` 文件的目录）。
4. `apsim-mcp-doctor` 检查安装并列出缺少的组件。
通过将 MCP 客户端指向 `apsim-mcp` 控制台脚本（在 Claude 外未测试）来连接它。对于 Claude：安装 [uv](https://docs.astral.sh/uv/)，然后 `/plugin marketplace add Briggs599/apsim-mcp`，安装 `apsim-mcp`，并重启 - 或将 `apsim-mcp` 控制台脚本添加到 `claude_desktop_config.json` 中。
## 使用
用自然语言提问；模型选择并链接工具。
- **驱动任何模型。** "打开玉米示例，附加我的天气文件 D:\wagga.met，添加每日土壤水和排水作为输出，运行它，并总结排水。" 模型链接 `open_model` → `set_weather` → `add_output` → `run_model` → `read_output`，并且可以 `save_model` 结果以重新打开或共享。
- **比较处理方法。** 给 `run_model` 一个 `factors` 列表，例如氮率与播种日期交叉，进行整个因子分析。每个结果行都标记有其处理方法，因此 `read_output(mode='aggregate', group_by=['N'])` 比较它们。
- **您自己的文件。** 将 `open_model` 指向 `.apsimx` 路径（首先设置 `APSIM_MCP_UPLOAD_DIR`）。它准确运行您构建的天气、土壤和管理模型。
## 架构
您用自然语言与模型对话；它通过 MCP（stdio）调用工具并读取结果。服务器是一个薄的两层堆栈，使用纯 **会话层** 和惰性加载的 **引擎**。
```mermaid
flowchart TB
U["您 — 自然语言"]
C["LLM · MCP 客户端<br/>在 Claude Desktop / Code 上测试"]
U <--> C
subgraph server["apsim-mcp 服务器 · MCP over stdio"]
direction TB
T["13 种工具：<br/>list_models · open_model · inspect · edit<br/>set_weather · set_soil · list_variables · add_output<br/>run_model · run_points · read_output · save_model · close_model"]
P["会话层 — primitives.py<br/>加载模型 · 编辑日志 · 有限输出"]
E["引擎，惰性加载 — engine.py<br/>apsimNGpy → APSIM Next Gen / .NET"]
T --> P --> E
end
C <-->|"工具调用 / JSON 结果"| T
E -->|"运行模型"| R["APSIM 运行<br/>结果数据库 → 清单"]
R -->|"read_output"| P
Y["您的文件：<br/>.apsimx · .met · 土壤"] --> P
E -.->|"可选获取"| NASA["NASA POWER 气候"]
E -.->|"可选获取"| SG["SoilGrids 土壤"]
```
## 链接
- APSIM Next Gen：[apsim.info](https://www.apsim.info) — 在 [registration.apsim.info](https://registration.apsim.info) 注册/下载
- apsimNGpy（Python 驱动程序）：[apsimngpy.readthedocs.io](https://apsimngpy.readthedocs.io)
- 可选数据获取器：[NASA POWER](https://power.larc.nasa.gov) 气候 · [SoilGrids / ISRIC](https://soilgrids.org) 土壤
## 许可证
代码是 Apache-2.0（参见 [LICENSE](LICENSE)）。APSIM 通过 apsimNGpy 是免费用于非商业用途的，其许可证为自有许可证。可选的 NASA POWER 气候和 SoilGrids 土壤数据是 CC BY 4.0 或公共领域。
