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 引擎打开客户的账簿，推导申报所需的数据，并通过此服务的端点处理增值税申报表和微型实体账目。此软件包是一个骨架：包含服务器、stdio 传输和两个账簿工具。推导和申报工具列在计划的后续部分。

运行

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

不带参数地将 MCP 客户端指向此命令。服务器位于 mcp/lib/server.js；stdio 入口点只负责将其连接到标准输入和标准输出，因此托管传输会将同一服务器连接到另一种传输。

托管

同一服务器也在网站的 /mcp 后端运行，供通过 URL 连接的聊天客户端使用。在 Claude（网页、桌面版、移动版或 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 要求提供每个请求所用设备的数据。两种接入方式发送的数据不同。

• stdio 服务器属于 DESKTOP_APP_VIA_SERVER。每次调用 HMRC 路由时，它都会读取设备 ID（存储于 ~/.config/diya-submit/device-id）、本地 IP 地址、MAC 地址、操作系统用户、时区、操作系统和设备型号，以及屏幕信息。它没有窗口，因此不会发送 Gov-Client-Window-Size。
• 托管端点属于 OTHER_VIA_SERVER。它会传递调用方访问 /mcp 时使用的公网地址，并对其签名，使 Submit 可以信任该地址。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。后两种格式会使用网站的模板生成产品工作簿。
derive_itsa_quarterly_update	根据自雇账簿生成 HMRC 自雇业务 API 的一个期间数据：税年内该期间的自身数据以带日期的期间摘要形式申报；从某年 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 期间提交已确认的七个栏位（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 第 1A 节）iXBRL，不连接网关。输入：companyNumber、companyName、periodStart、periodEnd、averageEmployees、director、statementsAccepted（四项小型公司声明）以及 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。该条目有效期为十分钟，且只能用于一次申报调用。提供 clientIds（不提供 companyNumber）时，页面会要求每个代理机构客户分别输入一个代码；每位客户的申报调用（包括通过 run_for_clients 发起的调用）只会使用该客户自己的代码。
submit_micro_entity_accounts_sandbox	使用用户通过该链接输入的代码提交相同数据，代码由 codesEntryId 指定；返回 submissionNumber。
submit_small_company_accounts_sandbox	使用 codesEntryId 指定的代码，为 companyNumber 或 clientId 提交小型公司数据；返回 submissionNumber。使用 poll_submission，并将 kind 设为 accounts，查询结果。
poll_submission	查询 Companies House 申报结果，kind 为 accounts 或 confirmation-statement，并提供 submissionNumber：PENDING、ACCEPT（附带 receiptId）或 REJECT（附带 rejections）。
申报工具会使用 MCP 自身的登录承载令牌（sign_in）调用 DIYA_SUBMIT_BASE_URL 上部署的 REST API，并轮询 202 响应，直到其状态变为终态。它们会在发出任何请求前验证必填输入。

每个会话内存中只保留一本账簿。open_book 会替换当前账簿。两个 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/ 中示例的副本），并将每本账簿分别通过三种无需模板的格式进行往返转换；ITSA 测试会打开 BrickWork Pro 自雇 VAT 账簿（examples/brickwork-pro/se-vat），并按纳税年度检查季度累计金额和年度字段集。