mcp-yandex-wiki

Минимальный MCP-сервер для Яндекс Вики (read + write).

Установка

cd ~/.claude/mcp/yandex-wiki
npm install

Регистрация в ~/.claude.json:

{
  "mcpServers": {
    "yandex-wiki": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/<user>/.claude/mcp/yandex-wiki/index.mjs"],
      "env": {
        "YW_OAUTH_TOKEN": "y0__...",
        "YW_ORG_ID": "1234567",
        "YW_ORG_HEADER": "X-Org-Id"
      }
    }
  }
}

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

Переменная	Обязательна	Описание
YW_OAUTH_TOKEN	да	OAuth-токен Яндекса со скоупом wiki:read / wiki:write
YW_ORG_ID	да	ID организации
YW_ORG_HEADER	нет	X-Org-Id для Яндекс 360 (по умолчанию), X-Cloud-Org-Id для Yandex Cloud Organization

Токен от Яндекс Трекера подходит, если тому же приложению выданы и wiki-скоупы — механика авторизации общая (OAuth + заголовок организации). Подробнее — Про скоупы токена.

Сервисный аккаунт Yandex Cloud для Wiki API не годится — только пользовательский.

Инструменты

Инструмент	API	Описание
myself	GET /users/me	Текущий пользователь, организация, домашний кластер
get_page	GET /pages?slug= / GET /pages/{id}	Страница по slug или id. Тело — только при fields: ["content"]
search	POST /search	Полнотекстовый поиск, до 10 результатов
list_descendants	GET /pages/{id}/descendants	Подстраницы
list_resources	GET /pages/{id}/resources	Вложения + таблицы одним списком
list_attachments	GET /pages/{id}/attachments	Вложения
list_grids	GET /pages/{id}/grids	Динамические таблицы
create_page	POST /pages	Создать страницу (slug, title обязательны)
update_page	POST /pages/{id}	Изменить title / content / slug
delete_page	DELETE /pages/{id}	Удалить страницу (необратимо)

fields у get_page

redirect, breadcrumbs, attributes, content, access_policy, access_lists, owner.

Без fields возвращаются только id, slug, title, page_type.

Особенности API

• Поиск не пагинируется. total_pages всегда 1, отдаётся максимум 10 результатов; параметры page / offset игнорируются. Сужай запрос.
• PATCH и PUT не поддерживаются. Обновление — это POST /pages/{id}. Разрешённые методы: /pages → POST, GET; /pages/{id} → POST, GET, DELETE.
• Readonly-страницы отдают HTTP 403 на запись — см. Как читать HTTP 403.

Статус проверок

Инструмент	Статус
myself, get_page, search, list_descendants, list_resources, list_attachments, list_grids	проверены на живом API
update_page	проверен: round-trip заголовка на реальной странице, контент побайтово не изменился
create_page, delete_page	не проверялись — схема восстановлена из ошибок валидации API и заголовка Allow

Про скоупы токена

Документация называет два скоупа: wiki:read (только чтение) и wiki:write (создание, редактирование, удаление). Плюс отдельный гейт — права пользователя: «запросы выполняются от имени пользователя… пользователь должен иметь соответствующие права в Вики».

На практике wiki-скоупы оказались не нужны. Токен приложения, которому выданы только скоупы Яндекс Трекера и ни одного wiki-скоупа, читает и пишет в Вики без ошибок — проверено на живом API, включая POST на страницу.

Механика этого не установлена, возможны два объяснения:

• Wiki API не проверяет скоуп вообще и пускает по личности пользователя;
• скоуп Трекера покрывает и Вики по дизайну — сервисы одного продуктового куста.

Различить можно токеном с посторонним скоупом (например, только login:info): пройдёт — первое, 403 — второе.

Enforcement у Яндекса посервисный, а не глобальный: тот же токен на Яндекс.Диск (cloud_api:disk.read не выдан) получает HTTP 403 «Возможно, у приложения недостаточно прав». То есть «Диск проверяет скоуп» не означает, что его проверяет Вики — не переносите вывод с одного API на другое.

Практический итог: если у вас уже есть токен Яндекс Трекера, отдельные wiki-скоупы можно не выдавать. Обратная сторона — отдельный «wiki-only» токен не изолирует Вики: её откроет и токен Трекера.

Как читать HTTP 403

Скоуп тут почти наверняка ни при чём — смотрите на права:

• у пользователя нет прав на страницу;
• страница readonly: get_page с fields: ["attributes"] → attributes.is_readonly. Системные страницы (владелец yandex360-wiki) readonly — например, главная.

Если 403 приходит вообще на всё, включая чтение, — проверьте X-Org-Id и то, что токен принадлежит пользователю, а не сервисному аккаунту.

Побочный эффект записи

Любой POST /pages/{id} бампает modified_at, даже если в теле нет ни одного значимого поля. Страница отметится как изменённая.