e-arveldaja-mcp

e-arveldaja MCP 服务

适用于爱沙尼亚 e-arveldaja（RIK e-Financials）REST API 的 MCP 服务。标准配置包含 126 个工具、16 个工作流提示词和 15 个资源。可与任何 MCP 客户端搭配使用，包括 Claude Code、Codex CLI、Gemini CLI、Cursor、Windsurf、Cline 等。

年末结账现已遵循 RIK 的方法（0.26.0，行为变更）。 execute_year_end_close 不再将收入和费用账户结转至 2970（这会导致 e-arveldaja 自身的损益表出错）。现在会根据指南“Äriühingu majandusaasta lõpetamiskanded e-arveldajas”记入 RIK 要求的两笔分录：12 月 31 日，借记 9000“Arvestuslik koondtulemus”／贷记 2970；1 月 1 日，借记 2970／贷记 2960（可选择将部分金额计入储备资本）。系统会检测你已手动记入的分录——无论凭证编号为何、是在 1 月 1 日还是次年更晚时间记入，也包括旧版 YECL-YYYY 结账分录——且不会重复记账；部分分录、已冲销分录、重复分录或不匹配的分录会报告出来，供人工审核。0.26.0 的其他更新：月末检查清单会在月份尚未结束时按当天日期判断逾期发票；attach_document 在未设置 replace_existing: true 时不会替换现有源文件；Lightyear 卖出交易会按对账单显示的金额记入现金；Wise 导入不再更改已确认的采购发票。详情请参阅更新日志。

⚠️ 如果你使用过 0.22.0，必须采取行动（入账的收款方向相反）。 0.22.0 中存在严重回归问题：所有新建的银行交易都会被强制设为“支出”方向，因此收款分录——所有者注资、客户付款、退款以及账户间转入——都被反向记账（现金记在错误的一方，余额也会以相反方向变动两倍金额）。总账仍然平衡，因此不会报错。此问题已在 0.22.1 中修复。如果你在 0.22.0 仍为当前版本期间（大约为 2026-07-19 星期日 22:30 至 2026-07-20 星期一 04:15）运行过 e-arveldaja-mcp 会话，那么该时间段内创建的银行对账单分录很可能有误。请核对 e-arveldaja 报告的银行账户余额与实际余额；如果两者不同，重新导入受影响的银行对账单即可修复。详情请参阅更新日志。

标准科目表账户已修正（行为变更）。 已对照 e-arveldaja RTJ 标准科目表审查并修正所有硬编码的默认账户——此前有多个默认账户指向错误科目（例如，股息所得税负债指向 2540“ Kogumispensioni maksed”，外汇损失指向收入账户）。更重要的是，现在工具会根据爱沙尼亚语名称，在你公司实际使用的科目表中解析每个权益／负债／财务账户，仅在无法匹配时才回退到标准编号。因此，即使使用自定义科目表或重新编号的科目表，股息、股本、储备、外汇及 Lightyear 分录也会记入正确账户。如果你今年使用较早版本记过账，只读脚本 npm run audit:legacy-accounts 会标记仍留在旧默认账户中的分录。详情请参阅更新日志。

股息合法性检查现已修正。 prepare_dividend_package 现按条款逐项应用 ÄS § 157：留存收益上限按净额计算——全部留存收益余额都可作为税后股息分配，22/78 所得税则作为本期费用另行记账；净资产下限仍按总额计算。每个响应都会报告法律允许的最高税后股息（maximum_distributable.max_net_dividend）以及法定的 compliance_notes（已批准的年度报告和利润分配决议、TSD 附件 7 的截止日期）。earveldaja://tax_rules 参考资料现也涵盖利润分配（ÄS § 157、TuMS § 50）及 RPS 流程规则（更正、盘点、留存）。详情请参阅更新日志。

