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"
      }
    }
  }
}

Related MCP server: Yandex Wiki MCP

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

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

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

Инструменты

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.

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

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

Документация называет два скоупа: 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, даже если в теле нет ни одного значимого поля. Страница отметится как изменённая.