Scientific Figure Library

Scientific Figure Library is a standard MCP server and MCP App for finding, importing, and materializing scientific figure references. It is not tied to Wisp: any stdio MCP host can use it. The included Wisp manifest and Skill are a thin optional adapter.

The first release has two template sources:

• FigureYa — 319 searchable modules with local thumbnails and commit-pinned archives.
• User Library — figures and plotting code copied from paths supplied by the MCP host.

The host Agent analyzes an uploaded image, a natural-language request, or a data file. It builds a compact retrieval intent, searches both sources, inspects the top preview, and decides whether that candidate actually matches before materializing anything. The catalog score orders retrieval candidates; it is not a recommendation or visual-similarity score.

For image input, the Agent must first inspect the user's image with the host's view_image, then inspect the top candidate with figure_library_preview. The final recommendation includes an Agent-produced visual pass/reject score covering chart family, layout, axes/geometry, encodings, and annotations/style, plus a separate data-compatibility verdict.

Safety contract

The server copies and extracts reference files but never executes plotting code or dependency installers. It verifies imported user files with SHA-256 and verifies FigureYa archives against the pinned catalog.

Materialization errors are terminal. figure_library_materialize returns a STOP: error that instructs the Agent to report the exact failure and wait for the user. The Agent must not switch extraction modes, use another downloader, fetch the complete repository, recreate the template, or generate a substitute/demo plot. This behavior is covered by the MCP smoke test.

Build

Requirements: Node.js 22 or newer.

npm install
npm run check

Use with any stdio MCP client

{
  "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 defaults to ~/.figure-library. The server exposes:

• figure_library_open — open an empty candidate workbench.
• figure_library_search — search FigureYa and/or the user library.
• figure_library_import — safely copy a user figure and/or code into the library.
• figure_library_preview — return a candidate as MCP image content and, optionally, a checked project-local preview path for Agent inspection.
• figure_library_source_status — inspect the user library and a FigureYa Source Pack.
• figure_library_describe — inspect one exact template.
• figure_library_materialize — write one selected reference to a project.

The MCP server does not contain a second model. Agent reasoning stays in the host: understand input → build retrieval intent → search → view the top candidate → visually and semantically audit it → materialize only an accepted template. For attachments, the host makes files available locally and the Agent passes those paths to figure_library_import. For search, the Agent passes compact descriptions, not raw datasets.

figure_library_preview returns standard MCP image content. In Wisp, pass an absolute project-local destination (for example, /project/.wisp/figure-library-previews) and call view_image on the returned path. This keeps visual judgment with the Agent even when the host exposes only the text portion of an MCP tool result.

Example import arguments:

{
  "title": "Our lab volcano plot",
  "description": "Labeled differential-expression volcano plot",
  "tags": ["volcano", "differential expression"],
  "visualProfile": "log2FC x-axis, -log10 FDR y-axis, labeled hits",
  "dataProfile": "gene, log2FC, adjusted p value",
  "imagePath": "/project/references/volcano.png",
  "codePaths": ["/project/references/volcano.R"],
  "license": "Internal lab reference"
}

Supported visual references are PNG, JPEG, WebP, SVG, and PDF (20 MiB maximum). Up to 20 R, R Markdown, Quarto, Python, notebook, Julia, MATLAB, Markdown, TeX, shell, JSON, or YAML files may be imported (5 MiB each, 50 MiB total). Original absolute paths are never stored in the shareable manifest.

Distribution

The standalone npm tarball contains the server, App, FigureYa search catalog, and thumbnails, but not the large archive collection:

npm run package:npm
npm install --global ./release/scientific-figure-library-0.1.1.tgz

Use scientific-figure-library as the MCP command after installation.

For Wisp:

npm run package:wisp

Install release/scientific-figure-library-wisp-0.1.1.zip from Wisp Settings → Plugins, enable it for a project, and start a fresh session.

FigureYa Source Pack

The core plugin and the optional Source Pack are deliberately separate. A Source Pack is an ordinary directory containing the existing per-module ZIPs from FigureYa-compressed:

FigureYaSourcePack/
├── FigureYa59volcanoV2.zip
└── archives/
    └── FigureYa9heatmap.zip

Pass this directory as sourcePackDir or set FIGUREYA_SOURCE_PACK_DIR. Resolution order is:

1. Local Source Pack.
2. Bases configured in FIGUREYA_ARCHIVE_BASE_URLS.
3. The commit-pinned FigureYa-compressed archive on GitHub.

The complete pinned archive collection is roughly 3 GiB, so it is not embedded in either plugin package. It can be copied by USB/shared storage or split into small transport packs:

npm run package:source-pack -- \
  --source /path/to/FigureYa-compressed \
  --name volcano \
  --modules FigureYa59volcanoV2

The helper verifies every selected ZIP and caps one transport pack at 200 MiB. Extract the resulting release/figure-library-source-pack-volcano-0.1.1.zip before use.

Materialized layouts

FigureYa template:

<destination>/<template-id>/
├── upstream/
├── TEMPLATE.md
└── template.lock.json

User template:

<destination>/<template-id>/
├── reference/
│   ├── preview.*
│   └── code/
├── TEMPLATE.md
└── template.lock.json

An existing target is never overwritten. Keep upstream/ or reference/ unchanged and adapt plotting code in a separate file.

Catalog development

The repository includes a generated FigureYa catalog. To regenerate it from local checkouts:

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

License

Project code is MIT licensed. FigureYa-derived catalog data, thumbnails, and downloaded templates remain CC BY-NC-SA 4.0. User-imported material keeps the license supplied at import. See THIRD_PARTY_NOTICES.md.