MCP Server Zotero Dev

Дайте вашему ИИ-ассистенту суперспособности для разработки плагинов Zotero

Архитектура · Быстрый старт · Доступные инструменты

Сервер Model Context Protocol (MCP), который позволяет ИИ-ассистентам, таким как Claude, Cursor и Windsurf, собирать, тестировать и отлаживать плагины Zotero 7, 8, 9 и 10. Скриншоты, состояние DOM, журналы отладки и выполнение JavaScript дают ИИ богатый контекст для понимания происходящего — и инструменты, которые помогут вам это исправить.

✨ Возможности

Related MCP server: Kaboom Browser AI Devtools MCP

🚀 Быстрый старт

Предварительные требования

• Node.js 20+ и npm

• Zotero 7+ — работает на всех сборках Zotero 7, 8, 9 и 10 (release, beta, dev)

• Для разработки плагинов: zotero-plugin-scaffold

1. Установите MCP-сервер

Используйте install-mcp, чтобы добавить сервер в вашего ИИ-ассистента:

npx -y install-mcp @introfini/mcp-server-zotero-dev --client claude-code

Поддерживаемые клиенты: claude-code, cursor, windsurf, vscode, cline, roo-cline, claude, zed, goose, warp, codex

npx -y install-mcp @introfini/mcp-server-zotero-dev --client claude-code

npx -y install-mcp @introfini/mcp-server-zotero-dev --client cursor

npx -y install-mcp @introfini/mcp-server-zotero-dev --client vscode

npx -y install-mcp @introfini/mcp-server-zotero-dev --client windsurf

Добавьте в конфигурацию вашего MCP-клиента:

{
  "mcpServers": {
    "zotero-dev": {
      "command": "npx",
      "args": ["-y", "@introfini/mcp-server-zotero-dev@1.1.1"],
      "env": {
        "ZOTERO_RDP_PORT": "6100"
      }
    }
  }
}

Версия и обновления: указывайте точную версию, как показано выше. Голый npx <pkg> (без версии) продолжает запускать то, что закэшировал npx, и не подхватывает новые релизы, поэтому всегда включайте версию и -y (без -y npx зависнет в ожидании запроса на установку). Увеличьте зафиксированную версию, чтобы обновиться, или используйте @latest, чтобы при каждом запуске получать самую свежую версию (автообновления, но неудачный релиз запустится автоматически, а при каждом старте добавляется проверка реестра). Учтите, что install-mcp может записать конфигурацию без -y или версии, поэтому ручная настройка выше — самый надёжный путь.

Перезапустите вашего ИИ-ассистента после добавления конфигурации.

2. Установите MCP Bridge Plugin в Zotero

Скачайте zotero-mcp-bridge.xpi и установите:

1. В Zotero: Сервис → Плагины

2. Нажмите ⚙️ → Установить плагин из файла

3. Выберите скачанный файл .xpi

4. Перезапустите Zotero

Этот лёгкий плагин включает Remote Debugging Protocol при запуске Zotero. Его нужно установить только один раз, и он работает на всех сборках Zotero 7+ (release, beta и dev).

3. Начинайте разработку!

Просто откройте Zotero как обычно и попросите вашего ИИ-ассистента:

«Сделай скриншот Zotero и перечисли установленные плагины»

Вот и всё! Никаких специальных флагов запуска и никакой настройки. 🎉

🧰 Доступные инструменты (всего 28)

Цели скриншотов: главное окно, настройки, программа просмотра PDF, диалоги или любой элемент по селектору. Используйте highlightSelector, чтобы перед захватом добавить красную рамку.

Поиск сначала идёт по обычному (light) DOM, затем проникает в открытые shadow root'ы (внутренности XUL-кастомных элементов Zotero хранятся в shadow DOM). Ограничение: нельзя закрыть блокирующий нативный модальный диалог (Services.prompt.confirmEx) — его вложенный модальный цикл блокирует поток eval, на котором работают эти инструменты.

