DIY Accounting Submit

@diy-accounting-uk/diya-submit

DIY Accounting Submit の申告用 MCP です（../private.diyaccounting.co.uk/engineering/submit/archive/PLAN_SUBMISSION_MCP.md）。公開済みの @diy-accounting-uk/diya-gl エンジンで顧客の帳簿を開き、申告に必要な数値を導き出し、このサービスのエンドポイントを通じて VAT 申告書と小規模企業の決算書を提出します。このパッケージは骨組みです。サーバー、stdio トランスポート、2 つの帳簿ツールが含まれます。数値の導出と申告を行うツールは、計画の後続項目です。

実行

npm --prefix mcp install
node mcp/bin/diya-submit-mcp.js

引数なしで、このコマンドを MCP クライアントに指定してください。サーバーは mcp/lib/server.js です。stdio エントリーポイントはサーバーを標準入力と標準出力に接続するだけなので、ホスト型トランスポートでは同じサーバーを別のトランスポートに接続します。

ホスト型

同じサーバーがサイトの /mcp で稼働しており、URL で接続するチャットクライアントから利用できます。Claude（Web、デスクトップ、モバイル、または Cowork）でカスタムコネクターとして https://submit.diyaccounting.co.uk/mcp を追加するか、Claude Code で次のように設定します。

claude mcp add --transport http diya-submit https://submit.diyaccounting.co.uk/mcp

クライアントは /.well-known/oauth-protected-resource/mcp を通じてサインイン先を検出し、自身を登録します。その後、ユーザーは Submit アカウントでサインインします。ci 用の URL は https://ci-submit.diyaccounting.co.uk/mcp です。ホスト型ツールセットは lib/hosted-tools.js の HOSTED_TOOL_NAMES です。open_book が読み取るのは DIYA クラウドのみです。サインイン用のペア、ファイルシステムツール、引き続き HMRC トークンを必要とする会計事務所向けツール、および run_for_clients は登録されません。

HMRC の不正防止データ

HMRC は、各リクエストを送信するデバイスに関するデータを必要とします。2 つの接続方式では異なるデータを送信します。

• stdio サーバーは DESKTOP_APP_VIA_SERVER です。HMRC のルートを呼び出すたびに、デバイス ID（~/.config/diya-submit/device-id に保存）、ローカル IP アドレス、MAC アドレス、オペレーティングシステムのユーザー、タイムゾーン、オペレーティングシステムとデバイスのモデル、および画面情報を読み取ります。ウィンドウがないため、Gov-Client-Window-Size は送信しません。
• ホスト型エンドポイントは OTHER_VIA_SERVER です。Submit が信頼できるよう署名したうえで、/mcp に接続した呼び出し元のパブリックアドレスを渡します。AI クライアントはデバイスデータを提供しません。

ツール

