# PowerOffice MCP for Codex

Локальный MCP-сервер для безопасного доступа Codex к PowerOffice Go API v2 с read-only и явно подтверждаемыми write-операциями. Сервер работает с DEMO API, использует OAuth 2.0 Client Credentials и предоставляет небольшие, явно ограниченные инструменты вместо универсального HTTP proxy.

## Что уже доступно

- `poweroffice_configuration_status` — проверяет наличие конфигурации, не раскрывая значения ключей.
- `poweroffice_connection_info` — проверяет соединение и возвращает доступные интеграции/привилегии.
- `poweroffice_search_customers` — ищет клиентов с фильтрами и пагинацией.
- `poweroffice_get_customer` — получает одного клиента по числовому ID.
- `poweroffice_list_general_ledger_accounts` — читает план счетов.
- `poweroffice_list_account_transactions` — читает проводки за обязательный диапазон дат.
- `poweroffice_create_customer` — создаёт клиента после `confirm=true`.
- `poweroffice_update_customer` — применяет разрешённый JSON Patch к клиенту после `confirm=true`.
- `poweroffice_create_general_ledger_account` — создаёт счёт после `confirm=true`.
- `poweroffice_update_general_ledger_account` — применяет разрешённый JSON Patch к счёту после `confirm=true`.

Read-инструменты остаются read-only. Write-инструменты изменяют данные только при явном `confirm=true`; операции удаления, проведения и отправки документов в этот этап не входят.

## Требования

- Node.js 22 или новее
- pnpm 11
- PowerOffice application key, client key и subscription key
- нужные access roles для вызываемых endpoint'ов

## Установка

```bash
pnpm install
cp .env.example .env.local
pnpm build
pnpm test
```

Заполните `.env.local` локально:

```dotenv
PO_ENV=demo
PO_APPLICATION_KEY=...
PO_CLIENT_KEY=...
PO_SUBSCRIPTION_KEY=...
PO_USER_AGENT=poweroffice-mcp/0.1 your-email@example.com
```

`.env.local` исключён из Git. Не отправляйте ключи в чат и не добавляйте их в `.codex/config.toml`.

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

Проектный файл `.codex/config.toml` уже запускает собранный `dist/index.js` через STDIO. Он читает `.env.local`, если файл существует, и также может получить перечисленные переменные из окружения процесса Codex.

После `pnpm build` перезапустите Codex-задачу для этого проекта. Начните с вызова `poweroffice_configuration_status`, затем `poweroffice_connection_info`.

## Локальная разработка

```bash
pnpm dev
pnpm typecheck
pnpm test
pnpm build
pnpm smoke
```

Сервер пишет только MCP-сообщения в stdout; ошибки запуска идут в stderr. Токены кешируются с запасом до истечения, при `401` выполняется одно обновление токена, а при `429` — до двух повторов с задержкой не менее одной секунды для read-запросов. Write-запросы не повторяются автоматически, чтобы не создавать дубликаты. Общая частота запросов ограничена значением `PO_MAX_REQUESTS_PER_SECOND` и не может превышать 10.

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

| Переменная | Обязательна | Значение по умолчанию |
| --- | --- | --- |
| `PO_ENV` | нет | `demo` |
| `PO_APPLICATION_KEY` | да | — |
| `PO_CLIENT_KEY` | да | — |
| `PO_SUBSCRIPTION_KEY` | да | — |
| `PO_USER_AGENT` | нет | `poweroffice-mcp/0.1` |
| `PO_REQUEST_TIMEOUT_MS` | нет | `30000` |
| `PO_MAX_REQUESTS_PER_SECOND` | нет | `10` |

Для production переключите `PO_ENV=production`; URL токена и API выбираются кодом, а не вводятся пользователем.

## Границы MVP

- Только PowerOffice API v2 и transport STDIO.
- Нет webhook'ов, автоматического обхода всех страниц, операций удаления, проведения и отправки документов.
- Write-инструменты ограничены Customers и GeneralLedgerAccounts и требуют `confirm=true`.
- Поле `Fields` можно переопределить, но по умолчанию сервер запрашивает компактные наборы данных.
- Следующая страница всегда запрашивается явно через `pageNumber`; метаданные заголовка `X-Pagination` возвращаются вместе с результатом.

Документация: [PowerOffice Developer Portal](https://developer.poweroffice.net/), [MCP в Codex](https://learn.chatgpt.com/docs/extend/mcp).