# Zotero Web MCP

Локальный MCP-сервер для Claude Desktop поверх **официального Zotero Web API v3**.
Собственная реализация, не форк стороннего Zotero MCP. **Node.js 22+, без npm-зависимостей, без сборки.**

```text
Claude Desktop → stdio → node src/server.mjs → HTTPS → api.zotero.org
                                                   ↕ синхронизация
                                               Zotero Desktop
```

**Статус: 0.1.0, первоначальная реализация для проверки на тестовой коллекции.**
Модульные тесты, тесты защиты и запуск реального MCP-процесса проверяются автоматически.
Работа с настоящим аккаунтом Zotero, настоящие загрузки файлов и установка в Windows/Claude Desktop еще требуют проверки. Нельзя считать успешные mock-тесты подтверждением этих интеграций.

## Быстрая установка в Windows

1. Проверьте `node --version`: нужна версия **22 или новее**.
2. Скачайте/распакуйте исходники в постоянную папку. После публикации в GitHub вместо ZIP можно использовать `git clone <URL-репозитория>`.
3. В аккаунте Zotero создайте **отдельный API key**: <https://www.zotero.org/settings/keys>. Дайте доступ к нужной библиотеке, заметкам, файлам и записи. Не включайте все группы без необходимости.
4. Полностью закройте Claude Desktop, включая значок в системном трее.
5. Запустите `setup-windows.cmd`. Вставьте ключ в **скрытое поле терминала**, выберите папку обмена, подтвердите запись.
6. Откройте Claude Desktop заново и проверьте инструмент `zotero_status`.

`setup-windows.cmd` последовательно выполняет настройку, реальную проверку чтения библиотеки и добавление **только** записи `zotero-web` в конфигурацию Claude. Предварительно создается резервная копия. Другие MCP, в том числе Obsidian, не заменяются.

**`npm install`, `npx`, Python, Docker, VPS и открытый сетевой порт не нужны.**
Node запускается непосредственно. `npm` используется только как удобный запускатель локальных скриптов; его тоже можно обойти.

Пошаговая инструкция, настройка вручную, тесты и устранение ошибок: **[Windows setup](docs/WINDOWS-SETUP.ru.md)**.

## Что реализовано

28 инструментов дают доступ к библиотечным операциям API, а не только к нескольким полям:

- поиск и чтение записей, коллекций, тегов, заметок и аннотаций; пагинация, версии, сортировка и документированные фильтры;
- создание и изменение записей всех поддерживаемых Zotero типов через editable JSON, авторов, связей, коллекций/подколлекций, тегов и сохраненных поисков;
- пакетные операции до 50 объектов с отдельным отчетом об успехах и ошибках;
- чтение/запись синхронизированного полнотекстового индекса, экспорт BibTeX/BibLaTeX, CSL JSON, RIS и других поддерживаемых форматов;
- загрузка локальных файлов в Zotero Storage, скачивание доступных облачных вложений, замена с проверкой MD5 и продвинутый binary-diff upload;
- корзина, восстановление, постоянное удаление и синхронизируемые настройки с дополнительными ограничениями;
- поиск **кандидатов** в дубликаты без автоматического объединения.

Полный список, соответствие конечным точкам и ограничения: **[CAPABILITIES](docs/CAPABILITIES.md)**.

Это **не** заявление о полном совпадении с любым общественным Zotero MCP и не универсальный доступ ко всем сервисам Zotero. Здесь нет GUI-управления, самостоятельного поиска PDF у издателей, OCR, семантического векторного индекса, автоматического DOI-распознавания или нативного merge дубликатов. Аккаунты, создание/удаление API-ключей, участники групп и платежи не управляются.

## Где хранится ключ

На Windows: `%APPDATA%\zotero-web-mcp\config.json`.

Ключ находится **вне репозитория**, в локальном JSON с ограничением прав доступа. Файл **не зашифрован**. В конфигурацию Claude помещается только путь к нему, не сам ключ. Установщик получает цифровой User ID через авторизованный `keys/current`; вручную переписывать его не требуется.