引导式工作流操作。 recommend_workflow 会根据自然语言目标建议最安全的会计流程；关键工作流／批处理工具会返回一个 workflow_action_v1 封装，其中包含 recommended_next_action、审核问题和审批预览。accounting_inbox 是工作区分类处理的首选整合入口，continue_accounting_workflow 是首选的整合式后续操作工具，receipt_batch 和 process_camt053 是首选的基于模式的导入／批处理入口；银行业务则提供 reconcile_bank_transactions 和 classify_bank_transactions 作为基于模式的入口。为了降低每个会话的令牌成本，较早的专用工具（例如 resolve_accounting_review_item、prepare_accounting_review_action、scan_receipt_folder、process_receipt_batch、parse_camt053、import_camt053、reconcile_transactions 和 apply_transaction_classifications）默认不会显示在工具列表中（整合后的工具会调用相同的内部逻辑）；设置 EARVELDAJA_EXPOSE_GRANULAR_TOOLS=1 可重新注册这些工具。详情请参阅更新日志。

期初余额（algbilanss）。 余额和报告会自动使用 API 的 INITIAL 日记账，并保留其原始日期、客户端和维度。无需本地导入。系统会披露 API 中草稿、已删除或为空的期初余额；存在多个有效期初余额时则需要审核。详情请参阅更新日志。

积极开发中。 此软件包仍在积极开发，尚未经过大量真实场景测试。如果你遇到错误或行为异常，请通过 GitHub Issues 或发送邮件至 [email protected] 告知我。

免责声明

这是一个实验性、非官方项目。 本项目与 RIK（Registrite ja Infosüsteemide Keskus）或 e-arveldaja / e-Financials 服务没有关联、未获其认可，也与其不存在任何官方联系。

使用本软件的风险完全由您自行承担。 本软件会与真实财务数据交互，并可能创建、修改、确认和删除会计记录（发票、日记账分录、交易等）。作者不对使用本软件造成的任何数据丢失、记账错误或其他损失承担责任。

使用本软件即表示您确认：

• 您全权负责核验所有数据和操作
• 使用真实数据前，应在演示服务上进行充分测试
• 这是实验性软件，不提供任何形式的保证

获取 API 密钥

1. 登录 e-arveldaja
2. 前往 Seadistused → Üldised seadistused → Lisa uus juurdepääsuluba（设置 → 常规设置 → 添加新的访问令牌）
3. 为令牌输入任意名称
4. 查找您的公网 IP 地址（例如访问 api.ipify.org），并将其填入允许的 IP 地址字段。多个 IP 地址可用 ; 分隔
5. 保存 — 下载 apikey.txt 文件，并将其放在运行 AI 助手的工作目录中

如果您没有静态 IP 地址，每当 IP 地址发生变化时，都需要在 e-arveldaja 设置中更新允许的 IP 地址。或者，输入 0.0.0.0/0 以允许从任何 IP 地址访问 — 这对笔记本电脑或 IP 地址会变化的情况很方便，但安全性较低，因为此时只需 apikey.txt 文件即可访问您的数据。

如果请求之后开始返回 401 Unauthorized，最常见的原因是您的公网 IP 地址发生了变化，不再与允许的 IP 地址列表匹配。请在浏览器中自行查看当前公网 IP 地址（例如访问 https://api.ipify.org），并根据需要更新 e-arveldaja 中的白名单。

切勿将 apikey.txt 文件提交到 git。

对于演示服务，请设置环境变量 EARVELDAJA_SERVER=demo。

设置

1. 添加 MCP 服务

大多数 AI 助手都可以为您完成设置 — 只需提出请求：

“使用 npx 将 e-arveldaja-mcp 添加为此项目的 MCP 服务。该软件包发布在 npm 上。”

如果您更愿意手动设置：

Claude Code：

claude mcp add e-arveldaja -- npx -y e-arveldaja-mcp

其他工具（Cursor、Windsurf、Cline、Gemini CLI、Codex CLI、Antigravity）— 将以下内容添加到 MCP 配置中：

{
  "mcpServers": {
    "e-arveldaja": {
      "command": "npx",
      "args": ["-y", "e-arveldaja-mcp"]
    }
  }
}

2. 添加 API 凭据

将下载的 apikey.txt 放在运行 AI 助手的工作目录中。首次启动时，服务会检测到该文件，并提示您验证凭据并将其导入 .env 文件 — 可选择本地导入（仅此文件夹可用）或全局导入（从任何文件夹均可使用）。

您也可以随时通过向 AI 助手提出请求来手动导入：

“从 apikey.txt 导入我的 API 密钥”

