# LS-DYNA R13 关键字手册 MCP 服务

[English README](README_EN.md)

将 **LS-DYNA R13 用户手册（Vol I 关键字 / Vol II 材料模型 / Vol III 多物理场求解器）** 解析为结构化知识库，并通过 MCP（Model Context Protocol）暴露给本机所有 AI Agent（opencode、Claude Code、Cursor 等），用于辅助编写和校核 LS-DYNA 关键字输入文件（K 文件）。

## 能力一览

- 三卷手册共 **1582 个关键字小节、4019 个卡片块、约 21000 个字段** 的结构化提取
- 每个卡片字段包含：变量名、卡号、列位置、类型（I/F/A）、默认值
- 完整保留手册原文（参数说明、备注、选项表），支持小节内全文检索
- 别名解析：`*MAT_024` / `MAT_24` / `24` / `piecewise_linear` 均可命中同一小节
- 跨卷消歧：同名条目返回候选列表，可按卷指定
- 家族大节（如 `*CONTACT`）支持定向摘录检索

## 工具列表

| 工具 | 说明 |
|---|---|
| `list_cards(volume, prefix)` | 按卷（1/2/3）和名称前缀浏览所有关键字小节 |
| `search_cards(query, volume)` | 按名称/别名/内容模糊检索 |
| `get_card_syntax(name, volume)` | 获取小节完整语法：逐卡字段表 + 手册原文（>40KB 自动截断） |
| `get_field_info(card, field)` | 单字段精确定位：卡号/位置/类型/默认值/描述 |
| `search_in_section(card, query)` | 小节内二次检索，返回命中上下文摘录（`*CONTACT` 等家族大节必备） |

## 安装与使用

### 1. 准备手册 PDF

本仓库**不包含手册 PDF 及解析后的数据文件**（LSTC 手册为版权文档，请使用你合法持有的副本）。将以下三个文件放入仓库根目录：

```
ls-dyna_manual_volume_i_r13_KEYWORD_USER'S_MANUAL.pdf
ls-dyna_manual_volume_ii_r13_Material_Models.pdf
ls-dyna_manual_volume_iii_r13_Multi-PhysicsSolvers.pdf
```

### 2. 构建知识库

```bash
pip install -r requirements.txt
python tools/build_all_v2.py
```

生成 `library_vol1.json` / `library_vol2.json` / `library_vol3.json`（约 7 秒）。

### 3. 验证（可选）

```bash
python tools/test_retrieval.py   # 32 项检索精度测试
python tools/smoke_client.py     # MCP stdio 端到端冒烟测试
```

### 4. 注册到 Agent

opencode（`~/.config/opencode/opencode.json`）：

```json
"mcp": {
  "lsdyna-docs": {
    "type": "local",
    "command": ["python", "/path/to/lsdyna_mat_server.py"]
  }
}
```

Claude Code / Cursor 等其他 MCP 客户端按各自格式注册同一命令即可。

## 解析质量

经自动质检 + 人工抽查验证（详见 [REVIEW.md](REVIEW.md)）：

- 卡片块数、字段名、类型、默认值与手册原文逐一对齐
- Vol III 小节检测率 272/273；Vol II 与材料/EOS 引导句总数对账一致；Vol I TOC 887 条全覆盖
- 已知限制：默认值上标丢失（`10^20`→`1020`）、数学公式区提取乱码（文字说明完整）、`*CONTACT` 等家族大节需节内二次检索

## 版本声明

本项目基于 **LS-DYNA R13 版用户手册** 构建与验证。其他版本手册的小节标题/页眉版式可能不同，需重新验证切片规则。

## 许可

- 代码：MIT License
- LS-DYNA 手册 PDF 及从中提取的数据文件：**不在本仓库分发**，版权归原作者（LSTC / ANSYS）所有，请自行合法获取并在本地生成