ZotPilot

https://github.com/xunhe730/zotpilot
Admin
ZotPilot allows AI agents to interact with and understand a Zotero reference library locally,...
Tokens:31,112
Snippets:438
Trust Score:5.4
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Initial ZotPilot Installation and Setup

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Install ZotPilot and perform the initial setup, recommended for getting started.

```bash
pip install zotpilot && zotpilot setup
```

--------------------------------

### Development Setup and Testing

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Clone the repository, install development dependencies, and run tests and checks.

```bash
git clone https://github.com/xunhe730/ZotPilot.git
cd ZotPilot
pip install -e ".[dev]"

zotpilot setup
python -m pytest
python -m ruff check src/ tests/
```

--------------------------------

### Install and Setup ZotPilot

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Install the ZotPilot package and run the setup command for interactive configuration, skill deployment, and MCP registration.

```bash
pip install zotpilot
zotpilot setup                 # interactive config + skill deploy + MCP register
```

--------------------------------

### Example ZotPilot Setup Workflow

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Run a setup workflow to check ZotPilot configuration.

```bash
/ztp-setup check my ZotPilot configuration
```

--------------------------------

### Initial ZotPilot Setup

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Perform an initial non-interactive setup for ZotPilot.

```bash
zotpilot setup --non-interactive --provider gemini
```

--------------------------------

### Example ZotPilot Review Workflow

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Start a review workflow to outline a topic based on existing library papers.

```bash
/ztp-review draft a review outline about X from papers already in my library
```

--------------------------------

### GET /pending Response Example (Command Available)

Source: https://github.com/xunhe730/zotpilot/blob/main/connector/PROTOCOL.md

Example JSON response when a save command is available at the /pending endpoint. Includes request ID, action, URL, and optional collection key and tags.

```json
{
  "request_id": "abc123def456",
  "action": "save",
  "url": "https://arxiv.org/abs/2401.00001",
  "collection_key": "XYZ789",
  "tags": ["ml", "survey"]
}
```

--------------------------------

### GET /pending Request Example

Source: https://github.com/xunhe730/zotpilot/blob/main/connector/PROTOCOL.md

Example of a GET request to the /pending endpoint to retrieve the next save command. The client should send an Accept header for application/json.

```http
GET /pending
Accept: application/json
```

--------------------------------

### Install ZotPilot

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-setup.md

Install ZotPilot using pip or uv. This is the first step if ZotPilot is not already installed.

```bash
pip install zotpilot
```

```bash
uv tool install zotpilot
```

--------------------------------

### Setup ZotPilot with local provider

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

Configure ZotPilot for first-time setup using a fully offline (local) embedding provider.

```bash
python3 scripts/run.py setup --non-interactive --provider local
```

--------------------------------

### Setup ZotPilot and Restart Agent

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Run 'zotpilot setup' to configure ZotPilot and then restart your agent if skills are not showing up or MCP tools are missing.

```bash
zotpilot setup
```

--------------------------------

### Interactive ZotPilot Setup

Source: https://github.com/xunhe730/zotpilot/blob/main/README.md

Run the interactive setup for ZotPilot, which prompts for embedding keys and Zotero User ID/API key. This is the recommended method for interactive use.

