yonote-mcp

MCP-сервер для управления рабочим пространством Yonote через AI-ассистенты (Claude, Cursor и другие).

Предоставляет 56 инструментов для работы с документами, коллекциями, пользователями, группами, комментариями, ссылками общего доступа, избранным, ревизиями, событиями и просмотрами.

Возможности

Группа	Кол-во	Описание
Документы	18	CRUD, поиск, архивация, перемещение, управление доступом
Коллекции	10	Управление коллекциями, участниками, экспорт
Пользователи	5	Список, приглашение, блокировка, активация
Группы	6	Управление группами и их участниками
Комментарии	4	CRUD комментариев к документам
Шаринг	4	Публичные ссылки на документы
Избранное	3	Управление избранным
Ревизии	2	История версий документов
События	1	Аудит-лог рабочего пространства
Просмотры	2	Статистика просмотров
Авторизация	1	Информация о текущем пользователе и команде

Требования

• Node.js >= 18
• npm
• API-токен Yonote

Установка

git clone <url-репозитория>
cd yonote-mcp
npm install
npm run build

Получение API-токена

1. Откройте Yonote и перейдите в Настройки -> API
2. Создайте новый персональный API-токен
3. Используйте токен при подключении (см. ниже)

Токен действует от имени вашего пользователя и имеет те же права доступа.

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

Токен и проект можно передать двумя способами:

Способ 1: CLI-аргументы (рекомендуется)

Передавайте параметры прямо в конфигурации MCP-клиента — без .env файлов:

Аргумент	Обязательный	Описание
--token	Да	API-токен Yonote
--project	Нет	Название проекта (формирует URL https://{project}.yonote.ru/api)
--base-url	Нет	Полный базовый URL API (если нужен нестандартный URL)

По умолчанию используется https://app.yonote.ru/api. Если передан --project, URL формируется автоматически.

Способ 2: Переменные окружения

Создайте файл .env на основе .env.example:

cp .env.example .env

YONOTE_API_TOKEN=ваш-токен
YONOTE_PROJECT=ваш-проект
YONOTE_API_BASE_URL=https://ваш-проект.yonote.ru/api

CLI-аргументы имеют приоритет над переменными окружения.

Локальное подключение (stdio)

При локальном подключении MCP-клиент запускает сервер как дочерний процесс и общается с ним через stdin/stdout.

Claude Desktop

Отредактируйте файл конфигурации:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yonote": {
      "command": "node",
      "args": [
        "/абсолютный/путь/к/yonote-mcp/dist/index.js",
        "--token", "ваш-токен",
        "--project", "ваш-проект"
      ]
    }
  }
}

Перезапустите Claude Desktop.

Claude Code

claude mcp add yonote -- node /абсолютный/путь/к/yonote-mcp/dist/index.js --token ваш-токен --project ваш-проект

Или добавьте в .claude/settings.json проекта:

{
  "mcpServers": {
    "yonote": {
      "command": "node",
      "args": [
        "/абсолютный/путь/к/yonote-mcp/dist/index.js",
        "--token", "ваш-токен",
        "--project", "ваш-проект"
      ]
    }
  }
}

Cursor

Откройте Settings -> MCP Servers -> Add new MCP server и укажите:

{
  "mcpServers": {
    "yonote": {
      "command": "node",
      "args": [
        "/абсолютный/путь/к/yonote-mcp/dist/index.js",
        "--token", "ваш-токен",
        "--project", "ваш-проект"
      ]
    }
  }
}

Другие MCP-клиенты

Любой MCP-клиент с поддержкой stdio-транспорта может использовать этот сервер. Общий паттерн:

• command: node
• args: ["/путь/к/yonote-mcp/dist/index.js", "--token", "ваш-токен", "--project", "ваш-проект"]

Удалённое развертывание (HTTP)

Для подключения с удалённых машин сервер поддерживает режим Streamable HTTP транспорта.

Запуск в HTTP-режиме

YONOTE_API_TOKEN=ваш-токен TRANSPORT=http PORT=3000 node dist/index.js

Сервер запустится на http://0.0.0.0:3000/mcp.

Также доступен эндпоинт /health для проверки состояния.

Подключение удалённого клиента

В конфигурации MCP-клиента укажите URL сервера:

{
  "mcpServers": {
    "yonote": {
      "url": "http://ваш-сервер:3000/mcp"
    }
  }
}

Docker

Соберите образ (убедитесь, что проект скомпилирован — npm run build):

docker build -t yonote-mcp .

Запустите контейнер:

docker run -d \
  -p 3000:3000 \
  -e YONOTE_API_TOKEN=ваш-токен \
  --name yonote-mcp \
  yonote-mcp

Подключение клиента — аналогично HTTP-режиму выше.

Docker Compose

services:
  yonote-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - YONOTE_API_TOKEN=ваш-токен
    restart: unless-stopped

