Окружение AI-агентов для backoffice: конфиги MCP-серверов (crush, kimi-code, opencode)
  • Shell 79.8%
  • Makefile 20.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Andrey Limachko 9ff5152d19
chore(mcp): bump forgejo-mcp onto upstream v3.4.1
Rebase the fork's eight commits from v3.3.0 onto upstream v3.4.1 (95
upstream commits). One conflict in cmd/cmd.go: upstream's -heartbeat flag
and the fork's -tool-profile share the var block, both kept. A follow-up
commit fixes four golangci-lint v2.15 findings in the fork's own code.

Generated-by: OpenCode (DeepSeek V4.1 Flash 1017)
Signed-off-by: Andrey Limachko <liannnix@altlinux.org>
2026-11-11 00:07:24 +00:00
.agents/skills chore: generate OpenSpec skills for every supported agent 2026-10-22 14:35:59 +00:00
.kimi-code feat(mcp): provision matrix-mcp credentials from .env 2026-10-28 17:42:05 +00:00
.opencode feat(mcp): provision matrix-mcp credentials from .env 2026-10-28 17:42:05 +00:00
mcp chore(mcp): bump forgejo-mcp onto upstream v3.4.1 2026-11-11 00:07:24 +00:00
mcp-features docs(mcp-features): mark the audit findings fixed since the audit 2026-10-23 19:09:16 +00:00
openspec chore: initialize OpenSpec workspace 2026-10-22 14:35:53 +00:00
reports chore: keep reports directory placeholder 2026-10-22 12:11:42 +00:00
scripts feat(mcp): provision matrix-mcp credentials from .env 2026-10-28 17:42:05 +00:00
.crushrc feat(mcp): provision matrix-mcp credentials from .env 2026-10-28 17:42:05 +00:00
.env.example feat(mcp): provision matrix-mcp credentials from .env 2026-10-28 17:42:05 +00:00
.gitignore chore: keep local session logs out of the repository 2026-10-22 14:36:16 +00:00
.gitmodules chore: manage MCP servers as git submodules 2026-10-22 12:07:30 +00:00
Makefile feat: build MCP servers from mcp/ submodules via Makefile 2026-10-22 12:26:54 +00:00
README.md feat(mcp): provision matrix-mcp credentials from .env 2026-10-28 17:42:05 +00:00

Office MCP Configuration

Общая конфигурация MCP-серверов для AI-агентов (Crush, kimi-code, opencode) для работы с инфраструктурой ALT Linux: багтрекер, Redmine, вики, почта, forge-репозитории и база пакетов.

Один и тот же набор из 14 MCP-серверов описан для каждого агента в его собственном формате:

Агент Файл конфигурации
Crush .crushrc
kimi-code .kimi-code/mcp.json
opencode .opencode/opencode.json

Локальные (stdio) серверы собираются из исходников сабмодулей mcp/ командой make; бинарники складываются рядом с исходниками (mcp/<имя>/<имя>). Секреты не хранятся в репозитории: ключи берутся из переменных окружения (файл .env, в git не коммитится; шаблон — .env.example).

MCP-серверы

Сервер Тип Что даёт Ключи
bugzilla remote Поиск и работа с багами bugzilla.altlinux.org опционально (для записи)
gitoskop remote Чтение git-репозиториев пакетов git.altlinux.org не нужны
telegram remote Telegram от аккаунта пользователя: история, поиск, отправка кластерный секрет
matrix local Matrix от аккаунта пользователя (matrix.altlinux.org): история, поиск, отправка нужны
alt-rdb local База пакетов ALT (версии, зависимости, CVE, errata) не нужны
redmine local Трекер задач my.basealt.space опционально (для записи)
mediawiki-altlinux local Публичная вики www.altlinux.org (только чтение) не нужны
mediawiki-intranet local Внутренняя вики intranet.altlinux.ru (чтение/запись) нужны
mail local Почтовый ящик (IMAP/Sieve), сервер yandex нужны
forgejo local Forge-репозитории altlinux.space (issues, PR, CI) опционально
hedgedoc local Совместные Markdown-заметки hdoc.lian.su не нужны
nextcloud-contacts local Адресная книга Nextcloud (CardDAV): поиск и правка контактов нужны
nextcloud-calendar local Календари Nextcloud (CalDAV): события, поиск, создание нужны
mattermost local Корпоративный Mattermost mm.srt.basealt.ru: каналы, сообщения, поиск нужны

