e-arveldaja-mcp

e-arveldaja MCP サーバー

エストニアの e-arveldaja（RIK e-Financials）REST API 用の MCP サーバーです。標準プロファイルでは126個のツール、16個のワークフロープロンプト、15個のリソースを利用できます。Claude Code、Codex CLI、Gemini CLI、Cursor、Windsurf、Cline など、あらゆる MCP クライアントで動作します。

年次決算は、RIK の方式に従うようになりました（0.26.0、動作変更）。 execute_year_end_close は、収益勘定と費用勘定を 2970 に振り替えて残高をゼロにしなくなりました（e-arveldaja 自体の損益計算書に不具合が生じていたためです）。ガイド「Äriühingu majandusaasta lõpetamiskanded e-arveldajas」にある RIK の 2 つの仕訳を計上します。12 月 31 日に D 9000「Arvestuslik koondtulemus」／K 2970、1 月 1 日に D 2970／K 2960（任意で一部を準備金に振り替え）です。すでに手動で計上済みの仕訳は、伝票番号を問わず、1 月 1 日または翌年のそれ以降の日付で計上されていても、旧形式の YECL-YYYY 決算仕訳を含めて検出され、二重計上されることはありません。一部のみの仕訳、取り消し済みの仕訳、重複仕訳、または不一致の仕訳は、手動確認が必要なものとして報告されます。0.26.0 ではほかにも、月末チェックリストが月の途中では今日を基準に期限超過請求書を評価するようになり、attach_document は replace_existing: true を指定しない限り既存の原資料を置き換えなくなり、Lightyear の売却仕訳は明細書に示された現金額を計上し、Wise のインポートで確定済みの仕入請求書が変更されなくなりました。詳細は変更履歴をご覧ください。

⚠️ 0.22.0 を使用した場合は対応が必要です（入金取引が逆方向に計上されています）。 0.22.0 には重大度の高いリグレッションがあり、新しく作成されたすべての銀行取引が「出金」方向に強制されていました。そのため、入金仕訳（出資者からの入金、顧客からの入金、返金、口座間の入金振替）が逆方向に計上されていました（現金が逆側に計上され、残高が誤った方向に金額の 2 倍だけ動いていました）。元帳の貸借は一致していたため、エラーは発生しませんでした。この問題は 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 は、自然言語で指定された目標に対して、最も安全な会計ワークフローを提案します。また、主要なワークフロー／バッチツールは、recommended_next_action、確認事項、承認プレビューを含む workflow_action_v1 エンベロープを返します。ワークスペースのトリアージには 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 アドレスからアクセスできるようになります。ノート PC や 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バンドル（概念ごとに1つのMarkdownファイルを格納したディレクトリ）として保存されます。このリポジトリに同梱されている未変更のaccounting-rules.mdは汎用テンプレートにすぎず、チェックアウト先にルールを固定するものではありません。新しいストアは、ユーザーごとの設定ディレクトリ（~/.config/e-arveldaja-mcp/accounting-rules/<identity-digest>、またはプラットフォームに相当する場所）内の不透明なIDスコープを使用するため、異なる会社間で生成されたルールが共有されることはありません。このスコープは、変更可能な表示ラベルではなく、秘密情報を含まない安定した接続フィンガープリントから導出されます。接続ラベルを変更しても、会計ルールのストアは移動しません。データを含む既存のプロジェクトストアと、スコープのない古いグローバルストアは、後方互換性のためそのまま保持されます。次の2つの環境変数を指定すると、保存場所を引き続き正確に上書きできます。

• EARVELDAJA_RULES_DIR=/path/to/bundle — バンドルの保存先として、会社ごとに固定のパスを指定します（例：~/.config/e-arveldaja-mcp/<company>/accounting-rules）。複数の会社を運用する場合に推奨されます。
• EARVELDAJA_RULES_FILE=/path/to/accounting-rules.md — 従来の単一ファイル形式を選択します。ルールはその1つのファイルに保存されます（バンドルなし、移行なし）。既定のバンドルモードでは、バンドルと同じ場所に既存のaccounting-rules.mdがある場合、初回の書き込み時に内容を破壊せずバンドルへ移行します。

