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; операции удаления, проведения и отправки документов в этот этап не входят.

Related MCP server: SceneBoard MCP for Codex

Требования

• Node.js 22 или новее

• pnpm 11

• PowerOffice application key, client key и subscription key

• нужные access roles для вызываемых endpoint'ов

Установка

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

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

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.

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

pnpm dev
pnpm typecheck
pnpm test
pnpm build
pnpm smoke

Сервер пишет только MCP-сообщения в stdout; ошибки запуска идут в stderr. Токены кешируются с запасом до истечения, при 401 выполняется одно обновление токена, а при 429 — до двух повторов с задержкой не менее одной секунды для read-запросов. Write-запросы не повторяются автоматически, чтобы не создавать дубликаты. Общая частота запросов ограничена значением 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, MCP в Codex.