В `src/` нет инструментов оболочки, запуска программ или чтения произвольных URL. Входящие HTTP-подключения не принимаются; телеметрии и автообновления нет. Для обмена файлами используется отдельная папка, а не весь диск. HTTPS-ключ отправляется только `api.zotero.org`; хранилище файлов получает только выданные Zotero параметры загрузки.

Это ограничения данного MCP, **не песочница для всех остальных инструментов Claude**. Подробнее: **[SECURITY](SECURITY.md)**.

## Опасные операции

Постоянное удаление, перемещение в корзину, PUT-перезапись объекта, публикационный статус и изменение синхронизированных настроек сначала создают локальный план. `dryRun: true` позволяет подготовить план и для обычной записи.

Человек проверяет план в терминале:

```powershell
npm.cmd run approve -- <planId>
```

Затем вручную вводит полный ID плана и просит Claude вызвать `zotero_execute_plan`. Подтверждение привязано к содержимому, действует 30 минут и используется однократно. Сам MCP не предоставляет Claude инструмента одобрения. Нельзя поручать другому агентному shell-инструменту выполнять это одобрение за человека.

Обычные добавления/правки/импорт при разрешенной записи выполняются без локального подтверждения. Они тоже могут ошибочно изменить важные данные: читайте [модель безопасности](SECURITY.md), используйте тестовую коллекцию и резервную копию Zotero до массовой обработки.

## Команды

```powershell
npm.cmd run setup
npm.cmd run doctor
npm.cmd run install:claude
npm.cmd test
npm.cmd run check
```

Эквиваленты без npm:

```powershell
node scripts/setup.mjs
node scripts/doctor.mjs
node scripts/install-claude.mjs
node scripts/test.mjs
node scripts/check.mjs
```

`npm.cmd run uninstall:claude` удаляет только запись подключения. Приватный конфиг и библиотека не удаляются. Чтобы окончательно отозвать доступ, отзовите ключ в Zotero; затем удалите локальный конфиг самостоятельно.

## Claude, Obsidian и Overleaf

Skill не нужен для самого подключения: инструменты содержат схемы и описания. Дополнительный необязательный skill лежит в `skills/zotero-library/SKILL.md`.
Пример небольшого дополнения к общим инструкциям: [CLAUDE-INSTRUCTIONS.ru.txt](docs/CLAUDE-INSTRUCTIONS.ru.txt).
Не заменяйте им существующие правила Obsidian или Overleaf. PDF/записи остаются в Zotero, итоговые рабочие заметки — в Obsidian, `.bib` и документ — в Overleaf по задаче пользователя.

## Разработка и проверка

Собственный минимальный JSON-RPC/MCP stdio transport реализует initialization, ping, tools/list, tools/call и отмену запросов. Объявляются только поддерживаемые capabilities. Ресурсы, sampling, tasks, HTTP transport и полный SDK не реализованы и не объявляются.

Поддерживаемые версии протокола: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`. При другой версии сервер предлагает поддерживаемую; окончательная совместимость зависит от клиента.

[Отчет и ограничения тестирования](docs/TESTING.md). В CI предусмотрены Linux/Windows и Node 22/24; само наличие workflow не означает, что GitHub Actions уже запускался.

## Первичные источники

Реализация написана самостоятельно по официальным интерфейсам; чужой Zotero MCP не включен.

- [Zotero Web API basics](https://www.zotero.org/support/dev/web_api/v3/basics)
- [Editable JSON, создание/правка/удаление](https://www.zotero.org/support/dev/web_api/v3/write_requests)
- [File upload/download и binary patches](https://www.zotero.org/support/dev/web_api/v3/file_upload)
- [Синхронизация](https://www.zotero.org/support/dev/web_api/v3/syncing)
- [Типы и поля](https://www.zotero.org/support/dev/web_api/v3/types_and_fields)
- [Официальный sync API client Zotero, сведения о fulltext/settings/keys/current](https://github.com/zotero/zotero/blob/main/chrome/content/zotero/xpcom/sync/syncAPIClient.js)
- [MCP lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle), [stdio](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports), [tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
- [Локальные MCP в Claude Desktop](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)

MIT. Неофициальный проект, не связан с Zotero или Anthropic.