アーキテクチャ
基本方針: AIが解釈し、OpenTax が検証して記録する
OpenTax は、永続的な記録と決定的な計算を担います。外部書類の読み取り、銀行明細の形式の解釈、勘定科目や税区分の提案はエージェント側の役割です。MCP アダプターにも、推論やファイル内容を解釈するコードは含まれません。
エージェント → MCP アダプター → 認証付き OpenTax HTTPS API → ドメインサービス → Firestore / Storageエージェントは元資料を読み、構造化されたリクエストを作ります。MCP アダプターはそれを OpenTax の HTTPS API に転送し、ドメインサービスが所有者の確認・会計上の妥当性・下書き/確認待ちの状態・監査履歴を強制します。
境界と責務
- 認証: すべての API リクエストは共通の
AuthContextを使います。Firebase ID トークンは Web ユーザー、otk_トークンはスコープ付きで取り消し可能なエージェント接続を表します。データは常に認証済みユーザーの UID 配下からのみ取得されます。 - エージェントトークン: 暗号学的に安全な 32 バイトの乱数から生成します。Firestore には SHA-256 ハッシュと表示用の短いプレフィックスのみを保存し、生のトークンは保存しません。生のトークンが返るのは作成時のレスポンスだけです。
- 仕訳の検証: ドメインサービスで行います。会計期間の導出、税額の計算、証憑の所有者確認を行い、貸借が一致した有限の正の金額と、有効な勘定科目・取引元・税区分コードを要求します。エージェントによる書き込みは必ず「確認待ち」から始まり、Web ユーザーが確認画面で確定します。
- 冪等性: 冪等キーはユーザーと操作ごとにスコープされます。同じキーによる作成は Firestore トランザクションで直列化され、再試行時には既存の結果を返します。日付と金額が同じでも、別の取引は別の取引として扱います。
- 監査: 監査ログには、操作者の種別と ID、変更前後の値、操作日時、理由を記録します。旧形式の
auto仕訳は、破壊的な移行をせずに確認待ちとして解釈します。 - 請求書: 合計額と源泉徴収は OpenTax の請求計算関数で算出します。エージェントによる請求書の書き込みは下書きのみです。
- 固定資産: エージェントは個別の作成/更新 API を使います。Web UI の一括置換 API はユーザー専用の互換用経路として残しています。
- レポート: 損益計算書・貸借対照表・税額プレビューは、Web と MCP で同じサービスを使います。正式な XTX 出力は、確認待ちまたは旧形式
autoの仕訳が残っている年度を拒否します（409 REVIEW_REQUIRED）。 - 証憑: OCR や分類をせずに保存します。旧メタデータを持つ既存の証憑は読み取り可能なまま残り、新規書き込みではそのメタデータを省きます。
データアクセス
リポジトリの Firestore / Storage ルールは、クライアントからの直接アクセスをすべて拒否します。Next.js サーバーは、すべての API リクエストを認証・認可したうえで Admin SDK を使ってデータにアクセスします。これにより、監査ログや会計上の検証を迂回した書き込みを防いでいます。
MCP の拡張方針
- 新しい MCP ツールは、既存のドメインサービスとスコープを再利用します。
- 申告や確定を伴う新しい操作には、人による確認の設計を必ず含めます。
- OpenTax 本体や MCP アダプターに、推論・形式判定・分類の機能を追加しません。
接続方法とツール一覧は MCP 接続ガイド を参照してください。