Esa MCP Server

Официальный MCP-сервер от команды esa.io (STDIO Transport).

Этот сервер связывает AI-ассистента с информационным сервисом esa.io через протокол Model Context Protocol (MCP). Благодаря ему AI может читать, создавать, обновлять и управлять статьями esa, а также выполнять другие действия с командой, комментариями и категориями.

Установка и настройка

Сервер запускается либо через Docker (рекомендуется), либо напрямую с помощью npx.

Требования

• Учетная запись в esa.io
• Персональный токен доступа (PAT v2) с правами read, write или более детальными: admin:comment, read:post, write:post, read:category, read:tag, read:attachment, read:team, read:member

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

• ESA_ACCESS_TOKEN — ваш персональный токен доступа (обязательно). Используйте PAT v2 (инструкция).
• LANG — язык интерфейса (например, ja, en).

Конфигурация MCP-клиента

Добавьте сервер в настройки вашего MCP-клиента (например, Claude Desktop).

Docker (рекомендуется)

{
  "mcpServers": {
    "esa": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "ESA_ACCESS_TOKEN", "-e", "LANG", "ghcr.io/esaio/esa-mcp-server"],
      "env": {
        "ESA_ACCESS_TOKEN": "your_personal_access_token",
        "LANG": "ja"
      }
    }
  }
}

npx

{
  "mcpServers": {
    "esa": {
      "command": "/Users/your-username/.nodenv/shims/npx",
      "args": ["@esaio/esa-mcp-server"],
      "env": {
        "ESA_ACCESS_TOKEN": "your_personal_access_token",
        "LANG": "ja"
      }
    }
  }
}

Важно: в пути command укажите полный путь к Node.js, который можно получить командой which node.

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

Управление командами (esa_)

• esa_get_teams — список команд, в которых состоит пользователь.
• esa_get_team_stats — статистика команды (число участников, статей, комментариев).
• esa_get_team_tags — список используемых тегов и частота их применения.
• esa_get_team_members — информация об участниках команды (роль, профиль).

Управление статьями

• esa_search_posts — поиск статей.
• esa_get_post — получение статьи по ID.
• esa_create_post — создание новой статьи (с тегами, категорией, статусом WIP).
• esa_update_post — обновление заголовка, текста, тегов, категории, статуса WIP.
• esa_archive_post — архивирование статьи (перемещение в категорию Archived/).
• esa_ship_post — публикация статьи (снятие флага WIP).
• esa_duplicate_post — подготовка к дублированию (возвращает заголовок и текст).

Управление комментариями

• esa_get_comment — получение комментария по ID.
• esa_create_comment — добавление комментария к статье.
• esa_update_comment — редактирование комментария.
• esa_delete_comment — удаление комментария.
• esa_get_post_comments — список комментариев к статье (с постраничной навигацией).
• esa_get_team_comments — список всех комментариев в команде (с постраничной навигацией).

Управление категориями

• esa_get_categories — список категорий по заданному пути.
• esa_get_top_categories — корневые категории.
• esa_get_all_category_paths — полный список путей категорий с количеством статей. Поддерживает фильтры: prefix: "dev" (только разработка), match: "api" (содержит "api").

Вложения

• esa_get_attachment — получение вложенного файла. Изображения (JPEG, PNG, GIF, WebP) до 30 МБ возвращаются в base64; остальные файлы и большие изображения — через подписанную ссылку (действительна 5 минут). Чтобы принудительно получить ссылку, укажите forceSignedUrl.

Справка и документация

• esa_get_search_options_help — справка по синтаксису поиска.
• esa_get_markdown_syntax_help — справка по Markdown-разметке esa.
• esa_search_help — поиск по документации esa.

Ресурсы

• esa_recent_posts — список недавно обновленных статей. Шаблон: esa://teams/{teamName}/posts/recent. Возвращает JSON.

Промпты

• esa_summarize_post — структурированное резюме статьи. Требует имя команды и ID статьи.

Полезные ссылки

• esa.io — информационный сервис для команд.
• Model Context Protocol — спецификация протокола.
• API документация esa.
• Claude Desktop — MCP-совместимый AI-клиент.

Поддержка

• Вопросы и предложения: форма обратной связи (на японском).
• Баги и запросы: GitHub Issues.
• Справка: esa Docs.

Разработано командой esa.io с ❤️