Примеры: Zotero.Items.getAll(1), Zotero.Prefs.get('export.quickCopy.setting'), ZoteroPane.getSelectedItems()

Совет: используйте zotero_inspect_object, чтобы изучить API перед написанием кода. Используйте zotero_search_prefs, чтобы находить ключи настроек.

Примечание: доступ к базе данных — только для чтения; требует закрытого Zotero либо используется копия базы данных.

🏗️ Архитектура

┌─────────────────────────────────────────────────────────────────┐
│                        AI Assistant                             │
│                  (Claude, Cursor, Windsurf)                     │
└─────────────────────────┬───────────────────────────────────────┘
                          │ MCP Protocol (stdio)
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                  MCP Server (Node.js/TypeScript)                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │   Scaffold   │  │     RDP      │  │      Database        │   │
│  │  Integration │  │    Client    │  │      Reader          │   │
│  └──────────────┘  └──────┬───────┘  └──────────────────────┘   │
└─────────────────────────────┼───────────────────────────────────┘
                              │ Firefox RDP (port 6100)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Zotero Application                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │            MCP Bridge for Zotero                         │   │
│  │         Starts DevToolsServer on launch                  │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Firefox DevTools Server (built-in)          │   │
│  │           JS Execution • DOM • Console • Screenshots     │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                   Your Plugin (dev)                      │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Почему такой подход?

• ✅ Лёгкий плагин — просто включает RDP, остальное делает Firefox DevTools

• ✅ Без настройки после установки — просто открывайте Zotero как обычно, без специальных флагов

• ✅ Богатый контекст для ИИ — скриншоты, DOM и журналы помогают ИИ понять состояние вашего плагина

• ✅ Горячая перезагрузка — интеграция с zotero-plugin-scaffold для мгновенной обратной связи

• ✅ Полный доступ к Zotero — выполнение любого API Zotero в привилегированном контексте

• ✅ Кроссплатформенность — работает на Linux, Windows, macOS

🔧 Переменные окружения

🔌 Изменение порта RDP

Мост по умолчанию слушает порт 6100. Менять его нужно, только если вы запускаете два экземпляра Zotero одновременно (например, обычный профиль и профиль для разработки) или если порт 6100 уже занят другим процессом.

Порт задан на обеих сторонах моста, и обе стороны должны совпадать.

1. Сторона Zotero — задайте настройку плагина:

1. Настройки → Дополнительно → Редактор конфигурации и примите предупреждение

2. Найдите extensions.mcp-rdp.port

3. Если её нет, создайте: выберите Число, назовите её extensions.mcp-rdp.port и введите ваш порт

4. Перезапустите Zotero — слушатель открывается только при запуске

Следите за типом. Редактор конфигурации по умолчанию выбирает Логическое. Если создать настройку, не переключившись на Число, вместо порта будет сохранено true, и Zotero откроет мост на локальном канале (pipe), а не на TCP-порту, — журнал отладки сообщит об успехе, но ни один MCP-клиент не сможет подключиться.

2. Сторона клиента — задайте ZOTERO_RDP_PORT с тем же значением в конфигурации вашего MCP-клиента:

{
  "mcpServers": {
    "zotero-dev": {
      "command": "npx",
      "args": ["-y", "@introfini/mcp-server-zotero-dev@1.1.2"],
      "env": {
        "ZOTERO_RDP_PORT": "6101"
      }
    }
  }
}

Меняйте обе стороны или не меняйте ни одной. Если изменить только одну сторону, мост разорвётся: Zotero слушает один порт, а клиент продолжает подключаться к другому.

Если вы действительно запускаете два экземпляра

Запуск Zotero во второй раз возвращает вам уже открытое окно — как и Firefox, он перенаправляет на запущенный экземпляр, а не запускает новый. Второму экземпляру нужен собственный профиль и -no-remote:

# macOS; adjust the binary path on Windows/Linux
MOZ_NO_REMOTE=1 "/Applications/Zotero.app/Contents/MacOS/zotero" -P <profile-name> -no-remote

