MCP-сервер

Обзор

MCP (Model Context Protocol) Сервер — это встроенный сервис протокола, который предоставляет вашу библиотеку Zotero и возможности Synthesis как 40+ инструментов MCP. Клиенты, совместимые с MCP (Claude Desktop, Cursor, расширения VS Code и т.д.), могут напрямую обращаться к данным Zotero.

MCP-сервер разделяет базовый реестр возможностей Host Bridge, но следует спецификации протокола MCP (Streamable HTTP транспорт, JSON-RPC 2.0).

Конфигурация

Zotero → Настройки → Zotero Agents → Host Bridge → Включить MCP-сервер

Один флажок переключает сервер вкл/выкл. Включено по умолчанию.

Ненастраиваемые значения по умолчанию

Настройка	Значение	Причина
Адрес прослушивания	`127.0.0.1`	Безопасность: только loopback
Проверка источника	Строгая	Только `127.0.0.1`, `localhost`, `[::1]`
Ограничение размера запроса	1 MB	Защита памяти
Защита записи	Включена	Все операции записи требуют подтверждения

Безопасность

Аутентификация Bearer Token: использует тот же сессионный/мастер-токен, что и Host Bridge
Только loopback: удалённый доступ невозможен
Проверка источника: запросы с других источников отклоняются (403)
Ограничение 1 MB: слишком большие тела отклоняются с кодом 413
Однопоточная очередь: 1 выполняющийся + 8 ожидающих, тайм-аут выполнения 45с, тайм-аут очереди 30с
Прерыватели цепи: 3 сбоя за 5 минут → инструмент приостановлен на 60с

Подключение клиентов MCP

Конечная точка

http://127.0.0.1:<port>/mcp

Порт назначается автоматически (диапазон 26370-26569). Проверьте конечную точку Host Bridge в настройках для фактического порта.

Пример конфигурации Claude Desktop

{
  "mcpServers": {
    "zotero-skills": {
      "type": "http",
      "url": "http://127.0.0.1:26370/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Получите токен из Настройки → Host Bridge → Копировать мастер-токен.

Детали протокола

Транспорт: Streamable HTTP (POST /mcp)
Версия: 2025-06-18
Идентичность сервера: zotero-skills / "Zotero Agents Context Broker" v0.4.0
GET /mcp → 405 (принимается только POST)
Запросы без id → рассматриваются как уведомления (без ответа)
id: null → явно недействительно

Инвентарь инструментов

Все 40+ инструментов

Инструменты чтения

Инструмент	Описание
`get_current_view`	Информация о текущем представлении Zotero
`get_selected_items`	Сводки текущих выбранных элементов
`search_items`	Поиск элементов (лимит ≤ 50)
`list_library_items`	Список элементов с пагинацией
`get_item_detail`	Полные метаданные элемента
`get_item_notes`	Список дочерних заметок
`get_note_detail`	Чтение тела заметки (частями, ≤16k символов на часть)
`list_note_payloads`	Список полезных нагрузок Workflow в заметке
`get_note_payload`	Чтение одной полезной нагрузки
`get_item_attachments`	Список манифестов вложений (без байтов файлов)
`prepare_paper_reading_context`	Агрегация метаданных, заметок, полезных нагрузок, вложений для одной статьи

Инструменты записи (требуют подтверждения)

Инструмент	Описание
`preview_mutation`	Предпросмотр операции записи без выполнения
`update_item_fields`	Обновление разрешённых полей одного элемента
`add_item_tags`	Добавление тегов к одному или нескольким элементам
`remove_item_tags`	Удаление тегов
`create_child_note`	Создание дочерней заметки
`update_note`	Обновление тела заметки
`create_markdown_note`	Создание заметки с отрендеренным HTML + полезной нагрузкой markdown base64
`update_markdown_note`	Обновление существующей заметки на основе markdown
`ingest_paper`	Приём статьи по DOI/arXiv/PMID/ISBN (с вложением PDF)
`add_items_to_collection`	Добавление элементов в коллекцию
`remove_items_from_collection`	Удаление элементов из коллекции

Инструмент диагностики

Инструмент	Описание
`get_mcp_status`	Диагностика сервиса: очередь, прерыватели цепи, последние запросы

Инструменты Synthesis

Инструмент	Описание
`topics.list`	Список всех тем
`topics.find_by_paper_ref`	Поиск тем по ссылке на статью
`topics.get_context`	Получение полного контекста темы
`topics.get_review_input`	Сборка пакета рецензирования темы
`schemas.get`	Получение определений схемы
`concepts.query`	Запрос базы знаний концепций
`citation_graph.query_cluster`	Запрос кластера цитирований
`citation_graph.get_overview`	Получение обзора графа
`citation_graph.get_slice`	Извлечение среза подграфа
`citation_graph.get_metrics`	Вычисление метрик графа (pagerank, foundation, frontier)
`citation_graph.rank_external_references`	Ранжирование внешних ссылок
`citation_graph.rank_library_papers`	Ранжирование статей библиотеки
`library_index.get`	Индекс библиотеки с пагинацией
`resolvers.resolve`	Разрешение резолверов ссылок/тем
`reference_index.get`	Получение индекса ссылок
`paper_artifacts.get_manifest`	Получение манифеста артефактов
`paper_artifacts.read`	Чтение содержимого артефактов
`paper_artifacts.export_filtered`	Экспорт отфильтрованных артефактов
`paper_artifacts.resolve_topic_digest`	Разрешение дайджеста темы
`insights.get_attention_queue`	Получение очереди внимания

Защита записи

Инструменты записи следуют той же модели подтверждения, что и Host Bridge:

Клиент MCP вызывает инструмент записи
  │
  ├── Bearer Token проверен
  ├── Область инструмента извлечена
  ├── Проверка подтверждения:
  │     ├── Инструмент только для чтения → выполнить немедленно
  │     ├── Предварительно одобренная запись → выполнить немедленно
  │     └── Требуется подтверждение → в очередь в UI Zotero
  └── Выполнить / Отклонить

Очередь: максимум 50 ожидающих подтверждений; >10 отклонённых записей за 5 минут → прерыватель цепи (отключён на 30с).

Следующие шаги

Host Bridge — Базовый транспорт и инструмент CLI
Настройки — Просмотр настроек MCP-сервера

Обзор​

Конфигурация​

Ненастраиваемые значения по умолчанию​

Безопасность​

Подключение клиентов MCP​

Конечная точка​

Пример конфигурации Claude Desktop​

Детали протокола​

Инвентарь инструментов​

Инструменты чтения​

Инструменты записи (требуют подтверждения)​

Инструмент диагностики​

Инструменты Synthesis​

Защита записи​

Следующие шаги​