このバンドルは、earveldaja://accounting_knowledgeのMCPリソースとして閲覧することもできます。複数のMCPクライアントが同じバンドルディレクトリを共有する場合、ルールの同時書き込みはロックファイルによって直列化されるため、インデックスと各概念の内容が不整合になることはありません。

4. 開始残高（algbilanss）

開始残高は、operation_type=INITIALとしてe-arveldajaから直接取得されます。勘定残高、明細書、年次報告書、配当の確認には、登録済みで削除されていない開始仕訳が、元の日付、取引先、ディメンションとともに含まれます。INITIALが存在しない場合、計算では残りのAPI仕訳が通常どおり使用されます。年間キャッシュフローには開始時点の残高は含まれません。

旧import_opening_balancesツールとローカルの開始残高台帳への対応は削除されました。既存のローカルopening-balances.jsonファイルは変更されずに残りますが、今後読み込まれることはありません。開始残高はe-arveldajaで管理してください。

ツールの構成を絞り込む

EARVELDAJA_PROFILEで明示的に1つの構成を選択します。guidedは、オプトインで利用する日常の記帳向け19ツール構成です。guided-salesは、販売向けファサードであるmanage_sale_invoiceを追加します（20ツール）。これにより、2段階の呼び出しによる準備・実行の承認ゲートを通じて、請求書の読み取りと、販売請求書のライフサイクル全体（作成／更新／削除／確定／無効化／送信／定期設定、および顧客のインライン解決または作成）を行います。standardは、環境変数が指定されていない場合の互換性を保つ既定値（126ツール）です。fullでは、詳細な認証情報管理と設定モードの認証情報管理を含む146個すべてのツールを利用できます。guided以外のすべての構成には、実行中のバージョン、有効なプロファイル、現在有効な利用時リリース通知を簡潔に報告する読み取り専用の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）と VAT しきい値プロンプトを除外します。suggest_booking による法定税務規則のアドバイスには影響しません。VAT しきい値、配当、経費精算、非課税限度額に関するワークフローを実行しない場合に使用してください。
• EARVELDAJA_DISABLE_REFERENCE_ADMIN=1 — 銀行口座や請求書シリーズの作成・更新・削除、および請求書設定の更新を行う参照データ管理ツール（単一レコードを読み取る get_bank_account／get_invoice_series も含む）を除外します。list_*／get_invoice_info／get_vat_info の読み取りは引き続き利用できます。勘定科目表、銀行口座、請求書シリーズの設定と管理を e-arveldaja の UI ですでに行っている場合に使用してください。
• 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 を含む）を設定した、仕入側のみを扱う軽量なカスタムデプロイでは、標準の 126 個に対して 85 個のツールを使用します。一方、EARVELDAJA_PROFILE=full では、146 個すべてのツールを利用できます。

EARVELDAJA_DOCUMENT_READING=1（オプトイン、デフォルトでは無効）を設定すると、アシスタントが請求書を 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 プロンプト）

サーバーには、あらゆる MCP クライアントが検出して使用できる、16 個の組み込みワークフロープロンプトが含まれています。これらのプロンプトは、複数ステップにわたる会計タスクを 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 アシスタントに話しかけるだけです。

受信トレイ形式の概要から開始する

「このワークスペースをスキャンして、自動でできること、判断が 1 つ必要なこと、会計士のレビューが必要なことを教えてください」

これは、会計士ではない方に推奨される最初のステップです。アシスタントは会計受信トレイのフローを使用して、CAMT ファイル、Wise CSV エクスポート、レシートフォルダーの候補を検出します。適切な順序で安全な dry-run 手順を提案し、推奨するデフォルト値を最初に提示したうえで、不足している情報について必要最小限の追加質問のみをします。

会計受信トレイやワークフローの推奨に関する応答には、done、needs_decision、needs_review、recommended_next_action、available_actions、approval_previews を含む workflow ブロックがあります。これにより、すべてのツールから手動で選ぶのではなく、クライアントは簡潔な次のステップから処理を続けられます。

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 など）に対応しています。

現時点では、Statements または Reports にある特別な明細／レポートのエクスポートではなく、Wise Transactions から通常の取引 CSV をエクスポートする必要があります。Wise のサポートはまだ十分にテストされていません。インポートで問題が発生した場合は、issue を作成するか、報告してください。

財務レポートを作成する

「2026 年 2 月 28 日時点の損益計算書と貸借対照表を作成してください」