Задайте для этого профиля собственный extensions.mcp-rdp.port, и два моста не будут мешать друг другу. Проверено одновременно с 9.0.6 на порту 6100 и 10.0-beta.22 на порту 6101.

Требуется плагин MCP Bridge 1.0.5 или новее. В версиях 1.0.4 и ранее extensions.mcp-rdp.port считывался в неправильной ветке настроек и молча игнорировался, поэтому мост оставался на 6100, что бы вы ни указали. Если вы настраивали нестандартный порт для более старой сборки, он хранится как extensions.zotero.extensions.mcp-rdp.port — такое имя по-прежнему работает, но лучше использовать указанное выше.

Отключение моста

Установите extensions.mcp-rdp.enabled в значение false (Boolean) в Config Editor и перезапустите Zotero. Плагин остаётся установленным, но не открывает порт для прослушивания, и ни один MCP-клиент не сможет подключиться к Zotero, пока вы не вернёте значение true.

📸 Примеры скриншотов

// Capture main Zotero window
await zotero_screenshot({ target: 'main-window' });

// Capture your plugin's panel with highlight
await zotero_screenshot({
  target: 'element',
  selector: '#my-plugin-panel',
  highlightSelector: '#my-plugin-button'
});

// Capture a specific window by ID (use zotero_list_windows to find IDs)
await zotero_screenshot({
  target: 'window',
  windowId: 12345
});

// Capture element after triggering UI action
await zotero_execute_js({ code: 'document.querySelector("#menu").click()' });
await zotero_screenshot({ target: 'element', selector: 'menupopup[state="open"]' });

🧑💻 Разработка

# Clone and install
git clone https://github.com/introfini/mcp-server-zotero-dev.git
cd mcp-server-zotero-dev
npm install

# Build everything
npm run build

# Build individual packages
npm run build:server
npm run build:plugin

# Run tests
npm test

# Development mode (watch)
npm run dev

mcp-server-zotero-dev/
├── packages/
│   ├── mcp-server/               # MCP server (npm package)
│   │   ├── src/
│   │   │   ├── index.ts          # MCP server entry
│   │   │   ├── rdp/              # RDP client
│   │   │   ├── tools/            # Tool implementations
│   │   │   └── prompts/          # Slash commands
│   │   └── package.json
│   │
│   └── zotero-plugin-mcp-rdp/    # Tiny Zotero plugin (.xpi)
│       ├── src/
│       │   └── bootstrap.js      # Starts RDP server (shipped verbatim)
│       ├── addon/
│       │   └── manifest.json
│       └── package.json
│
├── docs/                         # Documentation
└── package.json                  # Monorepo root

📚 Ресурсы

• Architecture & Technical Learnings — Подробный разбор протокола RDP, иерархии акторов и типичных ошибок

• Zotero Plugin Development — Официальная документация

• Zotero 10 for Developers — Руководство по миграции для последней мажорной версии

• Zotero 7 for Developers — Руководство по миграции

• zotero-plugin-scaffold — Инструменты сборки

• zotero-plugin-template — Стартовый шаблон

• zotero-plugin-toolkit — Вспомогательные API-функции

• Firefox RDP Protocol — Документация по протоколу

🤝 Участие

Вклад приветствуется. О настройке, соглашениях о тестировании и специфических для кодовой базы правилах, которые стоит знать перед началом работы, читайте в CONTRIBUTING.md.

Краткая версия:

1. Следуйте существующим образцам кода

2. Добавляйте тесты для новых функций; если Zotero не запущен, тесты должны пропускаться, а не падать

3. Обновляйте документацию

4. CI нет, поэтому самостоятельно запустите npm run build, npm run typecheck, npm run lint и npm test и укажите в PR, с какой версией Zotero вы проверяли

📄 Лицензия

MIT © introfini

Благодарности

• Создано для сообщества разработчиков плагинов Zotero

• Интегрируется с zotero-plugin-scaffold от @windingwind

• Использует Firefox DevTools RDP для надёжной связи