如果有多家公司，可放置多个文件（apikey.txt、apikey-company2.txt 等），并使用 list_connections / switch_connection 在它们之间切换。设置 EARVELDAJA_DEFAULT_CONNECTION=<index or name> 可选择新启动的服务默认使用的公司（默认值：索引 0）；在写入操作中传递可选的 connection 参数，则服务会拒绝任何针对非当前活动公司的调用。

3. 可选：定义公司专属会计规则

如果贵公司有稳定的记账惯例，且这些惯例并不总能仅从账簿中推导出来，可以创建一个可选的本地文件：

accounting-rules.md

该文件是可由人工编辑的 Markdown 文件，而非 JSON。它用于：

• 在缺少供应商历史记录时，设置针对交易对象的自动记账默认规则
• 设置业主费用的 VAT 抵扣默认规则或特定账户的覆盖规则
• 覆盖年度报告中的负债到期时间和现金流类别分类

默认情况下，这些规则以 Open Knowledge Format 资源包的形式存储，即一个由 Markdown 文件组成的目录（每个文件对应一个概念）。本仓库附带的未修改 accounting-rules.md 仅为通用模板，不会将规则固定到当前检出目录。新存储会在每用户配置目录下使用不透明的身份作用域（~/.config/e-arveldaja-mcp/accounting-rules/<identity-digest>，或平台对应路径），因此不同公司不会共用生成的规则。作用域由非机密的稳定连接指纹生成，而非易变的显示名称。更改连接名称不会迁移其会计规则存储。为保持向后兼容，已有包含数据的项目存储和较早的无作用域全局存储会保留在原处。以下两个环境变量仍可精确覆盖存储位置：

• EARVELDAJA_RULES_DIR=/path/to/bundle — 将资源包指定到稳定的公司专属路径（例如 ~/.config/e-arveldaja-mcp/<company>/accounting-rules）。如果要运行多家公司，建议使用此选项。
• EARVELDAJA_RULES_FILE=/path/to/accounting-rules.md — 选择旧版单文件格式：规则保留在该文件中（无资源包，也不迁移）。在默认的资源包模式下，若资源包旁存在 accounting-rules.md，则会在首次写入时将其非破坏性地迁移到资源包中。

该资源包也可通过 earveldaja://accounting_knowledge 作为 MCP 资源浏览。当多个 MCP 客户端共用一个资源包目录时，并发规则写入会通过锁文件串行处理，确保索引始终与各个概念保持同步。

4. 期初余额（algbilanss）

期初余额直接从 e-arveldaja 获取，类型为 operation_type=INITIAL。账户余额、报表、年度报告和股息检查都包含已登记且未删除的期初记账，并保留其原始日期、客户和维度。如果不存在 INITIAL，则计算会照常使用其余 API 日记账。年度现金流不包含期初余额。

已移除原有的 import_opening_balances 工具和本地期初余额登记簿支持。现有的本地 opening-balances.json 文件会保持不变，且不再读取。请在 e-arveldaja 中管理期初余额。

精简工具范围

使用 EARVELDAJA_PROFILE 选择一个明确的工具范围：guided 是包含 19 个工具、需主动选择启用的日常记账范围；guided-sales 在此基础上增加 manage_sale_invoice 销售门面（共 20 个工具）——读取发票，并在两次调用的准备/执行审批关卡后处理完整的销售发票生命周期（创建/更新/删除/确认/作废/发送/定期执行，还可直接解析或创建客户）；standard 是未设置变量时的兼容默认值（126 个工具）；full 则开放全部 146 个工具，包括细粒度和配置模式下的凭据管理。除 guided 和 guided-sales 外，每种范围还包含 get_server_status，用于精简地只读报告运行版本、当前活动配置范围，以及任何当前生效的即时发布通知。 这些配置选项一一对应：日常记账 → guided；日常记账加销售发票 → guided-sales；记账加投资 → 启用 Lightyear 的 standard；完整高级工具集 → full。此版本中的引导配置文件为可选项，并非推荐的／默认的日常操作界面。更改配置文件后，请重启并运行新的预览；旧的提案或计划句柄不能作为新配置文件下的批准。

