# Scientific Figure Library quickstart

SFL is a **local-first** stdio MCP server with an optional MCP App. You bind one Library
directory on disk, publish reviewed figure+code Releases there, then search and
materialize those exact templates into projects. It never executes plotting
code.

Optional extra catalogs may be enabled later. They do not replace the local
Library.

## Requirements

- Node.js 22 or newer
- An MCP host: Wisp Science, Claude Science, Codex, Claude Code, Cursor, Pi, DeepSeek Harness (dsh), or any stdio client

## From source

```bash
git clone https://github.com/xuzhougeng/ScientificFigureLibrary.git
cd ScientificFigureLibrary
npm ci
npm run check
```

```json
{
  "mcpServers": {
    "figure-library": {
      "command": "node",
      "args": ["/absolute/path/to/ScientificFigureLibrary/dist/index.js"]
    }
  }
}
```

`FIGURE_LIBRARY_DIR` overrides the user locator (admin only).

## Wisp Science

```bash
npm run package:wisp
```

Install the generated ZIP from `release/` in **Settings → Plugins**, enable it
for the project, and start a new session.

For maintainers, packaging also emits a [Wisp update feed](WISP_UPDATES.md).
This is a release-side prerequisite; current Wisp installation steps still apply.

## Cursor

```bash
npm run package:cursor
```

Unzip the generated Cursor ZIP from `release/` so this file exists:

`~/.cursor/plugins/local/figure-library/.cursor-plugin/plugin.json`

The same folder must also contain plugin-root `mcp.json`, `dist/index.js`, and
`skills/`. Restart Cursor. Cursor's official marketplace is Git-based; this ZIP
is the local plugin path.

## Pi

```bash
pi install npm:pi-mcp-adapter
pi install npm:scientific-figure-library
```

Restart Pi. The package loads the `figure-library` Skill and registers the
stdio MCP server through pi-mcp-adapter. Install from npm, not from a GitHub
URL: git checkouts do not include `dist/index.js`. If you already connected
the local SFL app with a copied MCP config, do not also install the npm
package — that duplicates tools.

From a local checkout after `npm run build` (development only):

```bash
pi install npm:pi-mcp-adapter
pi install /absolute/path/to/ScientificFigureLibrary
```

## DeepSeek Harness (dsh)

```bash
dsh plugin --profile web add scientific-figure-library
```

Restart the profile (`dsh --profile web` or `dsh web`). Install from npm, not
`github:xuzhougeng/ScientificFigureLibrary`: git checkouts do not include
`dist/index.js`. The bundle registers the Skill and mounts
`@deepseek-ai/dsh-mcp-client` against this package. Swap `web` for another
profile if needed. If you already connected the local SFL app with a profile
patch, do not also add the npm package.

## Ordinary MCP host (App optional)

After registering the stdio server, ask the host to call
`figure_library_get_skill` with no arguments. It returns the same core Skill
and a list of on-demand references; use their exact `document` IDs to read more.
You may instead install `skills/figure-library/` as a single local Skill. Keep
its reference files together. The other guidance topics are not separate Skills.

After setup, use `figure_library_search` to get candidate IDs and thumbnail URIs.
Call `figure_library_get_candidate_images` for the current page, or read its
thumbnail resources using MCP. Present those images with their candidate labels.
Use `figure_library_search_page` with the returned result set and cursor when
the user requests another page.

After selection, use `figure_library_preview_exact_headless` and
`figure_library_confirm_selection_headless`, then review and approve the normal
materialization Plan/Apply. Keep the same MCP connection throughout. Thumbnail
reads cannot replace exact preview confirmation. Host image display support
requires verification in the actual host; MCP resource URIs are not browser URLs.

## First session

1. Call `figure_library_open` or `figure_library_source_status`. A new install
   returns `setup_required` until both roots exist.
2. If setup is required, ask for two absolute directories: the global Library
   (绘图仓库) and the Local workspace (本地工作区). Do not use the current
   project folder unless the user names it. Plan/Apply
   `figure_library_plan_bind_global` and `figure_library_plan_bind_workspace`
   after the user confirms each path.
3. Import a figure/code pair if the local library is empty, review it, and
   publish a Release.
4. After both binds succeed, call `figure_library_open` or
   `figure_library_search` against Local Published.
5. Wait for the user to confirm one exact card.
6. Materialize only after a preview receipt: `figure_library_plan_materialize`
   then `figure_library_apply_materialize`.

Full contract: [PROTOCOL.md](PROTOCOL.md).