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
Установка```bash
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`:```bash
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````json
{
"mcpServers": {
"yonote": {
"command": "node",
"args": [
"/абсолютный/путь/к/yonote-mcp/dist/index.js",
"--token", "ваш-токен",
"--project", "ваш-проект"
]
}
}
}
Перезапустите Claude Desktop.
### Claude Code```bash
claude mcp add yonote -- node /абсолютный/путь/к/yonote-mcp/dist/index.js --token ваш-токен --project ваш-проект
Или добавьте в .claude/settings.json проекта:```json
{
"mcpServers": {
"yonote": {
"command": "node",
"args": [
"/абсолютный/путь/к/yonote-mcp/dist/index.js",
"--token", "ваш-токен",
"--project", "ваш-проект"
]
}
}
}
### Cursor
Откройте **Settings** -> **MCP Servers** -> **Add new MCP server** и укажите:```json
{
"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-режиме```bash
YONOTE_API_TOKEN=ваш-токен TRANSPORT=http PORT=3000 node dist/index.js
Сервер запустится на `http://0.0.0.0:3000/mcp`.
Также доступен эндпоинт `/health` для проверки состояния.
### Подключение удалённого клиента
В конфигурации MCP-клиента укажите URL сервера:```json
{
"mcpServers": {
"yonote": {
"url": "http://ваш-сервер:3000/mcp"
}
}
}
Docker
Соберите образ (убедитесь, что проект скомпилирован — npm run build):```bash
docker build -t yonote-mcp .
Запустите контейнер:```bash
docker run -d \
-p 3000:3000 \
-e YONOTE_API_TOKEN=ваш-токен \
--name yonote-mcp \
yonote-mcp
Подключение клиента — аналогично HTTP-режиму выше.
Docker Compose```yaml
services:
yonote-mcp:
build: .
ports:
- "3000:3000"
environment:
- YONOTE_API_TOKEN=ваш-токен
restart: unless-stopped
``````bash
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`) |
## Доступные инструменты
Документы (18)
| Инструмент | Описание |
|---|---|
| `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` | Вложенная структура дочерних документов |
Коллекции (10)
| Инструмент | Описание |
|---|---|
| `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) |
Пользователи (5)
| Инструмент | Описание |
|---|---|
| `users_list` | Список участников рабочего пространства |
| `users_info` | Информация о пользователе |
| `users_create` | Приглашение нового пользователя |
| `users_suspend` | Блокировка учётной записи |
| `users_activate` | Разблокировка учётной записи |
Группы (6)
| Инструмент | Описание |
|---|---|
| `groups_list` | Список всех групп |
| `groups_info` | Информация о группе |
| `groups_create` | Создание группы |
| `groups_update` | Обновление имени группы |
| `groups_delete` | Удаление группы |
| `groups_memberships` | Список участников группы |
Комментарии (4)
| Инструмент | Описание |
|---|---|
| `comments_list` | Список комментариев к документу или в коллекции |
| `comments_create` | Добавление комментария к документу |
| `comments_update` | Обновление комментария |
| `comments_delete` | Удаление комментария |
Шаринг (4)
| Инструмент | Описание |
|---|---|
| `shares_list` | Список расшаренных документов/коллекций |
| `shares_info` | Информация о ссылке общего доступа |
| `shares_create` | Создание публичной ссылки |
| `shares_delete` | Отзыв публичной ссылки |
Избранное (3)
| Инструмент | Описание |
|---|---|
| `stars_list` | Список избранных документов и коллекций |
| `stars_create` | Добавление в избранное |
| `stars_delete` | Удаление из избранного |
Ревизии (2)
| Инструмент | Описание |
|---|---|
| `revisions_list` | История версий документа |
| `revisions_info` | Получение конкретной версии документа |
События (1)
| Инструмент | Описание |
|---|---|
| `events_list` | Аудит-лог рабочего пространства |
Просмотры (2)
| Инструмент | Описание |
|---|---|
| `views_list` | Статистика просмотров документа |
| `views_create` | Фиксация просмотра документа |
Авторизация (1)
| Инструмент | Описание |
|---|---|
| `auth_info` | Информация о текущем пользователе и команде |
## Разработка```bash
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
```