现有的暴露标志仍保持兼容。如果明确设置了任何旧版暴露标志，有效配置文件就是 custom，这些标志仍按原有方式独立生效。经过审核的凭据导入若明确选择了命名配置文件，会从同一选定的本地／全局 .env 中移除这些旧版暴露键，这样重启后解析出的就是所选配置文件，而不是 custom；预览会列出要移除的确切键。配置文件和凭据使用同一个 .env；没有第二种配置格式。

每次会话都会将工具列表发送到模型的上下文中，因此会产生固定的会话令牌开销。若干功能组默认注册，但可选择关闭；部署不使用这些功能时，可以将其移除：

• EARVELDAJA_DISABLE_LIGHTYEAR=1 — 移除 Lightyear 投资工具（book_lightyear_*、parse_lightyear_*、lightyear_portfolio_summary）和 lightyear-booking 提示词。若公司不跟踪投资，请使用此设置。
• EARVELDAJA_DISABLE_TAX_TOOLS=1 — 移除爱沙尼亚税务辅助工具（check_vat_registration_threshold、prepare_dividend_package、create_owner_expense_reimbursement、check_tax_free_limits）和增值税门槛提示词。suggest_booking 背后的法定税务规则建议不受影响。如果从不处理增值税门槛／股息／报销／免税限额工作流，请使用此设置。
• EARVELDAJA_DISABLE_REFERENCE_ADMIN=1 — 移除用于创建／更新／删除银行账户和发票系列，以及更新发票设置的参考数据管理工具（还包括单条记录读取工具 get_bank_account／get_invoice_series）。list_*／get_invoice_info／get_vat_info 读取工具仍保留。如果会计科目表、银行账户和发票系列已设置完毕，并在 e-arveldaja 界面中管理，请使用此设置。
• EARVELDAJA_DISABLE_ANNUAL_REPORT=1 — 移除年末工具（prepare_year_end_close、generate_annual_report_data、execute_year_end_close）。一年中的大部分时间可使用此设置；到结账时再重新启用。
• EARVELDAJA_DISABLE_SALES=1 — 移除销售开票相关功能：11 个销售发票工具、create_recurring_sale_invoices 和应收账款账龄分析（compute_receivables_aging）。应付账款账龄分析和所有采购发票工具仍保留。若仅处理采购端记账，请使用此设置。
• EARVELDAJA_DISABLE_PRODUCTS=1 — 移除产品目录工具（list/get/create/update/deactivate/reactivate/delete_product）。产品主要用于销售发票的行项目目录（采购项目以 cl_purchase_articles_id 为键，但也可带有可选的 products_id），因此设置了 DISABLE_SALES 的部署通常也会设置此项。此设置仅移除目录管理；创建任一类型的发票仍可正常使用，因此这两个标志保持独立。

在仅处理采购端的精简自定义部署中，若设置所有禁用标志（包括 Lightyear），工具数量为 85 个，而标准配置为 126 个。相反，EARVELDAJA_PROFILE=full 会开放完整的 146 个工具目录。

EARVELDAJA_DOCUMENT_READING=1（选择启用，默认关闭）允许助手自行读取单张发票：process_accounting_document 增加 mode='read' 和 mode='verify' 两种模式，每个值都会与印刷文本核对，并且只会在创建草稿前向你询问服务器无法确定的问题。此设置不会增加工具，因此以上工具数量不变。

已确认的供应商历史记录仍优先于本地规则，用于确定采购记账默认值。

export EARVELDAJA_API_KEY_ID=...
export EARVELDAJA_API_PUBLIC_VALUE=...
export EARVELDAJA_API_PASSWORD=...

git clone https://github.com/iseppo/e-arveldaja-mcp.git
cd e-arveldaja-mcp
npm install && npm run build
# Then use: "node", "/path/to/e-arveldaja-mcp/dist/index.js" instead of npx

工作流（MCP 提示词）

该服务内置了 16 个工作流提示词，任何 MCP 客户端都可以发现并使用。这些提示词将引导 AI 完成多步骤会计任务：

Claude Code 也将这些提示词作为斜杠命令提供：/vat-registration-threshold、/accounting-inbox、/resolve-accounting-review、/prepare-accounting-review-action、/book-invoice、/receipt-batch、/import-camt、/import-wise、/classify-unmatched、/reconcile-bank、/month-end、/new-supplier、/company-overview、/lightyear-booking、/setup-credentials、/setup-e-arveldaja。