銀行取引を照合する

「未確定の銀行取引を請求書と照合してください」

口座間振替の照合は慎重に行われます。最も高い信頼度の候補が複数ある場合、振替は曖昧として報告され、推測による確定は行われません。

月次締め

「2026 年 2 月の月次締めチェックリストを実行してください」

まだ締めていない月については、期限超過の請求書は今日（エストニアの日付）時点で判定されます。月末まで支払期限が到来しない請求書は、due_before_month_end_* の下に別途一覧表示されます。

年次締め

「2025 年の年次締めを準備してください」

アシスタントは RIK の 2 件の締め仕訳（12 月 31 日の当期損益を 2970 に、1 月 1 日の利益剰余金 2960 への振替。必要に応じて一部を準備金へ振替）を提案し、既存の仕訳を表示します。承認後、不足している仕訳のみを記帳します。会計年度は暦年です。

エストニアの税務：配当とオーナー経費

「5,000 EUR の配当パッケージを準備して」

アシスタントは、法人所得税 22/78 を計算し、利益剰余金が十分か、純資産が株式資本を下回っていないか（ÄS §157）を確認したうえで、正しい仕訳で記帳を作成します。

「Bolt の 45.50 EUR の事業経費を精算して」

オーナーが立て替えた経費について、サーバーは妥当な初期設定を提示するようになりました。

• 通常の VAT 登録事業者の領収書は、仕入 VAT を全額控除する設定が初期値です
• 乗用車／燃料／接待に類する費用など、控除制限や複数用途が考えられるカテゴリでは、推測せずに確認を求めます
• 安定した社内方針がある場合は、accounting-rules.md に記述できます

更新

サーバーのセットアップ方法によって、更新手順が異なります。

npx を使用する場合

MCP 設定で npx -y e-arveldaja-mcp を実行している場合は、通常、アシスタントを再起動するか、MCP サーバーを再読み込みするだけで十分です。次回起動時に、npx が公開済みの最新バージョンを取得します。

クライアントが古いキャッシュ済みバージョンを使い続ける場合は、一度強制的に更新してください。

npx -y e-arveldaja-mcp@latest

その後、クライアントで MCP サーバーを再起動します。

ローカルの git チェックアウトから実行する場合

最新の変更を取得し、必要に応じて依存関係を再インストールしてビルドした後、アシスタントを再起動します。

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 Registry を通じて公開 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 秒）のみを再実行するため、アップロード開始時にも --otp のワンタイムパスワードが有効です。テストスイート全体は release:check と CI で実行されます。

npm login
npm publish --otp=<code>