Без ключей все серверы продолжают работать в режиме чтения (публичные данные); ключи нужны для записи и доступа к приватным данным.

Установка

git clone <url-репозитория> office
cd office
cp .env.example .env
# заполнить .env своими ключами (см. ниже)

Переменные из .env подхватываются агентами при запуске (экспортируйте их в shell-сессии или используйте direnv / аналог). Дополнительно .crushrc подгружает ~/.api_keys.env, если он существует.

Требования: uv/uvx (для серверов hedgedoc и mattermost), bash и Go (для сборки локальных серверов через make).

Получение API-ключей

BUGZILLA_API_KEY — Bugzilla ALT Linux

  1. Войти на https://bugzilla.altlinux.org (создать аккаунт при необходимости).
  2. Открыть Preferences → API Keys (https://bugzilla.altlinux.org/userprefs.cgi?tab=apikey).
  3. Нажать Generate a new API key, при желании ограничить права.
  4. Скопировать ключ в .env.

Без ключа доступны чтение публичных багов и поиск; с ключом — комментарии, создание и изменение багов от вашего имени.

REDMINE_API_KEY — Redmine my.basealt.space

  1. Войти на https://my.basealt.space.
  2. Открыть Моя учётная запись (ссылка справа вверху).
  3. На боковой панели нажать Показать у пункта Ключ доступа к API и скопировать ключ (при необходимости Сбросить, чтобы сгенерировать новый).
  4. Записать в .env. Переменная REDMINE_URL опциональна (переопределяет базовый URL, по умолчанию https://my.basealt.space).

Без ключа доступны только публичные проекты и только чтение.

ALTLINUX_SPACE_KEY — Forgejo altlinux.space

  1. Войти на https://altlinux.space.
  2. Открыть Settings → Applications (https://altlinux.space/user/settings/applications).
  3. В разделе Generate New Token задать имя, выбрать нужные scope (для полной работы: read:user, write:repository, write:issue, write:package и т.д.) и нажать Generate Token.
  4. Токен показывается один раз — сразу записать в .env.

Без токена доступны только публичные репозитории (чтение).

MW_INTRANET_USERNAME / MW_INTRANET_PASSWORD — внутренняя вики ALT

Для записи во внутреннюю вики используется механизм BotPasswords:

  1. Войти на https://intranet.altlinux.ru под своим аккаунтом.
  2. Открыть Special:BotPasswords (https://intranet.altlinux.ru/wiki/Special:BotPasswords).
  3. Создать новый бот-пароль: задать имя бота (например mcp) и выбрать права (минимум: чтение страниц, правка существующих, создание страниц).
  4. Wiki вернёт логин вида YourName@mcp и пароль.
  5. Записать в .env: MW_INTRANET_USERNAME=YourName@mcp, MW_INTRANET_PASSWORD=<пароль бота>.

Без ключей сервер не стартует с полным набором инструментов; чтение внутренней вики также требует авторизации.

MAIL_YANDEX_USER / MAIL_YANDEX_PASSWORD — почта Яндекса

Обычный пароль аккаунта не подходит, нужен пароль приложения:

  1. Включить IMAP: почта Яндекса → Настройки → Почтовые программы → С сервера imap.yandex.ru по протоколу IMAP.
  2. Открыть управление аккаунтом https://id.yandex.ru/security/app-passwords.
  3. Создать пароль приложения для типа Почта.
  4. Записать в .env: MAIL_YANDEX_USER=<ваш адрес @yandex.ru>, MAIL_YANDEX_PASSWORD=<пароль приложения>.

NEXTCLOUD_URL / NEXTCLOUD_USER / NEXTCLOUD_APP_PASSWORD — Nextcloud (контакты и календарь)

Одни и те же учётные данные используются серверами nextcloud-contacts (CardDAV) и nextcloud-calendar (CalDAV). Анонимного режима нет, учётные данные обязательны. При включённой двухфакторной аутентификации пароль веб-входа не подходит, нужен пароль приложения:

  1. Войти в веб-интерфейс своего Nextcloud.
  2. Открыть Настройки → Безопасность → Устройства и сессии → Создать новый пароль приложения.
  3. Записать в .env: NEXTCLOUD_URL=<базовый URL инстанса>, NEXTCLOUD_USER=<логин>, NEXTCLOUD_APP_PASSWORD=<пароль приложения>.

Переменная TIMEZONE (IANA-имя, например Europe/Saratov) задаёт часовой пояс для дат без явного смещения; её используют серверы mail и nextcloud-calendar. Без неё действует значение по умолчанию Europe/Saratov.

Источники серверов: https://altlinux.space/shaba/nextcloud-contacts-mcp, https://altlinux.space/shaba/nextcloud-calendar-mcp.

MATTERMOST_URL / MATTERMOST_TOKEN — корпоративный Mattermost

Сервер mattermost работает локально через uvx mcp-server-mattermost (stdio) и ходит в корпоративный инстанс https://mm.srt.basealt.ru. 39 инструментов: каналы, сообщения, треды, реакции, файлы, поиск, unread.

Особенность: вход в инстанс только через OIDC, парольной аутентификации нет, поэтому для API нужен personal access token:

  1. Войти на https://mm.srt.basealt.ru через OIDC в браузере.
  2. Открыть Profile → Security → Personal Access Tokens → Create Token (если раздела нет - опция EnableUserAccessTokens выключена админом, см. fallback ниже).
  3. Записать в .env: MATTERMOST_TOKEN=<токен>. MATTERMOST_URL уже выставлен в конфигах, переопределять не нужно.

Fallback, если PAT выключены: извлечь токен сессии из браузера после OIDC-входа (DevTools → Application → Cookies → MMAUTHTOKEN). Такой токен работает как Bearer, но живёт до конца сессии и требует периодической замены.

Токен действует от вашего имени: отправленные сообщения видны как ваши. Гейтинга инструментов у сервера нет, права ограничиваются только ролями аккаунта в Mattermost.

Источник сервера: https://github.com/cloud-ru-tech/mcp-server-mattermost (ставится через uvx из PyPI, без фиксации версии - всегда latest).

telegram — кластерный Telegram MCP

Сервер работает не локально, а в кластере giran (cluster/telegram-mcp/ репозитория giran-orchestra) и отдаёт общий HTTP-эндпоинт http://telegram-mcp.k8s.lan/mcp. Один процесс обслуживает всех трёх агентов: Telegram ограничивает число параллельных сессий аккаунта и ломает их при использовании с разных IP (AUTH_KEY_DUPLICATED).

Используется MTProto от имени пользователя, а не Bot API: только так видна история личных чатов и отправка идёт от вашего имени. Это userbot - Telegram ToS ограничивает автоматизацию аккаунта, массовые рассылки ведут к блокировке.

Источник: https://github.com/chigwell/telegram-mcp (ставится через uvx из git без фиксации версии - всегда latest).

Секреты (api_id, api_hash, session_string) лежат в SOPS-секрете cluster/telegram-mcp/secrets.yaml, в репозитории - только шифротекст. Строка сессии равна полному доступу к аккаунту и не должна попадать в git, чат или конфиги агентов.

Сессию для кластера генерируют один раз, интерактивно (QR или телефон + код

  • 2FA - агент этого сделать не может):
uvx --from "git+https://github.com/chigwell/telegram-mcp" \
  telegram-mcp-generate-session --qr

Полученное значение записывается в ~/.api_keys.env как TELEGRAM_SESSION_STRING, после чего секрет кластера пересобирается и Flux перезапускает под. Сессия рабочей станции и сессия кластера должны быть разными.

Доступ ограничен: набор инструментов - только чтение плюс send_message, reply_to_message, forward_message (удаление, админка групп, контакты и профиль не регистрируются), а снаружи эндпоинт закрыт ipAllowList на Gateway - только 10.0.0.0/8. Встроенной аутентификации у сервера нет. Клиенты ходят по plain HTTP - это LAN-конвенция кластера (как у netbox-mcp): корневой CA step-ca не распространён на рабочие станции, поэтому HTTPS агенты не проверили бы.

matrix — Matrix от аккаунта пользователя

Локальный stdio-сервер mindroom-ai/matrix-mcp (ставится через uvx из PyPI, без фиксации версии - всегда latest). Работает от вашего аккаунта на https://matrix.altlinux.org: чтение истории комнат и личных чатов, поиск, отправка сообщений, реакции - 43 инструмента.

В отличие от Telegram, общий кластерный инстанс не нужен: Matrix access token допускает параллельные соединения, поэтому каждый агент запускает свой stdio-процесс.

Настройка - та же, что у остальных серверов: заполните в .env переменные MATRIX_USER_ID, MATRIX_ACCESS_TOKEN и MATRIX_DEVICE_ID. matrix-mcp не принимает credentials через окружение (только через свой конфиг), поэтому запуск идёт через обёртку scripts/matrix-mcp-run.sh: при первом старте она сама создаёт конфиг ~/.config/matrix-mcp/config.json из переменных .env. Отдельных команд выполнять не нужно, а перенос на новую машину сводится к переносу заполненного .env. Сам токен в репозиторий не попадает.

Где взять токен: на matrix.altlinux.org включён только вход через SSO (ALT Linux ID), парольной аутентификации нет. Варианты:

  1. Войти в веб-Element (https://app.element.io, указав homeserver matrix.altlinux.org) и скопировать токен: Настройки → Справка и о программе → Access Token. MATRIX_DEVICE_ID - ID той же сессии (список сессий в настройках) либо из ответа GET /_matrix/client/v3/account/whoami с этим токеном. Без MATRIX_DEVICE_ID сервер отвечает "credentials are incomplete". В FluffyChat токен в интерфейсе не показывается.

  2. Либо не заполнять .env, а один раз выполнить интерактивный SSO-вход (агент этого сделать не может):

    uvx --from matrix-mcp matrix-mcp auth sso \
      https://matrix.altlinux.org --idp-id tuwunel
    

    Команда откроет браузер со страницей ALT Linux ID, сохранит конфиг и сразу настроит E2EE-устройство. Это единственный путь, дающий E2EE из коробки.

Access token равен полному доступу к аккаунту - не публикуйте его. В .env он живёт там же, где остальные ключи проекта.

Деструктивные инструменты (redact, kick, ban) помечены MCP- аннотациями destructiveHint/readOnlyHint; при желании их можно отфильтровать на стороне клиента. Отдельного read-only режима у сервера нет.

E2EE поддерживается в stdio-режиме: сервер создаёт своё Matrix-устройство, ключи импортируются из Element (matrix-mcp e2ee --help). При настройке через .env E2EE включён не будет (устройство принадлежит Element) - для шифрованных комнат используйте SSO-вход (вариант 2 выше) либо matrix-mcp e2ee setup. Без E2EE в зашифрованных комнатах виден только ciphertext.

Серверы без ключей

  • gitoskop — публичный read-only API git.altlinux.org.
  • alt-rdb — публичная база пакетов ALT (packages.altlinux.org), ключей нет.
  • mediawiki-altlinux — публичная вики, настроена только на чтение.
  • hedgedoc — анонимный доступ к https://hdoc.lian.su, токен не требуется.

Структура

.
├── .crushrc                 # конфигурация MCP для Crush (bash-формат)
├── .kimi-code/mcp.json      # конфигурация MCP для kimi-code
├── .opencode/opencode.json  # конфигурация MCP для opencode
├── .env.example             # шаблон файла с ключами
├── Makefile                 # сборка всех MCP-серверов из mcp/
├── scripts/                 # обёртки запуска (matrix-mcp-run.sh: провижининг из .env)
├── mcp/                     # исходники MCP-серверов (git-сабмодули)
│   ├── mail-mcp/
│   │   └── mail-mcp         # бинарник после `make` (mcp/<имя>/<имя>)
│   └── ...
└── README.md

Проверка

После заполнения .env запустите агента и проверьте список инструментов:

crush   # серверы видны через встроенные MCP-инструменты

Если у сервера нет инструментов — обычно это значит, что отсутствует или отклонён его ключ (см. разделы выше).