使用示例

连接 MCP 服务后，只需用自然语言与 AI 助手交流：

从收件箱式概览开始

“扫描此工作区，并告诉我哪些事项可以自动处理、哪些需要做出一项决定、哪些需要会计师审核”

对于非会计人员，建议从这一步开始。助手将使用会计收件箱工作流，识别可能的 CAMT 文件、Wise CSV 导出文件和收据文件夹，按正确顺序提出安全的 dry-run 步骤，并优先给出建议的默认选项，只询问最少的待补充问题。

会计收件箱和工作流建议的回复包含一个 workflow 块，其中包括 done、needs_decision、needs_review、recommended_next_action、available_actions 和 approval_previews，客户端因此可以沿着一个简洁的后续步骤继续操作，而不必手动在所有工具中做选择。

从 PDF 文件录入采购发票

“将此发票 PDF 录入 e-arveldaja，并与银行付款匹配”

助手将从 PDF 中提取发票数据；如果有同一供应商的类似已确认发票，则沿用其记账处理方式，否则会依据采购商品或本地会计规则处理，然后创建发票并将其与银行交易匹配。

批量处理文件夹中的发票和收据

“处理 arved/ 文件夹中的所有发票，并将它们录入 e-arveldaja”

助手会扫描文件夹，对每个 PDF/JPG/PNG 文件进行 OCR 解析，提取发票数据、匹配供应商并检测重复项，然后预览可自动录入的内容。此流程分阶段进行，而非一次完成：只有在你批准预览后，才会创建并上传 PROJECT（草稿）采购发票；确认这些发票以及将其与银行交易匹配，则需要分别进行后续审批。采购录入的默认设置优先取自已确认的供应商历史记录，其次取自 accounting-rules.md（如果存在）。默认采用试运行模式，便于你在提交前检查。 如果成功创建发票，但后续步骤（例如上传单据或确认）失败，工具现在会自动作废已创建的采购发票，并将对应文件报告为失败，而不会留下多余的草稿。

录入 Lightyear 投资交易和收入

下载你的 Lightyear 账户对账单 CSV 和资本利得报告，然后：

“从这些 Lightyear CSV 创建 e-arveldaja 日记账分录”

助手会解析交易、配对外币兑换，根据 FIFO 报告计算资本利得，并使用正确的证券账户创建日记账分录。卖出时，会按对账单显示的现金金额借记经纪账户，按 Lightyear 的 FIFO 成本基础贷记投资，并将差额记为收益或损失。对账单 CSV 中的股息、基金分配和现金利息也会一并导入，默认分别记入各自的收入账户（8330、8320 和 8400）。

导入银行对账单（CAMT.053）

将银行对账单下载为 CAMT.053 XML 文件（支持 LHV、Swedbank、SEB、Coop、Luminor），然后：

“将我的 LHV 对账单 XML 中的银行交易导入 e-arveldaja”

助手会解析 ISO 20022 XML，创建金额和交易对手正确的银行交易，按银行参考号检测重复项，并处理批量分录和混合货币。默认采用试运行模式。

导入 Wise 银行交易

在 Transactions 视图中下载常规 Wise 交易 CSV，然后：

“将 transaction-history.csv 中的 Wise 交易导入 e-arveldaja”

助手会解析 CSV，根据 Wise 的 Direction 字段创建入账和出账银行交易，并将 Wise 费用单独列项，以便正确核算支出。支持 EUR 和外币银行卡付款（USD 等）。

目前，此功能需要从 Wise Transactions 导出的常规交易 CSV，而非 Statements 或 Reports 下的特殊对账单/报告导出文件。Wise 支持仍未经充分测试；如果遇到导入问题，请提交 issue 或进行反馈。

生成财务报告

“生成截至 28.02.2026 的损益表和资产负债表”

对账银行交易

“将未确认的银行交易与发票匹配”

账户间转账对账采用谨慎策略：如果多个候选匹配的最高置信度相同，系统会将该转账报告为匹配不明确并跳过确认，而不会猜测。