サードパーティの snap／brew パッケージではなく、modelcontextprotocol/registry の GitHub リリースから公式の mcp-publisher バイナリを使用してください。非公式の配布経路では、最新のスキーマへの対応が遅れ、$schema のバージョンが「deprecated」として拒否される場合があります。公式の最新バイナリを ~/.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、銀行照合、認証情報の設定）は、レビュー済みの対象範囲を正確に固定する、1 回限りのサーバープランハンドルを返します。このハンドルは変更への同意ではありません。アシスタントには引き続き明示的な承認が必要です。また、プレビュー後に内容が変わった場合、レコードが作成される前にプランは拒否されます。
• すべての仕訳に証憑書類を添付してください。 attach_document / get_document / delete_document を使って、仕入請求書、売上請求書、手動仕訳、または銀行取引に証憑書類（PDF/JPG/PNG）を添付、ダウンロード、または削除できます。証憑書類がない仕訳には find_missing_documents でフラグが付けられます（エストニアの RPS 法では、すべての会計仕訳に証憑書類が必要です）。
• 会計上の選択では、証拠を優先します。 仕入の記帳では、サーバーは類似する確認済みの仕入先請求書の処理方法を優先します。その履歴がない場合は、accounting-rules.md を利用できます。一致する銀行取引の自動記帳では、根拠の弱いヒューリスティックだけに基づいて VAT の処理を推測することはなくなりました。
• 大規模なデータセットでは日付フィルターが必要です。 サーバーはクエリごとに最大 200 ページのデータを読み込みます。請求書や取引が数千件ある企業では、日付範囲を指定してレポートおよび照合ツールの対象を絞り込んでください。指定しない場合、ツールから指定を求められます。
• キャッシュ。 API レスポンスは 2～5 分間、参照データは最大 10 分間キャッシュされます。MCP ツールを使ってレコードを作成、更新、削除すると、サーバーはキャッシュを自動的に無効化します。e-arveldaja のウェブ UI で直接行った変更は、キャッシュの有効期限が切れるまで反映されません。次回の読み取りで最新の上流データを取得する必要がある場合は、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 の一時ディレクトリ（os.tmpdir()。$TMPDIR、通常は /tmp）配下にある、サポート対象のファイルにアクセスできます。EARVELDAJA_ALLOW_HOME=true を設定すると、ホームディレクトリ全体が追加されます。EARVELDAJA_ALLOWED_PATHS（コロン区切り。Windows ではセミコロン区切り）を設定すると、これらのデフォルトは指定したディレクトリだけに置き換えられます。引き続き必要な場合は、作業ディレクトリも一覧に含めてください。設定中は EARVELDAJA_ALLOW_HOME は無視されます。
• 人が編集できるローカル会計ルール。 accounting-rules.md を使うと、企業固有の記帳のデフォルト設定と年次報告書の上書き設定を、コードや JSON ではなく Markdown で保存できます。
• セッション監査ログ。 変更を伴うすべての操作（作成、更新、削除、確認、インポート）は、作業ディレクトリ内の 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 を設定すると、サーバーが標準エラー出力に書き込むすべての内容（警告、致命的エラー、および MCP トランスポート起動後の構造化ロガーの出力）が、追記モードで指定したファイルにコピーされます。デフォルトでは無効です。Linux、macOS、Windows で使用できます。MCP ホストが標準エラー出力を取得できない場合に便利です。例：EARVELDAJA_LOG_FILE=/tmp/mcp.err.log。
• OCR テキストはサンドボックス化されています。 PDF や画像から抽出した未加工の OCR 出力（raw_text、領収書行の description）は、LLM に返す前に、呼び出しごとに生成されるノンスを含む区切り文字（<<UNTRUSTED_OCR_START:{nonce}>> / <<UNTRUSTED_OCR_END:{nonce}>>）で囲まれます。これにより、スキャンした領収書を使ってエージェントのコンテキストにツール呼び出しの指示を忍び込ませることができなくなります。
• システム間でのファイル入力。 MCP サーバーがクライアント（例：Claude desktop、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／貸方 銀行）として記帳します。前払勘定から引き落とす税金費用の仕訳は、このサーバーではなく、EMTA の前払勘定明細に基づいて e-arveldaja が作成します。
• update_transaction の対象はメタデータのみです。 取引のメタデータ（銀行参照情報と摘要欄）のみを編集し、金額、仕訳、配分は変更しません。これらの変更には、照合／記帳ツールを使用してください。

プライバシー

ドキュメント（PDF、JPG、PNG）の解析には、デフォルトで LiteParse OCR をローカルで使用します。EARVELDAJA_LITEPARSE_OCR_SERVER_URL を設定すると、OCR を完全にローカルで実行する代わりに、サーバーは設定された OCR エンドポイントにドキュメントを送信します。リモート OCR エンドポイントには https を使用する必要があります。http が許可されるのは、localhost／ループバックの OCR サービスのみです。デフォルトでは、サーバーは作業ディレクトリと OS の一時ディレクトリにある、サポート対象のドキュメントファイルも読み取ることがあります。ホームディレクトリ全体も対象に含めるには EARVELDAJA_ALLOW_HOME=true を設定してください。または、デフォルトの設定を置き換える明示的な許可リストとして、EARVELDAJA_ALLOWED_PATHS（コロン区切り）を設定してください。いずれの場合も、抽出されたテキストは MCP プロトコル経由で AI アシスタントに返され、使用中の LLM（Claude、Codex、Gemini など）によって処理されます。そのため、サーバー自身の外部接続先は e-arveldaja API（rmp-api.rik.ee）、任意で仕入先検索に使用するエストニア商業登記局（ariregister.rik.ee）、および任意で設定する OCR サーバーに限定されます。

フィードバックとバグ報告

機能のリクエスト、バグ報告、正しく解析できない請求書は、GitHub Issues ページでお知らせください。

請求書を公開でアップロードしたくない場合は、[email protected] に直接メールでお送りください。

ライセンス

Apache License 2.0