PowerOffice MCP for Codex

Servidor MCP local para que Codex acceda de forma segura a PowerOffice Go API v2 con operaciones de solo lectura y operaciones de escritura explícitamente confirmadas. El servidor funciona con DEMO API, usa OAuth 2.0 Client Credentials y proporciona herramientas pequeñas y explícitamente limitadas en lugar de un proxy HTTP universal.

Lo que ya está disponible

• poweroffice_configuration_status — comprueba si existe configuración sin revelar los valores de las claves.

• poweroffice_connection_info — comprueba la conexión y devuelve las integraciones/privilegios disponibles.

• poweroffice_search_customers — busca clientes con filtros y paginación.

• poweroffice_get_customer — obtiene un cliente por su ID numérico.

• poweroffice_list_general_ledger_accounts — lee el plan de cuentas.

• poweroffice_list_account_transactions — lee las transacciones de cuenta dentro de un rango de fechas obligatorio.

• poweroffice_create_customer — crea un cliente después de confirm=true.

• poweroffice_update_customer — aplica el JSON Patch permitido a un cliente después de confirm=true.

• poweroffice_create_general_ledger_account — crea una cuenta contable después de confirm=true.

• poweroffice_update_general_ledger_account — aplica el JSON Patch permitido a una cuenta contable después de confirm=true.

Las herramientas de lectura siguen siendo de solo lectura. Las herramientas de escritura solo modifican datos cuando se pasa explícitamente confirm=true; las operaciones de eliminación, contabilización y envío de documentos no forman parte de esta etapa.

Related MCP server: SceneBoard MCP for Codex

Requisitos

• Node.js 22 o superior

• pnpm 11

• PowerOffice application key, client key y subscription key

• los roles de acceso necesarios para los endpoints a los que se llame

Instalación

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

Complete .env.local localmente:

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 está excluido de Git. No envíe las claves al chat ni las añada a .codex/config.toml.

Conexión con Codex

El archivo de proyecto .codex/config.toml ya ejecuta el dist/index.js compilado a través de STDIO. Lee .env.local si el archivo existe y también puede obtener las variables enumeradas desde el entorno del proceso de Codex.

Después de pnpm build, reinicie la tarea de Codex para este proyecto. Empiece llamando a poweroffice_configuration_status y luego a poweroffice_connection_info.

Desarrollo local

pnpm dev
pnpm typecheck
pnpm test
pnpm build
pnpm smoke

El servidor escribe únicamente mensajes MCP en stdout; los errores de arranque van a stderr. Los tokens se almacenan en caché con un margen antes de su expiración; ante un 401 se realiza una sola renovación del token, y ante un 429, hasta dos reintentos con una espera de al menos un segundo para las solicitudes de lectura. Las solicitudes de escritura no se reintentan automáticamente para evitar duplicados. La frecuencia general de solicitudes está limitada por el valor de PO_MAX_REQUESTS_PER_SECOND y no puede superar 10.

Variables de entorno

Para producción, cambie PO_ENV=production; la URL del token y la API las selecciona el código, no las introduce el usuario.

Límites del MVP

• Solo PowerOffice API v2 y transporte STDIO.

• No hay webhooks, ni recorrido automático de todas las páginas, ni operaciones de eliminación, contabilización y envío de documentos.

• Las herramientas de escritura están limitadas a Customers y GeneralLedgerAccounts y requieren confirm=true.

• El campo Fields se puede sobrescribir, pero por defecto el servidor solicita conjuntos de datos compactos.

• La siguiente página siempre se solicita explícitamente mediante pageNumber; los metadatos del encabezado X-Pagination se devuelven junto con el resultado.

Documentación: PowerOffice Developer Portal, MCP en Codex.