```bash
zotpilot setup                         # Interactive: will ask for embedding key and Zotero User ID / API key (can be skipped)
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/xunhe730/zotpilot/blob/main/CONTRIBUTING.md

Clone the ZotPilot repository and install development dependencies using uv.

```bash
git clone https://github.com/xunhe730/ZotPilot.git
cd ZotPilot
uv sync --extra dev
```

--------------------------------

### Setup ZotPilot with Gemini provider

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

Configure ZotPilot for first-time setup using the Gemini embedding provider. Requires a GEMINI_API_KEY.

```bash
python3 scripts/run.py setup --non-interactive --provider gemini
```

--------------------------------

### Setup ZotPilot with DashScope provider

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

Configure ZotPilot for first-time setup using the DashScope/Bailian embedding provider. Requires a DASHSCOPE_API_KEY.

```bash
python3 scripts/run.py setup --non-interactive --provider dashscope
```

--------------------------------

### OCR Setup for Scanned PDFs

Source: https://github.com/xunhe730/zotpilot/blob/main/README.md

Instructions for installing Tesseract OCR on macOS and Ubuntu for processing scanned PDF documents.

```bash
macOS `brew install tesseract tesseract-lang`
Ubuntu `sudo apt install tesseract-ocr`
```

--------------------------------

### Run ZotPilot Setup

Source: https://github.com/xunhe730/zotpilot/blob/main/references/troubleshooting.md

Use this command to run the ZotPilot setup process non-interactively, useful for setting Zotero directory or API keys.

```bash
zotpilot setup --non-interactive
```

```bash
zotpilot setup --non-interactive --zotero-dir /correct/path
```

--------------------------------

### Install ZotPilot

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Install ZotPilot using pip if the 'zotpilot' command is not found.

```bash
pip install zotpilot
```

--------------------------------

### Example ZotPilot Profile Workflow

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Execute a profile workflow to analyze library content before reorganization.

```bash
/ztp-profile show what this library is mostly about before reorganizing it
```

--------------------------------

### Install uv package manager on Windows

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

Use this PowerShell command to install the uv package manager on Windows.

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Refreshing Agent Integrations

Source: https://github.com/xunhe730/zotpilot/blob/main/README.md

If MCP tools or Skills are not appearing, rerun `zotpilot setup` and restart the agent. For advanced users, `zotpilot install` can refresh agent integrations without a full setup.

```bash
zotpilot install
```

--------------------------------

### Connector Development Build

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Install dependencies and build the connector for development.

```bash
cd connector
npm install
./build.sh -d
```

--------------------------------

### Non-interactive Setup for Gemini or Dashscope

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Perform a non-interactive setup for providers like Gemini or Dashscope. This is useful for scripting and automation.

```bash
zotpilot setup --non-interactive --provider gemini             # or dashscope / local
```

--------------------------------

### Install uv package manager on Linux/macOS

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

Use this command to install the uv package manager on Linux or macOS systems.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install ZotPilot Connector Browser Extension

Source: https://github.com/xunhe730/zotpilot/blob/main/CHANGELOG.md

Instructions for installing the ZotPilot Connector browser extension from a GitHub release. This extension allows AI agents to save papers to Zotero with institutional PDF access.

```bash
From [GitHub Release](https://github.com/xunhe730/ZotPilot/releases) 下载 zip，加载到 Chrome 即可
```

--------------------------------

### Start HTTP Bridge Service

Source: https://github.com/xunhe730/zotpilot/blob/main/CHANGELOG.md

Manually start the HTTP bridge service for browser extension integration. Specify the port if needed.

```bash
zotpilot bridge [--port N]
```

--------------------------------

### Install CLI

Source: https://github.com/xunhe730/zotpilot/blob/main/references/troubleshooting.md

If the `zotpilot` command is not found, this command will auto-install the CLI.

```bash
python3 scripts/run.py status
```

--------------------------------

### Verify ZotPilot Installation

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Check the status and health of your ZotPilot installation.

```bash
zotpilot doctor
```

```bash
zotpilot status
```

--------------------------------

### Add a New MCP Tool

Source: https://github.com/xunhe730/zotpilot/blob/main/CONTRIBUTING.md

Example of decorating a function to register it as an MCP tool.

```python
@mcp.tool()
def your_tool_function():
    """Comprehensive docstring for the tool."""
    # Tool implementation here
    pass
```

--------------------------------

### Install uv package manager using pip

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

This command installs the uv package manager using pip, compatible with any platform.

```bash
pip install uv
```

--------------------------------

### Example ZotPilot Research Workflow

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Initiate a research workflow to find, confirm, and ingest papers.

```bash
/ztp-research survey the most important recent papers on X and ingest the worthwhile ones into Zotero
```

--------------------------------

### Check ZotPilot Installation Status

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-setup.md

Use this command to check if ZotPilot is installed and its current status. It can be run before or after installation.

```bash
python scripts/run.py status --json
```

```bash
uv run zotpilot status
```

--------------------------------

### Install 'recover' Extra for uv

Source: https://github.com/xunhe730/zotpilot/blob/main/references/troubleshooting.md

Install the 'recover' extra for uv, which is required for zero-cost index recovery. This may require a C++ compiler if chroma-hnswlib needs to be compiled from source.

```bash
uv sync --extra recover
```

```bash
uv tool install zotpilot --with chroma-hnswlib
```

--------------------------------

### Non-Interactive Setup for Gemini Provider

Source: https://github.com/xunhe730/zotpilot/blob/main/README.md

Perform a non-interactive setup for the Gemini provider. This command is suitable for automated environments where user interaction is not possible.

```bash
# Or
```

```bash
zotpilot setup --non-interactive --provider gemini
```

--------------------------------

### Non-Interactive Setup with API Key and Verification

Source: https://github.com/xunhe730/zotpilot/blob/main/README.md

Set up ZotPilot non-interactively for SiliconFlow, including providing an embedding key and verifying the connection.

```bash
zotpilot setup --non-interactive --provider siliconflow --embedding-key <key> --verify
```

--------------------------------

### Register MCP server with configuration

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

Register the MCP server after configuring the embedding provider and Zotero API details using `setup` or `config set` commands.

```bash
python3 scripts/run.py setup --non-interactive --provider gemini
zotpilot config set gemini_api_key <key>
zotpilot config set zotero_api_key <key>
zotpilot config set zotero_user_id <numeric-id>

python3 scripts/run.py register
```

--------------------------------

### Browse Library Overview

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-profile.md

Use to get an overview of the Zotero library structure. Part of the taxonomy mapping step.

```python
browse_library(view="overview")
```

--------------------------------

### Specify Zotero Directory

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-setup.md

If Zotero is not detected at standard paths, use this flag to explicitly define its directory during setup.

```bash
--zotero-dir /path/to/zotero/data
```

--------------------------------

### ZotPilot File Layout and Data Locations

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Shows the directory structure for ZotPilot installation and the default locations for configuration and ChromaDB indexes on macOS/Linux and Windows.

```text
Installed zotpilot (wheel ships skills + references)
├── src/zotpilot/skills/
├── references/
└── connector/

# Config / index
# macOS / Linux
~/.config/zotpilot/config.json
~/.local/share/zotpilot/chroma/

# Windows
%APPDATA%\zotpilot\config.json
%APPDATA%\zotpilot\chroma\
```

--------------------------------

### Update Zotpilot from Source

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

If Zotpilot was installed from source, navigate to the skill directory and use git pull to fetch the latest changes.

```bash
cd <skill-directory>
git pull
```

--------------------------------

### Non-Interactive Setup for Specific Providers

Source: https://github.com/xunhe730/zotpilot/blob/main/README.md

Configure ZotPilot non-interactively for specific providers like Gemini, DashScope, or local models. This is useful for scripting and automated setups.

```bash
zotpilot setup --non-interactive --provider gemini
```

```bash
# Or dashscope / local
```

--------------------------------

### Upgrade ZotPilot

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-setup.md

Run this command to upgrade an existing ZotPilot installation to the latest version. This is part of the upgrade workflow.

```bash
zotpilot upgrade
```

--------------------------------

### Verifying ZotPilot Installation and Configuration

Source: https://github.com/xunhe730/zotpilot/blob/main/README.md

Use `zotpilot doctor` to diagnose configuration, environment, and MCP registration issues. `zotpilot status` shows the indexing status.

```bash
zotpilot doctor     # Diagnose configuration / environment / MCP registration
```

```bash
zotpilot status     # Indexing status
```

--------------------------------

### Custom OpenAI-Compatible Endpoint Setup

Source: https://github.com/xunhe730/zotpilot/blob/main/README.md

Configure ZotPilot to use a custom OpenAI-compatible endpoint, specifying the base URL, embedding model, and dimensions. This is useful for self-hosted or specific cloud endpoints.

```bash
zotpilot setup --non-interactive --provider custom \
  --embedding-base-url http://localhost:11434/v1 \
  --embedding-model nomic-embed-text --embedding-dimensions 768
```

--------------------------------

### Configuration Management CLI

Source: https://github.com/xunhe730/zotpilot/blob/main/CHANGELOG.md

Manage ZotPilot configuration settings using the `config` CLI subcommand. Supports set, get, list, unset, and path operations.

```bash
config set / get / list / unset / path
```

--------------------------------

### List Available Embedding Vendors

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-setup.md

Discover available embedding vendors and their models. This command is safe to run before ZotPilot is fully configured and does not require a Zotero installation.

```bash
zotpilot setup --list-vendors --json
```

```bash
zotpilot setup --list-vendors
```

--------------------------------

### Configure ZotPilot Non-Interactively

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-setup.md

Configure ZotPilot non-interactively using command-line arguments. This is useful for automated setups or shared machines. The --verify flag performs a self-check.

```bash
zotpilot setup --non-interactive --provider <vendor> [--embedding-model <model>] [--embedding-key <key>] --verify
```

--------------------------------

### Update Zotpilot CLI and Skill

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

Run this command to update both the Zotpilot command-line interface and its associated skill files. Use the --check flag to see if an update is available without installing.

```bash
zotpilot update
```

--------------------------------

### Perform Initial Indexing

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-setup.md

Run an initial index of your data. The --limit flag is used here for a quick first-time index.

```bash
zotpilot index --limit 20
```

--------------------------------

### Set Zotero API Key and Register

Source: https://github.com/xunhe730/zotpilot/blob/main/references/troubleshooting.md

Configure the Zotero API key for write operations and then register the client.

```bash
zotpilot config set zotero_api_key <key>
```

```bash
zotpilot register
```

--------------------------------

### Index Pipeline Overview

Source: https://github.com/xunhe730/zotpilot/blob/main/ARCHITECTURE.md

Illustrates the flow of data from Zotero SQLite through various processing stages to the ChromaDB vector store.

```text
Zotero SQLite
      │
      ▼
  zotero_client.py    Read-only access to Zotero's EAV schema
      │
      ▼
  indexer.py           Orchestrates extraction → chunking → embedding → storage
      │
      ├──► pdf/extractor.py     Text + table + figure extraction (pymupdf4llm + pymupdf-layout)
      │        ├── chunker.py              Section-aware text chunking with overlap
      │        ├── section_classifier.py   Heading → section label mapping
      │        ├── orphan_recovery.py      Caption recovery for unmatched figures/tables
      │        └── reference_matcher.py    Maps tables/figures to citing text chunks
      │
      ├──► feature_extraction/   Vision-based table extraction (optional)
      │        ├── vision_api.py           Anthropic Batch API for table cells
      │        ├── paddle_extract.py       PaddleOCR alternative
      │        └── captions.py             Caption detection from PDF blocks
      │
      ├──► embeddings/           Text → vector conversion
      │        ├── gemini.py               Gemini API (asymmetric, 768d)
      │        └── local.py                ChromaDB default (symmetric, 384d)
      │
      └──► vector_store.py       ChromaDB persistent storage
```

--------------------------------

### List All Vendors and Models

Source: https://github.com/xunhe730/zotpilot/blob/main/README.md

Use this command to list all available vendors and their supported embedding models. The `--json` flag can be used for machine-readable output.

```bash
zotpilot setup --list-vendors [--json]
```

--------------------------------

### Get Status

Source: https://github.com/xunhe730/zotpilot/blob/main/connector/PROTOCOL.md

This endpoint provides a health check and connectivity status for the bridge. It is exempt from the Origin ACL.

```http
GET /status
```

--------------------------------

### Upgrade Zotpilot via pip

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

If Zotpilot was installed using pip, use this command to upgrade it to the latest version.

```bash
pip install --upgrade zotpilot
```

--------------------------------

### Register Zotero clients

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

Sync detected Zotero clients after configuring the Zotero API key and User ID.

```bash
python3 scripts/run.py register
```

--------------------------------

### Run Code Style Checks and Formatting

Source: https://github.com/xunhe730/zotpilot/blob/main/CONTRIBUTING.md

Use ruff for checking code style and formatting the source code.

```bash
uv run ruff check src/
```

```bash
uv run ruff format src/
```

--------------------------------

### Verify ZotPilot Health

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-setup.md

Check the overall health of your ZotPilot installation. This command performs a comprehensive health verification.

```bash
zotpilot doctor
```

--------------------------------

### Register ZotPilot with Zotero Credentials

Source: https://github.com/xunhe730/zotpilot/blob/main/references/troubleshooting.md

Enable write operations by registering ZotPilot with your Zotero User ID and API key. Ensure you have created a key with 'Allow library access' and 'Allow write access' on the Zotero website.

```bash
claude mcp remove zotpilot
zotpilot config set zotero_user_id <id>
zotpilot config set zotero_api_key <key>
zotpilot register
```

--------------------------------

### Safari Popover Initialization and Event Handling

Source: https://github.com/xunhe730/zotpilot/blob/main/connector/src/safari/popoverTranslatorSelector.html

This script initializes the Zotero connector's popover menu in Safari. It sets up event listeners for saving web pages with or without snapshots, saving PDFs, and opening Zotero preferences. The code dynamically adjusts the displayed save options based on whether the active tab is a PDF and if automatic snapshots are enabled.

```javascript
(function () {
    document.getElementById('zotero-preferences').onclick = function() {
        var Zotero_Connector_Browser = safari.extension.globalPage.contentWindow.Zotero.Connector_Browser;
        Zotero_Connector_Browser.openTab(`${safari.extension.baseURI}safari/` + "preferences/preferences.html");
        safari.self.hide();
    };

    function saveAsWebpage(snapshot=true) {
        var Zotero_Connector_Browser = safari.extension.globalPage.contentWindow.Zotero.Connector_Browser;
        Zotero_Connector_Browser.saveAsWebpage(
            Zotero_Connector_Browser.activeTab,
            { snapshot }
        );
        safari.self.hide();
    }

    var saveWithSnapshotElem = document.getElementById('zotero-save-page-with-snapshot');
    var saveWithoutSnapshotElem = document.getElementById('zotero-save-page-without-snapshot');
    var savePDFElem = document.getElementById('zotero-save-PDF');

    saveWithSnapshotElem.onclick = saveAsWebpage;
    savePDFElem.onclick = saveAsWebpage;
    saveWithoutSnapshotElem.onclick = saveAsWebpage.bind(this, [false]);

    safari.application.addEventListener('popover', function (event) {
        var Zotero = safari.extension.globalPage.contentWindow.Zotero;
        var tab = Zotero.Connector_Browser.activeTab;

        setTimeout(function () {
            safari.self.height = document.documentElement.offsetHeight;
            let width = 0;
            let aElems = document.getElementsByTagName('a');
            for (let i = 0; i < aElems.length; i++) {
                if (aElems[i].offsetWidth > width) {
                    width = aElems[i].offsetWidth;
                }
            }
            safari.self.width = width + 40;
        });

        let translatorElems = document.getElementsByClassName('translator');
        for (let i = translatorElems.length-1; i >= 0; i--) {
            let li = translatorElems[i];
            li.parentNode.removeChild(li);
        }

        var withSnapshot = Zotero.Connector.isOnline ? Zotero.Connector.automaticSnapshots : Zotero.Prefs.get('automaticSnapshots');
        if (withSnapshot) {
            document.getElementsByTagName('menu')[0]
                .insertBefore(saveWithSnapshotElem, saveWithoutSnapshotElem);
        } else {
            document.getElementsByTagName('menu')[0]
                .insertBefore(saveWithoutSnapshotElem, saveWithSnapshotElem);
        }

        var isPDF = tab.contentType == 'application/pdf' || tab.isPDFFrame;
        saveWithoutSnapshotElem.style.display = isPDF ? 'none' : null;
        saveWithSnapshotElem.style.display = isPDF ? 'none' : null;
        savePDFElem.style.display = isPDF ? null : 'none';

        var translators = tab.translators;
        if (!translators || event.target.identifier != 'zotero-translatorSelector') return;

        var menu = document.getElementsByTagName('menu')[0];
        var savePage = menu.firstChild;
        var Zotero = safari.extension.globalPage.contentWindow.Zotero;

        for (let i = 0; i < translators.length; i++) {
            let translator = translators[i];
            let li = document.createElement('li');
            li.classList.add('translator');
            let a = document.createElement('a');
            a.setAttribute('href', 'javascript:void(0);');
            a.textContent = `${Zotero.getString('general_saveTo', 'Zotero')} (${translator.label})`;
            li.onclick = function () {
                Zotero.Connector_Browser.saveWithTranslator(
                    tab,
                    i
                );
                safari.self.hide();
            };
            li.appendChild(a);
            menu.insertBefore(li, savePage);
        }
    });
})();
```

--------------------------------

### GET /result/<request_id>

Source: https://github.com/xunhe730/zotpilot/blob/main/connector/PROTOCOL.md

Clients poll this endpoint to retrieve the results of previously enqueued save commands using the `request_id`.

```APIDOC
## GET /result/<request_id>

### Description
Clients poll for results after enqueueing.

### Method
GET

### Endpoint
/result/{request_id}

### Parameters
#### Path Parameters
- **request_id** (string) - Required - The ID of the request to check.

### Response
#### Success Response (200)
- **request_id** (string) - The ID of the request.
- **success** (boolean) - Indicates if the operation was successful.
- **url** (string) - The URL associated with the request.
- **title** (string) - The title of the saved item.
- **item_key** (string | null) - The Zotero item key, if available.
- **collection_key** (string | null) - The collection key, if available.
- **tags** (string[]) - The tags associated with the item, if available.
- **warning** (string) - Optional - A warning message, e.g., if collection/tags could not be applied.

#### Response Example (200)
```json
{
  "request_id": "abc123def456",
  "success": true,
  "url": "https://arxiv.org/abs/2401.00001",
  "title": "A Neural Network for Everything",
  "item_key": null,
  "warning": "collection_key/tags not applied — item not found in Zotero within discovery window"
}
```

#### Success Response (204 — result not yet available)
No body is returned when the result is not yet available.
```

--------------------------------

### ZotPilot Indexing and Querying Workflow

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Illustrates the data flow for indexing Zotero libraries and processing queries. Indexing is a one-off process, while queries are handled on each call.

```text
Indexing (one-off)
Zotero SQLite ──→ PDF extraction ──→ chunking + section classification ──→ embeddings ──→ ChromaDB

Queries (every call)
Agent ──→ MCP tools ───┬── semantic search ──→ ChromaDB ──→ section-aware reranking
                       ├── citation graph  ──→ OpenAlex
                       ├── library browse  ──→ Zotero SQLite (read-only)
                       ├── write ops       ──→ Zotero Web API ──→ sync back to Zotero
                       └── ingestion       ──→ Bridge + Connector ──→ Zotero Desktop
```

--------------------------------

### GET /status

Source: https://github.com/xunhe730/zotpilot/blob/main/connector/PROTOCOL.md

Provides a health check and connectivity status of the ZotPilot bridge. This endpoint is exempt from the Origin ACL for external health probes.

```APIDOC
## GET /status

### Description
Health check and connectivity status. Exempt from the Origin ACL so non-browser health probes can check bridge state without attaching an Origin header.

### Method
GET

### Endpoint
/status

### Response
#### Success Response (200)
- **bridge** (string) - Always `"running"` if the server is up.
- **port** (integer) - The actual port the server is listening on.
- **extension_connected** (boolean) - `true` if a heartbeat was received in the last 30s.
- **extension_last_seen_s** (float) - Seconds since the last heartbeat (omitted if never connected).
- **extension_version** (string) - Version from the last heartbeat (omitted if never connected).
- **zotero_running** (boolean) - From the last heartbeat (omitted if never connected).

#### Response Example (200)
```json
{
  "bridge": "running",
  "port": 2619,
  "extension_connected": true,
  "extension_last_seen_s": 3.2,
  "extension_version": "0.0.2",
  "zotero_running": true
}
```
```

--------------------------------

### Register Zotero with API key and User ID as flags

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

Register Zotero clients by passing the API key and User ID directly as command-line flags. This is a compatibility path for automation.

```bash
python3 scripts/run.py register --zotero-api-key <key> --zotero-user-id 12345678
```

--------------------------------

### Configure DashScope Provider

Source: https://github.com/xunhe730/zotpilot/blob/main/references/troubleshooting.md

Set up ZotPilot to use the DashScope embedding provider non-interactively.

```bash
zotpilot setup --non-interactive --provider dashscope
```

--------------------------------

### Check for Zotpilot Update

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

Use the --check flag with the update command to determine if a new version of Zotpilot is available without performing the installation.

```bash
zotpilot update --check
```

--------------------------------

### Get Annotations for Deep Dive Analysis

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-profile.md

Retrieves annotations from library items. Requires a remote ZOTERO_API_KEY. If the key is missing, this step should be gracefully skipped.

```python
get_annotations()
```

--------------------------------

### Set Environment Variables for API Keys and Base URLs

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Configure API keys and optional base URLs using environment variables. These variables take precedence over local configuration files.

```bash
export GEMINI_API_KEY=<your-key>           # or DASHSCOPE_API_KEY
export ANTHROPIC_API_KEY=<your-key>        # optional: complex-table vision extraction
export GEMINI_BASE_URL=<https-proxy>       # optional: custom Gemini endpoint (proxy / restricted region)
```

--------------------------------

### Enable Zotero Write Operations

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Configure Zotero user ID and API key for write operations. Includes a command to migrate legacy secrets.

```bash
zotpilot config set zotero_user_id 12345678
```

```bash
zotpilot config set zotero_api_key YOUR_KEY
```

```bash
zotpilot setup
```

```bash
zotpilot doctor
```

```bash
zotpilot config migrate-secrets
```

--------------------------------

### Manual ZotPilot Update

Source: https://github.com/xunhe730/zotpilot/blob/main/CHANGELOG.md

Instructions for manually updating ZotPilot using package managers.

```bash
uv tool upgrade zotpilot
pip install --upgrade zotpilot
```

--------------------------------

### Register MCP server with CLI flags

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

Register the MCP server by passing AI provider keys and Zotero credentials directly as command-line flags. This is a compatibility path for automation.

```bash
python3 scripts/run.py register \
  --gemini-key <key> \
  --zotero-api-key <key> \
  --zotero-user-id <numeric-id>
```

--------------------------------

### Updating ZotPilot Configuration

Source: https://github.com/xunhe730/zotpilot/blob/main/README.md

Modify existing ZotPilot configurations using the `config set` command. This allows for updating API keys, user IDs, and other settings after the initial setup.

```bash
zotpilot config set gemini_api_key <key>
```

```bash
zotpilot config set zotero_user_id <id>
```

```bash
zotpilot config set zotero_api_key <key>
```

```bash
zotpilot setup
```

--------------------------------

### Save URLs - Slow Publisher (Cambridge Core)

Source: https://github.com/xunhe730/zotpilot/blob/main/docs/e2e-scenarios/scenarios.md

Tests item_key discovery for a slow publisher like Cambridge Core, expecting successful discovery after potential exponential backoff. Requires an institutional subscription.

```python
save_urls(["<当前可访问的 Cambridge Core 文章 URL>"], tags=["e2e-test"])
```

--------------------------------

### Enabling Write Operations with Zotero API Keys

Source: https://github.com/xunhe730/zotpilot/blob/main/README.md

Configure Zotero User ID and API key for write operations like adding tags, collections, or notes. Ensure the API key has 'Allow library access' and 'Allow write access' permissions.

```bash
zotpilot config set zotero_user_id 12345678
```

```bash
zotpilot config set zotero_api_key YOUR_KEY
```

```bash
zotpilot setup
```

```bash
zotpilot doctor
```

--------------------------------

### Set Gemini API Key

Source: https://github.com/xunhe730/zotpilot/blob/main/README_EN.md

Export your GEMINI_API_KEY or switch to local provider if the key is not set.

```bash
export GEMINI_API_KEY=<key>
```

--------------------------------

### Get Notes for Deep Dive Analysis

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-profile.md

Retrieves notes associated with library items, useful for identifying hidden themes when note density is high. Part of the optional deep dive step.

```python
get_notes()
```

--------------------------------

### Example JSON Payload Structure for annotate_pdf

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-tutor.md

This JSON structure is used to pass annotation data to the annotate_pdf tool via a temporary file. It includes the final list of annotations and an overview dictionary.

```json
{
  "annotations": [ ...the final list from Steps 3–7... ],
  "overview":    { ...the dict from Step 5... }
}
```

--------------------------------

### Register MCP Tools with Claude Code (Serve Command)

Source: https://github.com/xunhe730/zotpilot/blob/main/references/troubleshooting.md

Register ZotPilot's MCP serve command with Claude Code to use the current model.

```bash
claude mcp add -s user zotpilot -- zotpilot mcp serve
```

--------------------------------

### GET /pending

Source: https://github.com/xunhe730/zotpilot/blob/main/connector/PROTOCOL.md

The ZotPilot Connector extension polls this endpoint every 2 seconds to retrieve the next pending save command. It returns a command object if available, or a 204 No Content response if the queue is empty.

```APIDOC
## GET /pending

### Description
Extension polls this endpoint every 2 seconds. Returns the next pending save command, or `204 No Content` if the queue is empty.

### Method
GET

### Endpoint
/pending

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **request_id** (string) - Opaque identifier for this save; must be echoed in the result
- **action** (string) - `"save"` or `"preflight"`
- **url** (string) - URL to open and save
- **collection_key** (string | null) - Optional. Zotero collection key to place the item in
- **tags** (string[]) - Optional. Tags to apply to the item

#### Response Example (200)
```json
{
  "request_id": "abc123def456",
  "action": "save",
  "url": "https://arxiv.org/abs/2401.00001",
  "collection_key": "XYZ789",
  "tags": ["ml", "survey"]
}
```

#### Success Response (204)
No Content

#### Response Example (204)
```
No body
```

#### Error Handling
- **400** `{"error": "invalid_command", "reason": "..."}` - If command validation fails on the extension side (defense-in-depth).
```

--------------------------------

### Upgrade ZotPilot and Reinstall

Source: https://github.com/xunhe730/zotpilot/blob/main/CHANGELOG.md

Upgrade the ZotPilot package and reinstall to apply changes to tool signatures. This is a mandatory step after upgrading.

```bash
pip install --upgrade zotpilot     # 或 uv tool upgrade zotpilot
zotpilot install                   # 必须：工具签名变了，需重新注册
```

--------------------------------

### List Registered MCP Tools

Source: https://github.com/xunhe730/zotpilot/blob/main/references/troubleshooting.md

Verify that ZotPilot has been successfully registered as an MCP tool in Claude Code.

```bash
claude mcp list
```

--------------------------------

### Index User Papers

Source: https://github.com/xunhe730/zotpilot/blob/main/references/setup-guide.md

Run this command to index the user's papers. Indexing speed is approximately 2-5 seconds per paper. Documents exceeding 40 pages are skipped by default.

```bash
python3 scripts/run.py index
```

--------------------------------

### ZotPilot Upgrade Command Options

Source: https://github.com/xunhe730/zotpilot/blob/main/README.md

Provides various options for the zotpilot upgrade command to control the upgrade process, such as checking versions, dry runs, or targeting specific components.

```bash
upgrade or update (no arguments)
--check
--dry-run
--cli-only
--skill-only
--re-register
--migrate-secrets
```

--------------------------------

### Index Documents

Source: https://github.com/xunhe730/zotpilot/blob/main/references/troubleshooting.md

Index documents for ZotPilot. Use `--limit` for testing or batching.

```bash
zotpilot index --limit 10
```

```bash
zotpilot index
```

--------------------------------

### Save URLs - Standard Translator (arXiv)

Source: https://github.com/xunhe730/zotpilot/blob/main/docs/e2e-scenarios/scenarios.md

Tests the discovery of item_key using a standard translator path for arXiv URLs. Requires ZOTERO_API_KEY to be configured.

```python
save_urls(["https://arxiv.org/abs/2301.07041"], tags=["e2e-test"])
```

--------------------------------

### Register MCP or Skill

Source: https://github.com/xunhe730/zotpilot/blob/main/src/zotpilot/skills/ztp-setup.md

Use this command for MCP registration and skill deployment. It can also be used for advanced repair scenarios.

```bash
zotpilot install
```

```bash
zotpilot register
```
Tokens:
Raw