PowerOffice MCP for Codex

Codex가 PowerOffice Go API v2에 안전하게 접근할 수 있도록 하는 로컬 MCP 서버로, 읽기 전용 및 명시적으로 확인된 쓰기 작업을 지원합니다. 이 서버는 DEMO API에서 작동하며 OAuth 2.0 Client Credentials를 사용하고, 범용 HTTP 프록시 대신 작고 명확하게 제한된 도구를 제공합니다.

현재 사용 가능한 기능

• 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 — confirm=true 후 허용된 JSON Patch를 고객에게 적용합니다.

• poweroffice_create_general_ledger_account — confirm=true 후 계정을 생성합니다.

• poweroffice_update_general_ledger_account — confirm=true 후 허용된 JSON Patch를 계정에 적용합니다.

읽기 도구는 읽기 전용으로 유지됩니다. 쓰기 도구는 명시적인 confirm=true가 있을 때만 데이터를 변경합니다. 문서 삭제, 전기, 전송 작업은 이 단계에 포함되지 않습니다.

Related MCP server: SceneBoard MCP for Codex

요구 사항

• Node.js 22 이상

• pnpm 11

• PowerOffice application key, client key 및 subscription key

• 호출하는 엔드포인트에 필요한 access roles

설치

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

서버는 stdout에 MCP 메시지만 쓰고, 시작 오류는 stderr로 출력됩니다. 토큰은 만료 전 여유를 두고 캐시되며, 401 발생 시 토큰을 한 번 갱신하고, 429 발생 시 읽기 요청에 대해 최소 1초 지연으로 최대 두 번 재시도합니다. 쓰기 요청은 중복을 만들지 않도록 자동으로 재시도하지 않습니다. 전체 요청 빈도는 PO_MAX_REQUESTS_PER_SECOND 값으로 제한되며 10을 초과할 수 없습니다.

환경 변수

프로덕션에서는 PO_ENV=production으로 전환하세요. 토큰 및 API URL은 코드에서 선택되며 사용자가 입력하지 않습니다.

MVP 경계

• PowerOffice API v2 및 STDIO 전송만 지원합니다.

• Webhook, 전체 페이지 자동 탐색, 문서 삭제, 전기 및 전송 작업은 없습니다.

• 쓰기 도구는 Customers 및 GeneralLedgerAccounts로 제한되며 confirm=true가 필요합니다.

• Fields 필드는 재정의할 수 있지만 기본적으로 서버는 간결한 데이터 세트를 요청합니다.

• 다음 페이지는 항상 pageNumber를 통해 명시적으로 요청되며, X-Pagination 헤더 메타데이터가 결과와 함께 반환됩니다.

문서: PowerOffice Developer Portal, Codex의 MCP.