月末结账

“运行 2026 年 2 月的月末结账清单”

对于仍处于开放状态的月份，逾期发票按今天（爱沙尼亚日期）进行评估；到月底前仍未到期的发票会单独列在 due_before_month_end_* 下。

年末结账

“准备 2025 年年末结账”

助手会提出 RIK 的两笔结账分录（12 月 31 日将本年结果转入 2970，1 月 1 日转入留存收益 2960，可选择将部分金额转入储备资本），显示已有内容，并仅在你批准后登记缺少的分录。财年按日历年计算。

爱沙尼亚税务：股息和所有者费用

“准备一份 5000 EUR 的股息方案”

助手将计算 22/78 的企业所得税，检查留存收益是否充足以及净资产是否达到股本要求（ÄS §157），并创建记账分录，确保过账正确。

“报销我在 Bolt 的 45.50 EUR 业务费用”

对于所有者垫付的费用，服务现在会尽量提供合理的默认设置：

• 普通的已登记增值税企业收据默认全额抵扣进项增值税
• 对于可能受到限制或涉及混合用途的类别，例如乘用车、燃油或类似招待费的开支，会要求澄清，而不是自行猜测
• 如果你有固定的内部政策，可以将其写入 accounting-rules.md

更新

更新方式取决于你如何设置服务：

使用 npx

如果你的 MCP 配置运行 npx -y e-arveldaja-mcp，通常只需重启 AI 助手或重新加载 MCP 服务。下次启动时，npx 会获取最新发布的版本。

如果客户端仍在使用较旧的缓存版本，请强制刷新一次：

npx -y e-arveldaja-mcp@latest

然后在客户端中重启 MCP 服务。

从本地 git 检出运行

拉取最新更改，如有需要则重新安装依赖项，然后重新构建，最后重启 AI 助手：

git pull
npm install
npm run build

如果 MCP 配置指向 dist/index.js，则更新源代码后必须重新构建。

开发

运行集成测试套件：

npm run test:integration

现在默认会针对本地启动的服务进程运行独立的 MCP 接口检查，并使用虚拟测试凭据。实时 API 集成检查仍需主动启用，并且需要真实凭据以及：

EARVELDAJA_INTEGRATION_TEST=true npm run test:integration

发布到 MCP Registry

Claude Cowork 通过 MCP 注册表发现公开的 MCP 服务。仅推送到 GitHub 并不足够：请先将相同版本发布到 npm，然后将此仓库的 server.json 元数据发布到注册表。

发布前，请确保以下版本完全一致：

• package.json 中的 version
• package-lock.json 根包中的 version
• server.json 顶层的 version
• server.json 中的 packages[0].version

还要确保 package.json 中的 mcpName 与 server.json 中的 name 完全匹配；注册表会用它来验证 npm 包的所有权。

在发布提交上打标签前，运行全部检查（元数据、构建、单元测试和集成测试、打包后烟雾测试）：

npm run release:check

发布 npm 包。prepublishOnly 只会重新运行快速包检查（元数据、构建、打包后烟雾测试，约 30 s），因此上传开始时，--otp 提供的一次性密码仍然有效；完整测试套件会在 release:check 和 CI 中运行。

npm login
npm publish --otp=<code>

请使用来自 modelcontextprotocol/registry GitHub 发布页的官方 mcp-publisher 二进制文件，而不要使用第三方 snap/brew 软件包。非官方渠道可能无法及时跟进当前架构，并会以“已弃用”为由拒绝 $schema 版本。以下单行命令可将最新官方二进制文件安装到 ~/.local/bin（请确保该目录已加入 PATH）：

mkdir -p ~/.local/bin
curl -sSL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" \
  | tar xz -C /tmp mcp-publisher
install -m 0755 /tmp/mcp-publisher ~/.local/bin/mcp-publisher
rm -f /tmp/mcp-publisher

然后进行身份验证并发布注册表条目：

npm run registry:login
npm run registry:publish

验证已发布的条目：

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.iseppo/e-arveldaja-mcp"

实用信息