docker compose up -d

Рекомендации по продакшену

• Используйте HTTPS (через reverse proxy — nginx, Caddy, Traefik)
• Не зашивайте токен в Docker-образ — передавайте через переменные окружения или секреты
• Ограничьте доступ к серверу по сети (firewall, VPN)

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

Переменная	Обязательная	По умолчанию	Описание
YONOTE_API_TOKEN	Да	—	API-токен Yonote (или --token)
YONOTE_PROJECT	Нет	app	Название проекта (или --project)
YONOTE_API_BASE_URL	Нет	https://{project}.yonote.ru/api	Базовый URL API (или --base-url)
TRANSPORT	Нет	stdio	Транспорт: stdio или http
PORT	Нет	3000	Порт HTTP-сервера (только для TRANSPORT=http)

Доступные инструменты

<details> <summary><b>Документы (18)</b></summary>

Инструмент	Описание
documents_list	Список документов с фильтрацией по коллекции, пользователю, статусу
documents_info	Информация о документе по ID или share ID
documents_search	Полнотекстовый поиск по документам
documents_search_titles	Быстрый поиск по заголовкам
documents_create	Создание документа (Markdown)
documents_update	Обновление заголовка, текста и свойств
documents_delete	Перемещение в корзину или удаление
documents_archive	Архивация документа
documents_restore	Восстановление из архива или корзины
documents_move	Перемещение в другую коллекцию
documents_duplicate	Создание копии документа
documents_drafts	Список черновиков текущего пользователя
documents_viewed	Недавно просмотренные документы
documents_unpublish	Возврат в статус черновика
documents_users	Список пользователей с доступом
documents_add_user	Предоставление доступа пользователю
documents_remove_user	Отзыв доступа у пользователя
documents_children	Вложенная структура дочерних документов

</details>

<details> <summary><b>Коллекции (10)</b></summary>

Инструмент	Описание
collections_list	Список всех доступных коллекций
collections_info	Информация о коллекции
collections_create	Создание коллекции
collections_update	Обновление свойств коллекции
collections_delete	Удаление коллекции со всеми документами
collections_documents	Дерево документов коллекции
collections_add_user	Предоставление доступа пользователю
collections_remove_user	Отзыв доступа у пользователя
collections_memberships	Список участников коллекции
collections_export	Экспорт коллекции (Markdown/HTML/JSON)

</details>

<details> <summary><b>Пользователи (5)</b></summary>

Инструмент	Описание
users_list	Список участников рабочего пространства
users_info	Информация о пользователе
users_create	Приглашение нового пользователя
users_suspend	Блокировка учётной записи
users_activate	Разблокировка учётной записи

</details>

<details> <summary><b>Группы (6)</b></summary>

Инструмент	Описание
groups_list	Список всех групп
groups_info	Информация о группе
groups_create	Создание группы
groups_update	Обновление имени группы
groups_delete	Удаление группы
groups_memberships	Список участников группы

</details>

<details> <summary><b>Комментарии (4)</b></summary>

Инструмент	Описание
comments_list	Список комментариев к документу или в коллекции
comments_create	Добавление комментария к документу
comments_update	Обновление комментария
comments_delete	Удаление комментария

</details>

<details> <summary><b>Шаринг (4)</b></summary>

Инструмент	Описание
shares_list	Список расшаренных документов/коллекций
shares_info	Информация о ссылке общего доступа
shares_create	Создание публичной ссылки
shares_delete	Отзыв публичной ссылки

</details>

<details> <summary><b>Избранное (3)</b></summary>

Инструмент	Описание
stars_list	Список избранных документов и коллекций
stars_create	Добавление в избранное
stars_delete	Удаление из избранного

</details>

<details> <summary><b>Ревизии (2)</b></summary>

Инструмент	Описание
revisions_list	История версий документа
revisions_info	Получение конкретной версии документа

</details>

<details> <summary><b>События (1)</b></summary>

Инструмент	Описание
events_list	Аудит-лог рабочего пространства

</details>

<details> <summary><b>Просмотры (2)</b></summary>

Инструмент	Описание
views_list	Статистика просмотров документа
views_create	Фиксация просмотра документа

</details>

<details> <summary><b>Авторизация (1)</b></summary>

Инструмент	Описание
auth_info	Информация о текущем пользователе и команде

</details>

Разработка

npm run build    # Компиляция TypeScript
npm start        # Запуск (stdio-режим)
npm test         # Запуск тестов

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

src/
├── index.ts          # Точка входа, настройка транспорта
├── api-client.ts     # HTTP-клиент для Yonote API
└── tools/            # Инструменты MCP
    ├── documents.ts
    ├── collections.ts
    ├── users.ts
    ├── groups.ts
    ├── comments.ts
    ├── shares.ts
    ├── stars.ts
    ├── revisions.ts
    ├── events.ts
    ├── views.ts
    └── auth.ts