# Kontur.Elba MCP

MCP-сервер для управления данными в [Контур.Эльбе](https://elba.kontur.ru/) через официальный Elba Public API.

Сервер работает локально по `stdio`, передаёт API-ключ только в заголовке `X-Kontur-ApiKey` и разрешает запросы только к операциям из приложенной OpenAPI-схемы.

## Возможности

- получение доступных организаций;
- создание и просмотр банковских счетов;
- создание, поиск и просмотр контрагентов;
- создание, обновление, поиск и просмотр товаров;
- работа с новостями по документам и подписками;
- создание счетов, актов, накладных и УПД;
- проверка долгих операций;
- создание, изменение, получение и удаление публичных ссылок;
- получение шаблонов документов;
- просмотр параметров каждой операции прямо через MCP.

Полный контракт API сохранён в [`openapi.json`](./openapi.json).

## 1. Получите API-ключ

1. Откройте Эльбу.
2. Нажмите **«Настройки и оплата» → «Настройки сервиса»**.
3. Откройте вкладку **API**.
4. Нажмите **«Выпустить ключ»**.
5. Скопируйте ключ и сохраните его в менеджере секретов: повторно Эльба его не покажет.

Не добавляйте ключ в код, `.env` в Git или переписку. Если ключ раскрыт, отзовите его в Эльбе и выпустите новый.

## 2. Установите и соберите сервер

Требуется Node.js 20 или новее.

```bash
git clone https://github.com/apo100l/elba-kontur-mcp.git
cd elba-kontur-mcp
npm install
npm run build
```

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

```bash
npm install --global elba-kontur-mcp
```

В конфигурации MCP в этом случае используйте команду `elba-kontur-mcp` без `args`.

## 3. Подключите MCP-клиент

Укажите абсолютный путь к `dist/index.js` и передайте ключ через окружение.

### Codex

Добавьте сервер в `~/.codex/config.toml`:

```toml
[mcp_servers.kontur_elba]
command = "node"
args = ["/absolute/path/to/elba-kontur-mcp/dist/index.js"]

[mcp_servers.kontur_elba.env]
ELBA_API_KEY = "ваш-api-ключ"
```

После изменения конфигурации перезапустите Codex.

### Claude Desktop

Добавьте сервер в `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kontur-elba": {
      "command": "node",
      "args": ["/absolute/path/to/elba-kontur-mcp/dist/index.js"],
      "env": {
        "ELBA_API_KEY": "ваш-api-ключ"
      }
    }
  }
}
```

Перезапустите Claude Desktop.

### Другой MCP-клиент

Запускаемая команда:

```bash
ELBA_API_KEY="ваш-api-ключ" node /absolute/path/to/elba-kontur-mcp/dist/index.js
```

`stdout` занят протоколом MCP. Диагностические сообщения сервер выводит только в `stderr`.

## Инструменты MCP

| Инструмент | Назначение |
|---|---|
| `elba_list_operations` | Список разрешённых операций; поддерживает поиск |
| `elba_describe_operation` | Параметры, JSON-тело и ответы операции |
| `elba_list_organizations` | Быстро получить организации по API-ключу |
| `elba_request` | Выполнить любую операцию из OpenAPI-схемы |

Перед созданием или изменением данных сначала вызовите `elba_describe_operation`, чтобы получить точную структуру тела запроса.

Примеры запросов ассистенту:

- «Покажи мои организации в Эльбе».
- «Найди операции для работы с контрагентами».
- «Покажи схему создания счёта, но пока ничего не создавай».
- «Создай контрагента в организации … с такими реквизитами: …».

## Настройки окружения

| Переменная | Обязательна | Значение по умолчанию |
|---|---:|---|
| `ELBA_API_KEY` | да | — |
| `ELBA_API_BASE_URL` | нет | `https://elba-api.kontur.ru` |
| `ELBA_API_TIMEOUT_MS` | нет | `30000` |

`ELBA_API_BASE_URL` полезен для тестового прокси. Не меняйте его на недоверенный адрес: сервер отправляет туда API-ключ.

## Разработка

```bash
npm run check
npm test
```

При обновлении API замените `openapi.json`, затем выполните проверку и тесты. Клиент автоматически использует список маршрутов из схемы.

## Версионирование и публикация

Проект использует [Semantic Versioning](https://semver.org/lang/ru/):

- `patch` — исправления без изменения совместимости;
- `minor` — новые обратно совместимые возможности;
- `major` — несовместимые изменения MCP-инструментов или конфигурации.

Перед выпуском обновите [`CHANGELOG.md`](./CHANGELOG.md), убедитесь, что ветка `main` чистая, затем выберите тип версии:

```bash
npm run release:patch
# или npm run release:minor
# или npm run release:major
```

Команда обновит версии в `package.json` и `package-lock.json`, создаст коммит и Git-тег. Отправьте их вместе:

```bash
git push origin main --follow-tags
```

Тег `vX.Y.Z` запускает workflow `.github/workflows/publish.yml`: он сверяет тег с версией пакета, выполняет тесты и публикует пакет с provenance.

Для публикации добавьте в настройках GitHub-репозитория секрет Actions `NPM_TOKEN` с npm automation/granular access token. Ограничьте токен только этим пакетом и правом публикации.

## Безопасность

- ключ не записывается в логи и ответы MCP;
- произвольные URL и неизвестные маршруты отклоняются;
- сетевой запрос ограничен таймаутом;
- ошибки API возвращаются без заголовков запроса;
- `.env` исключён из Git.

Любой MCP-инструмент с операциями `POST`, `PUT` или `DELETE` может менять данные в Эльбе. Проверяйте организацию, идентификаторы и тело запроса перед подтверждением действия.

## Лицензия

[MIT](./LICENSE)