- Shell 79.8%
- Makefile 20.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
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> |
||
| .agents/skills | ||
| .kimi-code | ||
| .opencode | ||
| mcp | ||
| mcp-features | ||
| openspec | ||
| reports | ||
| scripts | ||
| .crushrc | ||
| .env.example | ||
| .gitignore | ||
| .gitmodules | ||
| Makefile | ||
| README.md | ||
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
- Войти на https://bugzilla.altlinux.org (создать аккаунт при необходимости).
- Открыть Preferences → API Keys (https://bugzilla.altlinux.org/userprefs.cgi?tab=apikey).
- Нажать Generate a new API key, при желании ограничить права.
- Скопировать ключ в
.env.
Без ключа доступны чтение публичных багов и поиск; с ключом — комментарии, создание и изменение багов от вашего имени.
REDMINE_API_KEY — Redmine my.basealt.space
- Войти на https://my.basealt.space.
- Открыть Моя учётная запись (ссылка справа вверху).
- На боковой панели нажать Показать у пункта Ключ доступа к API и скопировать ключ (при необходимости Сбросить, чтобы сгенерировать новый).
- Записать в
.env. ПеременнаяREDMINE_URLопциональна (переопределяет базовый URL, по умолчаниюhttps://my.basealt.space).
Без ключа доступны только публичные проекты и только чтение.
ALTLINUX_SPACE_KEY — Forgejo altlinux.space
- Войти на https://altlinux.space.
- Открыть Settings → Applications (https://altlinux.space/user/settings/applications).
- В разделе Generate New Token задать имя, выбрать нужные scope
(для полной работы:
read:user,write:repository,write:issue,write:packageи т.д.) и нажать Generate Token. - Токен показывается один раз — сразу записать в
.env.
Без токена доступны только публичные репозитории (чтение).
MW_INTRANET_USERNAME / MW_INTRANET_PASSWORD — внутренняя вики ALT
Для записи во внутреннюю вики используется механизм BotPasswords:
- Войти на https://intranet.altlinux.ru под своим аккаунтом.
- Открыть Special:BotPasswords (https://intranet.altlinux.ru/wiki/Special:BotPasswords).
- Создать новый бот-пароль: задать имя бота (например
mcp) и выбрать права (минимум: чтение страниц, правка существующих, создание страниц). - Wiki вернёт логин вида
YourName@mcpи пароль. - Записать в
.env:MW_INTRANET_USERNAME=YourName@mcp,MW_INTRANET_PASSWORD=<пароль бота>.
Без ключей сервер не стартует с полным набором инструментов; чтение внутренней вики также требует авторизации.
MAIL_YANDEX_USER / MAIL_YANDEX_PASSWORD — почта Яндекса
Обычный пароль аккаунта не подходит, нужен пароль приложения:
- Включить IMAP: почта Яндекса → Настройки → Почтовые программы → С сервера imap.yandex.ru по протоколу IMAP.
- Открыть управление аккаунтом https://id.yandex.ru/security/app-passwords.
- Создать пароль приложения для типа Почта.
- Записать в
.env:MAIL_YANDEX_USER=<ваш адрес @yandex.ru>,MAIL_YANDEX_PASSWORD=<пароль приложения>.
NEXTCLOUD_URL / NEXTCLOUD_USER / NEXTCLOUD_APP_PASSWORD — Nextcloud (контакты и календарь)
Одни и те же учётные данные используются серверами nextcloud-contacts
(CardDAV) и nextcloud-calendar (CalDAV). Анонимного режима нет, учётные
данные обязательны. При включённой двухфакторной аутентификации пароль
веб-входа не подходит, нужен пароль приложения:
- Войти в веб-интерфейс своего Nextcloud.
- Открыть Настройки → Безопасность → Устройства и сессии → Создать новый пароль приложения.
- Записать в
.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:
- Войти на https://mm.srt.basealt.ru через OIDC в браузере.
- Открыть Profile → Security → Personal Access Tokens → Create Token
(если раздела нет - опция
EnableUserAccessTokensвыключена админом, см. fallback ниже). - Записать в
.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), парольной аутентификации нет. Варианты:
-
Войти в веб-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 токен в интерфейсе не показывается. -
Либо не заполнять
.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-инструменты
Если у сервера нет инструментов — обычно это значит, что отсутствует или отклонён его ключ (см. разделы выше).