内容
# 科学图形库
科学图形库是一个标准的MCP服务器和MCP应用程序，用于查找、导入和实现科学图形引用。它与Wisp无关：任何stdio MCP主机都可以使用它。包含的Wisp清单和技能是一个薄的可选适配器。
首个版本有两个模板来源：
- **FigureYa** — 319个可搜索的模块，带有本地缩略图和提交固定的存档。
- **用户库** — 从MCP主机提供的路径复制的图形和绘图代码。
主机代理分析上传的图像、自然语言请求或数据文件。它建立一个紧凑的检索意图，搜索两个来源，检查顶部预览，并在实现任何内容之前决定该候选者是否真正匹配。目录分数对检索候选者进行排序；它不是推荐或视觉相似性分数。
对于图像输入，代理必须首先使用主机的`view_image`检查用户的图像，然后使用`figure_library_preview`检查顶级候选者。最终推荐包括代理生成的视觉通过/拒绝分数，涵盖图表系列、布局、轴/几何、编码和注释/样式，以及单独的数据兼容性裁决。
## 安全合约
服务器复制并提取引用文件，但从不执行绘图代码或依赖安装程序。它使用SHA-256验证导入的用户文件，并使用固定的目录验证FigureYa存档。
**实现错误是终端错误。** `figure_library_materialize` 返回一个`STOP:`错误，指示代理报告确切的失败并等待用户。代理不得切换提取模式，使用另一个下载器，获取完整的存储库，重新创建模板或生成替代/演示图。此行为由MCP烟雾测试覆盖。
## 构建
要求：Node.js 22或更新版本。
```bash
npm install
npm run check
```
## 与任何stdio MCP客户端一起使用
```json
{
"mcpServers": {
"figure-library": {
"command": "node",
"args": ["/absolute/path/to/ScientificFigureLibrary/dist/index.js"],
"env": {
"FIGURE_LIBRARY_DIR": "/absolute/path/to/my-figure-library",
"FIGUREYA_SOURCE_PACK_DIR": "/optional/path/to/FigureYaSourcePack"
}
}
}
}
```
`FIGURE_LIBRARY_DIR` 默认值为 `~/.figure-library`。服务器暴露：
- `figure_library_open` — 打开一个空的候选工作台。
- `figure_library_search` — 搜索FigureYa和/或用户库。
- `figure_library_import` — 安全地复制用户图形和/或代码到库中。
- `figure_library_preview` — 返回候选者为MCP图像内容和可选的检查路径。
- `figure_library_source_status` — 检查用户库和FigureYa源包。
- `figure_library_describe` — 检查一个确切的模板。
- `figure_library_materialize` — 将选定的引用写入项目。
MCP服务器不包含第二个模型。代理推理保留在主机中：理解输入 → 构建检索意图 → 搜索 → 查看顶级候选者 → 视觉和语义审计 → 仅实现接受的模板。对于附件，主机在本地提供文件，代理将这些路径传递给 `figure_library_import`。对于搜索，代理传递紧凑的描述，而不是原始数据集。
`figure_library_preview` 返回标准的MCP图像内容。在Wisp中，传递绝对的项目本地 `destination`（例如，`/project/.wisp/figure-library-previews`）并在返回的路径上调用 `view_image`。这即使在主机只公开MCP工具结果的文本部分时，也将视觉判断权交给代理。
导入参数示例：
```json
{
"title": "我们的实验室火山图",
"description": "标记的差异表达火山图",
"tags": ["火山图", "差异表达"],
"visualProfile": "log2FC x轴，-log10 FDR y轴，标记的命中",
"dataProfile": "基因，log2FC，调整后的p值",
"imagePath": "/project/references/volcano.png",
"codePaths": ["/project/references/volcano.R"],
"license": "内部实验室参考"
}
```
支持的视觉引用是PNG、JPEG、WebP、SVG和PDF（最大20 MiB）。最多可以导入20个R、R Markdown、Quarto、Python、笔记本、Julia、MATLAB、Markdown、TeX、shell、JSON或YAML文件（每个文件最大5 MiB，总共最大50 MiB）。原始绝对路径从未存储在可共享的清单中。
## 分发
独立的npm tarball包含服务器、应用程序、FigureYa搜索目录和缩略图，但不包含大型存档集合：
```bash
npm run package:npm
npm install --global ./release/scientific-figure-library-0.1.1.tgz
```
在安装后，将`scientific-figure-library`用作MCP命令。
对于Wisp：
```bash
npm run package:wisp
```
从Wisp **设置 → 插件** 安装 `release/scientific-figure-library-wisp-0.1.1.zip`，为项目启用它，并启动一个新的会话。
## FigureYa源包
核心插件和可选的源包是故意分开的。源包是一个普通的目录，包含现有的FigureYa压缩模块的ZIP文件：
```text
FigureYaSourcePack/
├── FigureYa59volcanoV2.zip
└── archives/
└── FigureYa9heatmap.zip
```
将此目录作为 `sourcePackDir` 传递或设置 `FIGUREYA_SOURCE_PACK_DIR`。解析顺序为：
1. 本地源包。
2. 在 `FIGUREYA_ARCHIVE_BASE_URLS` 中配置的基准。
3. GitHub上的提交固定FigureYa压缩存档。
完整的固定存档集合约为3 GiB，因此它不包含在两个插件包中。它可以通过USB/共享存储复制或分成小的传输包：
```bash
npm run package:source-pack -- \
--source /path/to/FigureYa-compressed \
--name volcano \
--modules FigureYa59volcanoV2
```
助手验证每个选定的ZIP文件，并限制一个传输包的最大大小为200 MiB。在使用前，请提取生成的 `release/figure-library-source-pack-volcano-0.1.1.zip`。
## 实现的布局
FigureYa模板：
```text
<destination>/<template-id>/
├── upstream/
├── TEMPLATE.md
└── template.lock.json
```
用户模板：
```text
<destination>/<template-id>/
├── reference/
│ ├── preview.*
│ └── code/
├── TEMPLATE.md
└── template.lock.json
```
现有的目标永远不会被覆盖。保持 `upstream/` 或 `reference/` 不变，并在单独的文件中调整绘图代码。
## 目录开发
存储库包含生成的FigureYa目录。要从本地检出重新生成它：
```bash
git -C /path/to/FigureYa-compressed ls-tree --name-only HEAD |
npm run catalog -- \
--source /path/to/FigureYa \
--figureya-commit <figureya-commit> \
--compressed-commit <compressed-repo-commit> \
--compressed-tree /path/to/compressed-github-tree.json
```
## 许可证
项目代码根据MIT许可证授权。FigureYa派生的目录数据、缩略图和下载的模板仍受CC BY-NC-SA 4.0约束。用户导入的材料保留在导入时提供的许可证。参见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