ツール	内容
open_book	パスから帳簿を読み込みます。book.toml と lines.jsonl を含むディレクトリ、またはエンジンが読み取る単一ファイル（ワークブック、パッケージ ZIP、diya-gl ZIP、diya-gl JSON ファイル）を指定します。プロダクト、エンティティ、期間、行数、帳簿チェックの概要を返します。
save_book	セッションの帳簿を、diya-gl-dir、diya-gl-zip、json、xlsx、zip のいずれかの形式でパスに書き込みます。最後の 2 つでは、サイトのテンプレートからプロダクトのワークブックを作成します。
derive_itsa_quarterly_update	自営業者の帳簿から、HMRC の Self Employment Business API に提出する 1 期間分を作成します。課税年度内の期間自体の数値は日付付き期間サマリーとして、年度内の 4 月 6 日からの累計は累積期間サマリーとして提出されます（2025-26 年度以降）。periodEndDate で期間を指定します。quarterlyPeriodType は standard または calendar です。帳簿から取得できない項目は省略され、ゼロとして送信されることはありません。
derive_itsa_annual_submission	年次申告用の年間控除額と調整額を作成します。対象は、その課税年度に HMRC が受け付ける項目（sa103-mtd-mapping.json の api.years）に限定されます。path を指定すると、サイトの年次申告ページでインポートできる JSON ファイルとしても書き出されます。
request_hmrc_authorisation	このセッション用の HMRC サインインリンクを返します。services は vat（デフォルト）と itsa、hmrcAccount は live（デフォルト）または synthetic です。url、expiresAt、scope、hmrcAccount を返します。ユーザーは HMRC のページでアクセスを許可します。Submit は HMRC のトークンを保持し、セッションの残りの期間にわたってアクセストークンを更新します。トークンがチャットに渡されることはありません。
list_vat_obligations	vrn（または clientId）の VAT 申告義務を、from、to、status で絞り込みます。セッションの HMRC 認証を使用します。hmrcAccount（デフォルトでは認証に使用したアカウント）と govTestScenario は任意です。
submit_vat_return	periodStart から periodEnd までの期間について、確認済みの 7 つのボックス（vatDueSales、vatDueAcquisitions、vatReclaimedCurrPeriod、totalValueSalesExVAT、totalValuePurchasesExVAT、totalValueGoodsSuppliedExVAT、totalAcquisitionsExVAT）を、vatNumber または clientId の申告として提出します。セッションの HMRC 認証を使用します。receipt、periodKey、receiptId を返します。
get_vat_receipt	name（<receiptId>.json）で指定した保存済みの受領証を取得します。clientId は任意です。
render_micro_entity_accounts_sandbox	確認済みの数値から作成した零細企業向け iXBRL をレンダリングします。Companies House ゲートウェイには接続しません。入力項目：companyNumber、companyName、periodStart、periodEnd、balanceSheet、averageEmployees、director、statementsAccepted。
render_small_company_accounts_sandbox	確認済みの数値から作成した小規模企業向け（FRS 102 section 1A）iXBRL をレンダリングします。ゲートウェイには接続しません。入力項目：companyNumber、companyName、periodStart、periodEnd、averageEmployees、director、statementsAccepted（小規模企業向けの 4 つのステートメント）、smallCompany（filleted、principalActivity、accountingPolicies、directors、balanceSheet、profitAndLoss、fixedAssetNote）。
request_companies_house_codes	チャットの代わりにユーザーが Companies House のコードを入力するリンクを返します。kind は accounts、confirmation-statement（提出順の directors を指定）、または confirmation-statement-data です。entryId、url、expiresAt を返します。エントリーの有効期間は 10 分で、提出呼び出し 1 回で使用済みになります。clientIds（companyNumber は指定しない）を指定すると、ページで実務のクライアントごとに 1 つのコードを求めます。run_for_clients 経由の場合も含め、各クライアントの提出呼び出しでは、それぞれに対応するコードのみが使用されます。
submit_micro_entity_accounts_sandbox	リンクでユーザーが入力したコードを使用し、同じ数値を提出します。コードは codesEntryId で指定し、submissionNumber を返します。
submit_small_company_accounts_sandbox	codesEntryId で指定したコードを使用し、companyNumber または clientId の小規模企業の数値を提出します。submissionNumber を返します。kind が accounts の poll_submission で結果を確認します。
poll_submission	submissionNumber で指定した Companies House への提出結果を返します。kind は accounts または confirmation-statement です。結果は PENDING、ACCEPT（receiptId を含む）、または REJECT（rejections を含む）です。
申告ツールは、MCP 独自のサインインベアラー（sign_in）を使用して、デプロイ済みの REST API を DIYA_SUBMIT_BASE_URL に呼び出し、202 応答が終端ステータスになるまでポーリングします。リクエストを送信する前に、必須の入力を検証します。

セッションごとにメモリ上で扱う帳簿は 1 冊です。open_book を実行すると、現在の帳簿が置き換えられます。2 つの ITSA ツールは lib/itsa-tools.js にあり、 registerItsaTools(server, session) を通じて登録されます。

テスト

npm --prefix mcp test
npm --prefix mcp run test:system

test:system はリポジトリのルートから npm run start:simulator を起動し、バンドルを付与して、request_hmrc_authorisation で HMRC の認可を開始し、コールバックページと同じ方法で完了します。その後、シミュレーターが返す未処理の義務を使用して、list_vat_obligations、submit_vat_return、get_vat_receipt を実行します。リポジトリのルートから実行する npm run test:mcpHmrcGrantBehaviour-simulator は、ブラウザーで HMRC の同意ページを経由して、同じ認可手続きを進めます。設計については ../../private.diyaccounting.co.uk/engineering/submit/archive/PLAN_MCP.md を参照してください。

テストでは、test/fixtures/ にある BrickWork Pro Ltd と Precision Code Ltd のサンプル帳簿（スプレッドシートリポジトリの examples/ をコピーしたもの）を開き、テンプレートを必要としない 3 つの形式それぞれで往復変換します。ITSA テストでは、BrickWork Pro の自営業者向け VAT 帳簿（examples/brickwork-pro/se-vat）を開き、課税年度ごとの四半期累計と年次項目セットを検証します。