• 默认进行试运行。 批量操作（银行导入、Wise 导入、Lightyear 入账、收据处理、自动确认）会先预览结果。修改记录前必须明确确认。收据批次使用 execution_mode="create" 创建/上传未确认的 PROJECT 发票；确认是单独的审批步骤。
• 计划句柄不等于批准。 会修改数据的导入/对账工作流（CAMT、Wise、Lightyear、银行对账、凭据设置）会返回一个仅可尝试一次的服务端计划句柄，用于绑定已审阅的确切范围。该句柄不代表同意修改数据——助手仍需获得你的明确批准；如果预览和执行之间发生任何变化，计划会在创建任何记录前被拒绝。
• 每笔分录都要有来源文件。 可使用 attach_document / get_document / delete_document 为任何采购发票、销售发票、手动日记账或银行交易附加、下载或删除来源文件（PDF/JPG/PNG）；find_missing_documents 会标记缺少来源文件的分录（爱沙尼亚《会计法》（RPS）要求每笔会计分录都附有来源文件）。
• 会计处理优先依据证据。 采购入账时，服务端优先参考类似且已确认的供应商发票中的处理方式。如果缺少此类历史记录，则可以使用 accounting-rules.md。对于无法匹配的银行交易自动入账，不再仅凭薄弱的启发式规则臆测增值税处理方式。
• 大型数据集需要日期筛选。 服务端每次查询最多加载 200 页数据。拥有数千张发票或笔交易的公司应为报告和对账工具指定日期范围，否则工具会要求你指定。
• 缓存。 API 响应会缓存 2–5 分钟，参考数据最多缓存 10 分钟。通过 MCP 工具创建、更新或删除记录时，服务端会自动使缓存失效。直接在 e-arveldaja 网页界面中进行的更改，在缓存过期前不会显示；如果需要下一次读取获取最新的上游数据，请调用 clear_cache，或向余额/报告工具传入 fresh: true。
• 默认使用 EUR。 除非指定其他币种，否则所有金额均为 EUR。
• 第三方付款人。 e-arveldaja 会将银行收款记在交易的客户（付款人）名下，因此由他人支付发票时，应收款贷方会记入错误的客户明细账。除非传入 reassign_client_to_invoice: true，否则 confirm_transaction 会拒绝此类确认（linked_invoice_client_mismatch）；每次确认与发票关联的交易后，它都会检查生成的登记日记账；而 reconcile_bank_transactions 会将这些情况列入 third_party_payer_reviews，而非自动确认。使用 run_accounting_report 并设置 report: "receipt_client_alignment" 可审计现有账簿。
• 多公司。 放置多个 apikey*.txt 文件，并使用 list_connections / switch_connection。切换时会清除前一连接和目标连接的缓存数据，因此不会向其他公司提供某家公司的记录。活动连接按服务端进程分别设置：如果 MCP 宿主重启服务端，它会恢复为 EARVELDAJA_DEFAULT_CONNECTION 指定的连接（索引或名称；默认索引为 0；未知值会导致启动失败）。配置了多个连接时，每个非只读工具都接受可选的 connection 参数（索引或名称）；如果调用时提供的值不是活动连接，系统会在发送任何 API 请求前以 connection_mismatch 拒绝调用，因此你可以在每次写入操作中固定目标公司，而不必依赖之前调用的 switch_connection。
• 需要 Node.js 18+。
• 文件访问范围。 默认情况下，文件读取工具可访问工作目录和操作系统临时目录（os.tmpdir()：$TMPDIR，通常为 /tmp）下的受支持文件。EARVELDAJA_ALLOW_HOME=true 会添加整个主目录。EARVELDAJA_ALLOWED_PATHS（以冒号分隔；Windows 上使用分号）会将这些默认目录替换为所列的目录；如果仍需访问工作目录，也请将其列入；设置此变量时会忽略 EARVELDAJA_ALLOW_HOME。
• 可由人工编辑的本地会计规则。 使用 accounting-rules.md 可以通过 Markdown 存储公司专属的入账默认规则和年度报告覆盖规则，而无需修改代码或 JSON。
• 会话审计日志。 每项会修改数据的操作（创建、更新、删除、确认、导入）都会记录到工作目录下的 logs/{connection}.audit.md 人类可读 Markdown 文件中。每条记录都包含时间戳、工具名称、实体详情、科目分录和金额。使用 get_session_log 查看、使用 list_audit_logs 浏览所有公司，使用 clear_session_log 重置。日志会跨会话保留，并按公司分别记录。设置 EARVELDAJA_AUDIT_LANG=en 可使用英文标签（默认：爱沙尼亚语）。
• 标记 MCP 创建的发票。 设置 EARVELDAJA_TAG_NOTES=true，可在服务端创建的所有发票的备注字段中追加 (e-arveldaja-mcp)。默认关闭。
• 调试日志文件。 设置 EARVELDAJA_LOG_FILE=/path/to/mcp.err.log，即可将服务端写入 stderr 的所有内容（警告、致命错误，以及 MCP 传输启动后结构化日志记录器的输出）同时追加到指定文件。默认关闭。支持 Linux、macOS 和 Windows。当 MCP 宿主会吞掉 stderr 时，此功能很有用；示例：EARVELDAJA_LOG_FILE=/tmp/mcp.err.log。
• OCR 文本经过隔离处理。 将 PDF 和图像的原始 OCR 输出（raw_text、收据行 description）包裹在每次调用专属的随机数分隔符（<<UNTRUSTED_OCR_START:{nonce}>> / <<UNTRUSTED_OCR_END:{nonce}>>）中，再返回给 LLM，这样扫描的收据就无法将工具调用指令夹带到 Agent 的上下文中。
• 跨系统文件输入。 如果 MCP 服务运行在与客户端不同的主机上（例如 Claude 桌面应用、Cowork、Cursor 或远程容器），文件读取工具也接受格式为 base64:<b64data>（适用于 PDF / PNG / JPEG / CAMT XML）或 base64:<ext>:<b64data>（例如 base64:csv:QSxCLEMK...）的 file_path，因此客户端上的文件无需再存在于服务端文件系统中。

