# Atera MCP для Codex

Самостоятельный MCP-сервер для официального Atera REST API.

Текущий vertical slice уже содержит:

- MCP `stdio` transport с legacy/modern protocol negotiation;
- `atera_health_check` и `atera_capabilities`;
- чтение Customers, Agents, Tickets и Alerts;
- авто-выбор legacy `X-API-KEY` или Bearer JWT, с ручным override;
- timeout, cancellation, rate limiting, `Retry-After` и retry безопасных GET;
- нормализованные ошибки и управляемая политика мутаций (запись и удаления включены по умолчанию).

Полный каталог всех Atera endpoint’ов добавляется после импорта актуального OpenAPI. Инструкция: [docs/OPENAPI_IMPORT.md](docs/OPENAPI_IMPORT.md). Reference baseline по доменам: [REFERENCE_COVERAGE.md](docs/REFERENCE_COVERAGE.md).

Локальный tenant-экспорт уже проверен: OpenAPI 3.0.4, 81 paths и 136 операций (69 GET, 35 POST, 19 PUT, 13 DELETE). Файл находится в `openapi-private/` и намеренно исключён из git; при старте сервер публикует эти операции как дополнительные MCP tools.

## Запуск

```bash
npm install
npm run typecheck
npm test
npm run build
npm run openapi:validate -- openapi-private/atera-openapi.json
```

Последняя команда проверяет импортированную tenant-схему до перезапуска Codex. Если файла ещё нет, она завершится с понятной диагностикой.

Переменные задаются через окружение; шаблон находится в [.env.example](.env.example). Минимально нужен `ATERA_API_TOKEN` или legacy `ATERA_API_KEY`.

```bash
ATERA_API_TOKEN='…' npm start
```

Секрет не добавлять в git и не передавать в аргументах MCP tool.

## Подключение к Codex

В конфигурации Codex добавить локальный сервер. На macOS/Linux путь к Node.js проверьте командой `which node`, на Windows — `where node`:

```toml
[mcp_servers.atera]
command = "/opt/homebrew/bin/node"
args = ["/Users/vardahei/Documents/atera-mcp/dist/src/index.js"]
startup_timeout_sec = 30

[mcp_servers.atera.env]
ATERA_API_TOKEN = "<Atera token>"
ATERA_BASE_URL = "https://api.atera.com/api/v3"
ATERA_AUTH_MODE = "bearer"
ATERA_OPENAPI_PATH = "/Users/vardahei/Documents/atera-mcp/openapi-private/atera-openapi.json"
ATERA_WRITE_ENABLED = "true"
ATERA_ENABLE_DESTRUCTIVE_OPERATIONS = "true"
```

Запись и удаления включены по умолчанию. Их можно отключить локально, установив соответствующее значение в `false`. Возможности всё равно ограничиваются правами Atera token.

## Установка сотрудником из GitHub

Сотрудник может дать Codex такую задачу на любой поддерживаемой ОС:

```text
Установи Atera MCP из https://github.com/Oleksandr-Kliuiev/atera-mcp.
Определи мою ОС. На macOS/Linux выполни scripts/install-codex.sh, на Windows — scripts/install-codex.ps1.
Не запрашивай и не выводи мой Atera token в чат. После установки объясни, как добавить мой token локально в окружение MCP-сервера atera.
```

Для macOS/Linux можно выполнить локально:

```bash
git clone https://github.com/Oleksandr-Kliuiev/atera-mcp.git ~/.local/share/codex/atera-mcp
~/.local/share/codex/atera-mcp/scripts/install-codex.sh
```

Для Windows PowerShell:

```powershell
$dir = Join-Path $HOME ".local\share\codex\atera-mcp"
git clone https://github.com/Oleksandr-Kliuiev/atera-mcp.git $dir
& "$dir\scripts\install-codex.ps1"
```

Требования для всех ОС: Git, Node.js 20+ и установленный Codex CLI. На Windows скрипт запускается из PowerShell; при политике выполнения, запрещающей локальные скрипты, используйте `powershell -ExecutionPolicy Bypass -File .\scripts\install-codex.ps1`.

Installer устанавливает зависимости, собирает сервер и регистрирует stdio MCP в Codex. Каждый сотрудник добавляет только собственный `ATERA_API_TOKEN`; общий token в репозитории отсутствует. По умолчанию запись и удаления включены; при необходимости их можно отключить через `ATERA_WRITE_ENABLED=false` и `ATERA_ENABLE_DESTRUCTIVE_OPERATIONS=false`.