Metadata-Version: 2.4
Name: zotbridge
Version: 1.2.0
Summary: A Zotero integration layer for agents, apps, and scripts, with Web API sync, HTTP/MCP access, semantic search over libraries, and recoverable headless state.
Author: Robin Rademacher
License-Expression: MIT
Project-URL: Homepage, https://github.com/robinradx/zotbridge
Project-URL: Repository, https://github.com/robinradx/zotbridge
Project-URL: Issues, https://github.com/robinradx/zotbridge/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.8
Requires-Dist: questionary>=2.1.0
Requires-Dist: rich>=14.0.0
Requires-Dist: typer>=0.24.0
Dynamic: license-file

# zotbridge

zotbridge is a Zotero integration layer for agents, apps, and scripts, with Web API sync, HTTP/MCP access, semantic search over libraries, and recoverable headless state. It keeps the local project surface small:

- canonical SQLite store
- Zotero Web API sync for personal and group libraries
- HTTP API and MCP server for tool-capable clients
- qmd-backed semantic search over exported Markdown
- skills for clients that support them
- recovery snapshots for canonical state and derived artifacts

It no longer ships a Zotero Desktop helper, reads or writes `zotero.sqlite`, or bundles native client plugin projects.

## Current Zotero Baseline

The current tracked Zotero baseline is Zotero `9.0.5`, released June 10, 2026. The runtime avoids depending on Zotero Desktop internals so routine Zotero Desktop changes should not force project updates. Zotero 9 citation-key fields are preserved in normalized item payloads where present, and remote writes use the Web API.

## Install

```bash
uv tool install zotbridge
# or, from a checkout:
uv run --no-editable zotbridge version
```

Useful entry points:

```bash
zotbridge                 # human-oriented CLI
zotbridge raw ...         # strict JSON/machine-friendly commands
zotbridge-daemon serve    # HTTP API daemon
zotbridge-mcp             # MCP stdio server
```

## Setup

Run the wizard:

```bash
zotbridge setup start
```

Or configure directly:

```bash
zotbridge config init \
  --api-key "$ZOTERO_API_KEY" \
  --remote-library-id user:123456 \
  --default-library-id user:123456
```

Discover and sync remote libraries:

```bash
zotbridge raw sync discover
zotbridge raw sync pull --library user:123456
```

## Integration

Use MCP setup when a client can call MCP tools:

```bash
zotbridge setup add codex --scope user
zotbridge setup add claude-code --scope project
zotbridge setup add cursor --scope project
zotbridge setup add json
```

Use skills when a client supports them:

```bash
zotbridge skill install codex
zotbridge skill install claude-code
zotbridge skill install cline
zotbridge skill export claude-desktop
```

There is no native client plugin install/update flow. The intended distribution boundary is the Python runtime plus MCP/HTTP config and skills.

## Runtime

Start the API daemon:

```bash
zotbridge-daemon serve --host 127.0.0.1 --port 23119 --sync-interval 300
```

Useful endpoints:

- `GET /health`
- `GET /capabilities`
- `GET /daemon/status`
- `GET /libraries`
- `GET /libraries/{library_id}/items`
- `POST /sync/discover`
- `POST /sync/pull`
- `POST /sync/push`
- `POST /recovery/snapshots`

## Search

Export Markdown and query through qmd:

```bash
zotbridge qmd export --library user:123456
zotbridge qmd query "retrieval augmented generation"
zotbridge qmd vsearch "semantic search over papers"
zotbridge qmd get "<target-from-result>"
```

Use qmd for discovery and related-work retrieval, then `qmd get` to recover the exported source behind a useful hit. Use direct API/CLI/MCP reads for exact item keys, collections, and authoritative metadata.

## Recovery

Create and inspect snapshots:

```bash
zotbridge recovery snapshot-create --reason before-large-sync
zotbridge recovery snapshot-list
zotbridge recovery restore-plan --snapshot <snapshot_id>
```

Execute a restore only with explicit confirmation:

```bash
zotbridge recovery restore-execute --snapshot <snapshot_id> --confirm
```

For remote libraries, optionally push restored pending changes through the Zotero Web API:

```bash
zotbridge recovery restore-execute --snapshot <snapshot_id> --library user:123456 --push-remote --confirm
```

## Project Layout

- `src/zotbridge/core/`: canonical store and change model
- `src/zotbridge/adapters/web_sync.py`: Zotero Web API sync adapter
- `src/zotbridge/api.py`: HTTP API
- `src/zotbridge/mcp.py`: MCP stdio server
- `src/zotbridge/agent_setup.py`: MCP config and skill installers
- `src/zotbridge/recovery.py`: snapshots and restore flow
- `tests/`: Python runtime and integration tests
- `docs/`: focused CLI, API, MCP, skills, sync, and recovery docs

## Removed Surface

The desktop/helper/plugin surface has been intentionally removed:

- no bundled Zotero Desktop helper workflow
- no local `zotero.sqlite` adapter
- no `/local/*` HTTP API routes
- no `zotero_local_*` MCP tools
- no plugin install/update commands
- no packaged client plugin bundles

This keeps the project lighter and better isolated from Zotero Desktop internals.

## Verification

```bash
uv run pytest -q
```