非目标（由 e-arveldaja 原生处理）

有些事项特意不在本项目的范围内，因为 e-arveldaja 已经能够处理这些事项；在 MCP 层重复处理可能会导致重复入账：

• 不处理 VAT/KMD 申报（käibedeklaratsioon）。 e-arveldaja 会根据已确认的总账原生生成 KMD，并提交给 EMTA。服务的税务规则层（earveldaja://tax_rules）仅提供建议——它为入账决策提供信息，但不会生成或提交申报。
• 不处理 EMTA 预缴账户税务分录。 向 EMTA（Maksu- ja Tolliamet）转账时，会记为预缴账户充值（借方 ettemaksukonto / 贷方银行）；扣减该账户的税务费用分录由 e-arveldaja 根据其 EMTA 预缴账户对账单创建，而不是由本服务创建。
• update_transaction 仅作用于元数据。 它只会编辑交易元数据（银行参考信息和描述字段），不会更改金额、过账或分配。请使用对账／入账工具处理这些事项。

隐私

默认情况下，文档解析（PDF、JPG、PNG）会在本地使用 LiteParse OCR。如果设置了 EARVELDAJA_LITEPARSE_OCR_SERVER_URL，服务会将文档发送到指定的 OCR 端点，而不是完全在本地进行 OCR。远程 OCR 端点必须使用 https；仅 localhost／回环地址的 OCR 服务可使用普通 http。默认情况下，服务还可能读取工作目录和操作系统临时目录下受支持的文档文件；设置 EARVELDAJA_ALLOW_HOME=true 可将整个主目录也纳入范围，或者设置 EARVELDAJA_ALLOWED_PATHS（以冒号分隔）指定明确的允许列表，以替换默认范围。无论哪种情况，提取出的文本都会通过 MCP 协议返回给你的 AI 助手，因此会由你使用的大模型（Claude、Codex、Gemini 等）处理。因此，服务自身的出站连接仅限于 e-arveldaja API（rmp-api.rik.ee）、可选的爱沙尼亚商业登记处（ariregister.rik.ee，用于查询供应商），以及可选的你所配置的 OCR 服务。

反馈和 Bug 报告

欢迎通过 GitHub Issues 页面提交功能请求、Bug 报告，以及无法正确解析的发票。

如果你不想公开上传发票，也可以直接将其通过电子邮件发送至 [email protected]。

许可证

Apache License 2.0