yonote-mcp

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