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

サーバーは MCP メッセージのみを stdout に書き込み、起動エラーは stderr に出力されます。トークンは有効期限前に余裕を持ってキャッシュされ、401 の場合はトークンの更新を 1 回実行し、429 の場合は読み取りリクエストに対して 1 秒以上の遅延で最大 2 回再試行します。書き込みリクエストは重複を作成しないよう自動的には再試行されません。全体のリクエスト頻度は PO_MAX_REQUESTS_PER_SECOND の値によって制限され、10 を超えることはできません。

環境変数

本番環境では PO_ENV=production に切り替えます。トークン URL と API URL はコードによって選択され、ユーザーが入力するものではありません。

MVP の制限

• PowerOffice API v2 と STDIO トランスポートのみ。

• Webhook、全ページの自動巡回、削除、転記、文書の送信操作はありません。

• 書き込みツールは Customers と GeneralLedgerAccounts に限定され、confirm=true が必要です。

• Fields フィールドは上書きできますが、デフォルトではサーバーはコンパクトなデータセットを要求します。

• 次ページは常に pageNumber で明示的に要求されます。X-Pagination ヘッダーのメタデータは結果とともに返されます。

ドキュメント: PowerOffice Developer Portal、Codex の MCP