Ekwo OS — open source accounting: ledger, invoices and VAT on your own Supabase or Postgres

@ekwo-ai/mcp

Ekwo OS 用の Model Context Protocol サーバーです。AI エージェントが、ユーザー自身の Postgres 上にある帳簿を操作できるようにします。元帳の読み取り、請求書の発行と記帳、入金の照合、VAT 申告書の準備などを、ユーザー本人として、そのインストール環境独自の行レベルセキュリティのもとで行えます。

利用方法は 2 つありますが、どちらも同じサーバーです。

ホステッド版：https://mcp.ekwo.ai/mcp

サーバーを起動するのではなく、リモートサーバーを追加するクライアント向けです。claude.ai など、Streamable HTTP に対応するクライアントで利用できます。インストールは不要で、パスワードやキーを設定ファイルに書き込む必要もありません。

https://mcp.ekwo.ai/mcp

クライアントをこのアドレスに接続すると、必要な情報が自動的に検出されます。認証されていない呼び出しには、サーバーの保護対象リソースのメタデータ（RFC 9728）を示す WWW-Authenticate ヘッダーを付けて 401 が返されます。クライアントはその情報をたどって認可サーバー（RFC 8414）に接続し、自身を登録します（RFC 7591。クライアント自身の認証情報は不要です）。その後、ユーザーをブラウザーに誘導して接続の承認を求めます。要求されるスコープは books です。

ブラウザーを使わずにこれを読み込んでいるエージェントは、/.well-known/oauth-protected-resource から処理を開始できます。

帳簿は元の場所に保管されます。ホステッドサーバーは帳簿を保持せず、ユーザーが承認時に選んだインスタンスに接続します。同じ画面で、エージェントに書き込みを許可するかどうかも指定できます。許可しない場合は読み取りのみです。ホステッドサーバーは Ekwo Cloud が運営しており、そこでサインインするにはアカウントが必要です。住所と 6 桁のコードで無料アカウントを作成すると、同じ帳簿を利用する Web アプリケーションと、連携するすべての会社の毎晩のバックアップも使えるようになります。

ローカル版：stdio 経由

npx -y @ekwo-ai/mcp@latest

Claude Desktop、Claude Code、および .mcp.json を読み込むエディターなど、サーバーを起動するクライアント向けです。アカウントなしで、あらゆるインストール環境に接続できます。コマンドには @latest を指定してください。リポジトリのクローン内で単に npx @ekwo-ai/mcp を実行すると、ビルドされていないワークスペースのパッケージが見つかり、ekwo-mcp: command not found と表示されます。

コマンドラインをインストールすると、ekwo mcp で同じサーバーを起動できます。エントリーポイントは同じ runStdio() で、フラグ（--autopilot、--review）と環境も同じです："command": "ekwo", "args": ["mcp"]。

概要と、できないこと

このサーバーは独自の権限を持ちません。利用者としてサインインするか、その利用者のアクセストークンを渡されます。その後に実行できることは、すべてその利用者が実行できることと同じです。閲覧者は読み取りのみ可能で、書き込みはできません。ある会社のメンバーは別の会社を閲覧できません。締め済み期間への記帳は拒否されます。このパッケージ自体では、これらの確認を行いません。スキーマのポリシーとトリガーが判断し、サーバーはその結果を報告します。

このサーバーが決して行わないことは 3 つあります。

• 元帳の明細を直接書き込むこと。 すべての仕訳は、会計ルールを適用するスキーマ独自の関数から作成されます。直接挿入するのは、利用者が入力する連絡先、下書きの書類とその明細、入金、銀行取引です。
• 記帳済みの仕訳を削除または編集すること。 仕訳を削除するツールはありません。記帳済み請求書の取り消しは、その国で認められた方法で行います。内容がまだ外部に出ていなければ下書きに戻し、それ以外の場合は該当する請求書を示すクレジットノートを発行します。手入力された仕訳は、反対仕訳で取り消します。
• service_role キーを使用すること。 使用すれば動作しますが、それこそが問題です。すべてのポリシーを迂回するため、エージェントはユーザーが招待されたことのない会社にも回答できてしまいます。このサーバーは、そのキーがあると起動を拒否します。

設定

推奨方法：サインインしたユーザーとして PostgREST を利用する

{
  "mcpServers": {
    "ekwo": {
      "command": "npx",
      "args": ["-y", "@ekwo-ai/mcp@latest"],
      "env": {
        "SUPABASE_URL": "https://YOURREF.supabase.co",
        "SUPABASE_ANON_KEY": "your anon (publishable) key",
        "EKWO_EMAIL": "[email protected]",
        "EKWO_PASSWORD": "your password"
      }
    }
  }
}

この設定ブロックは、Claude Desktop では claude_desktop_config.json に、Claude Code ではプロジェクトのルートにある .mcp.json に記述します。すでにセッションがある場合は、EKWO_ACCESS_TOKEN を指定すると、アドレスとパスワードの代わりに使えます。パスワードを使う場合、セッションはメモリ内に保持されて更新され、ディスクには何も書き込まれません。

フォールバック：Postgres への直接接続

データベースの前段に PostgREST を置かないセルフホスト環境、または テスト向けです。

{
  "env": {
    "EKWO_DB_URL": "postgresql://…",
    "EKWO_ACT_AS_USER_ID": "the auth.users id this server acts for"
  }
}

EKWO_ACT_AS_USER_ID は必須です。これがこのモードの要点です。 データベース接続は誰のものでもありません。auth.uid() は null になり、行レベルセキュリティは満たされるのではなく迂回されます。そのように動作するサーバーは、ポリシーに従うクライアントではなく、ポリシーを回避する手段になってしまいます。そのため、すべてのクエリは request.jwt.claims にそのユーザーを設定し、authenticated ロールに切り替えるトランザクション内で実行されます。ポリシーは API 経由の場合とまったく同じように適用されます。このモードでは、サーバーとともに postgres パッケージをインストールする必要があります。推奨される方法ではドライバーは一切不要です。

変数	意味
SUPABASE_URL	https://<ref>.supabase.co
SUPABASE_ANON_KEY	anon（公開可能）キーです。service_role キーは拒否されます。
EKWO_EMAIL / EKWO_PASSWORD	このエージェントが代理で操作するユーザーです
EKWO_ACCESS_TOKEN	上記 2 つの代わりに、すでに取得済みのセッションを使用します
EKWO_DB_URL	セルフホスト環境用の Postgres 直接接続先です
EKWO_ACT_AS_USER_ID	EKWO_DB_URL と併用する場合に必須です。代理で操作する auth.users の id を指定します
EKWO_NO_REGISTER_INVITE	任意です。1 を指定すると、登録への招待を手順から除外します
EKWO_NO_CLOUD_OFFER	任意です。1 を指定すると、無料の Ekwo Cloud アカウントの案内を手順から除外します。CI の場合も同様です
EKWO_AGENT_POSTING	任意です。autopilot または review を指定します。このセッションでの投稿方法を選び、--autopilot と --review で設定できます。未設定の場合は、各社の agent_posting の設定が使われます。レビューまたは自動運転を参照してください
EKWO_EINVOICE_DIRECTORY	任意です。send を指定した einvoicing_issue が電子請求書を送信するフォルダーです。未設定の場合、ファイルは発行されて保管され、送信は no_transport として拒否されます
EKWO_FISCAL_SYSTEM	任意です。einvoicing_fiscalise が会計記録を連鎖させる請求システムを JSON で指定します。name、id、version、installation、producerName、producerTaxId と、制度で必要となる場合があるブール値（verifactuOnly、multipleTaxpayers、multipleTaxpayersNow）を含めます。未設定の場合、会計処理は no_fiscal_system として拒否されます。形式が正しくない場合、サーバーは起動しません

何も設定せずに起動した場合

クライアントはサーバーを追加するとすぐにそのツール一覧を取得します。MCP サーバーをインデックス化するディレクトリーも同様です。そのため、上記の変数が何も設定されていない場合でも、または一部しか設定されていない場合でも、サーバーは起動し、ツール一覧への要求に応答します。すべてのツール呼び出しは、設定すべき変数と設定場所を示す not_configured エラーを返します。それまではどこにも接続せず、基盤機能のツールのみを提供します。インストール環境に含まれるモジュールは、データベースから読み取られます。

許容されるのは値の未設定だけです。どちらかのキーに service_role を指定した場合や、UUID ではない EKWO_ACT_AS_USER_ID を指定した場合、それらは明示的に設定された値であるため、サーバーは起動を拒否します。

npm run build -w @ekwo-ai/mcp
node packages/mcp/scripts/introspect.mjs     # starts it with no environment and lists the tools

リポジトリーのルートにある Dockerfile は、チェックアウトから同じサーバーをビルドします。docker run -i --rm <image> は標準入出力経由で MCP を使用し、変数は -e で渡します。

HTTP 経由：ほかの人向けにホストする

クライアントが起動する代わりに、URL 経由でアクセスする同じサーバーです。 handleHttpRequest は MCP のストリーミング可能な HTTPトランスポートに応答します。 ステートレスであり、リクエストごとにサーバーを構築して JSON で応答し、終了します。セッション ID はなく、何も保持しません。そのため、関数プラットフォーム、ロードバランサーの背後、または単一のプロセスで実行できます。GET には 405 で応答します。このサーバーから通信を開始することはないため、開くストリームはありません。

誰が呼び出しているかを判定することはありません。ホストが独自の方法でリクエストを認証し、そのリクエストで使用できる接続を渡します。

import { handleHttpRequest } from '@ekwo-ai/mcp';

export default async function (request: Request): Promise<Response> {
  const who = await yourOwnAuthentication(request);      // a token you issued
  if (who === undefined) return new Response(null, { status: 401 });
  return handleHttpRequest(request, {
    supabaseUrl: who.supabaseUrl,                         // https://<ref>.supabase.co
    anonKey: who.publishableKey,                          // never the service_role key
    apiKey: who.ekwoKey,                                  // or: accessToken: who.session
  });
}

接続は次のいずれか一方であり、両方になることはありません。

• インスタンス上の個人のアクセストークン。行レベルセキュリティにより、ブラウザーでその人が操作する場合と同じように判定されます。
• Ekwo OS のキー。create_api_key() で発行されます。Authorization を併記せずに X-Ekwo-Api-Key ヘッダーで送信され、スキーマのリクエスト前フックで提示されます（判断については 0062を参照）。呼び出し元は、そのキーが所属する 1 つの会社に属し、そのキーの機能を持ちます。書き込み機能なしで発行されたキーを使えば、エージェントには読み取りのみが許可されます。

service_role キーは、stdio と同様に、3 つのスロットすべてで拒否されます。 node:http（またはそれを基に構築されたもの）では、handleNodeRequest(req, res, connection, { origin }) が同じハンドラーです。

人々が利用できるようにする：認可

リモート MCP クライアントは、サーバーが認可に関する MCP 仕様の部分に従うことを想定しています。具体的には、PKCE を使用した OAuth 2.1、保護対象リソースのメタデータ（RFC 9728）、認可サーバーのメタデータ（RFC 8414）、動的クライアント登録（RFC 7591）です。これはこのパッケージではなく、ホストが担います。ホストはユーザーをサインインさせ、独自のトークンを発行し、それぞれを前述の接続に対応付けます。読み取りや書き込みが許可される内容を決める場所は、引き続きデータベースのみです。

ツール

すべての書き込みでは、会社を明示的に指定します。

ツール	機能
list_companies	所属している会社と、それぞれの会社での役割
get_company	会計年度、ロック日、仕訳帳、デフォルト勘定
list_accounts	会社が使用する勘定。コードの接頭辞、種類、または名前で絞り込めます。勘定科目表全体を取得するには include_all を指定します
search_contacts	顧客と仕入先を、名前、種類、または VAT 番号で検索します
suggest_duplicate_contacts	同一の取引先である可能性が高い連絡先を、確度の高い順に、統合対象の連絡先ごとに1行で表示します。同じ取引先である連絡先の行には、残す連絡先、スコア、根拠（同じ VAT 番号または登録番号、同じ銀行口座、該当する連絡先が少ないほど重み付けされた名前の単語）、グループ内で最も簡潔な名前（残す連絡先に適用する候補）が含まれます。データは変更しません。ユーザーが確認したペアは merge_contacts で統合できます
search_products	商品カタログ：販売品および仕入品のコード、単位、価格、勘定、税
list_documents	請求書、クレジットノート、見積書を条件で絞り込んで表示します
get_document	1件の書類と、その明細および書類によって作成された仕訳
render_invoice_pdf	販売請求書またはクレジットノートの PDF を、JSON の概要とともに PDF リソース（base64）として返します。会計帳簿から @ekwo-ai/invoice-pdf で生成します。factur_x は、転記済み販売書類の CII（Factur-X、EN 16931、PDF/A-3）を埋め込み、違反するルールを返します。labels は、書類の言語でレイアウトに表示される語句を返します。ロゴはサーバーが会社の logo_url から取得し、ローカルアドレスやプライベートアドレスから取得することはありません。記録は行いません
list_bank_accounts	会社の銀行口座と、それぞれに対応する仕訳帳および総勘定元帳の勘定
list_bank_transactions	既定では未処理の明細行
trial_balance	勘定ごとの期首残高、増減、期末残高
general_ledger	勘定の転記済み明細行すべてと、残高の推移
journal_book	1つの仕訳帳、またはすべての仕訳帳の帳簿。期間内の転記済み明細行を帳簿の表示順で並べ、先頭に各仕訳帳の合計を表示します
suggest_line_contacts	売掛金または買掛金の未消込明細行のうち、連絡先が指定されていないものについて、該当する可能性が高い連絡先を順に表示します。それぞれに根拠と、その根拠に該当した連絡先数が含まれます。データは変更しません
suggest_item_combinations	1社の取引先に関する売掛金または買掛金の未消込明細行ごとに、それを消し込む反対側の明細行を表示します。完全一致するペア、セント単位で合計が一致する複数明細行、または会社の差額許容範囲内の組み合わせと、その差額を返します。データは変更しません
matching_difference_options	差額を計上する理由と、各理由に対してパックが指定する勘定、および会社の許容差
aged_balance	総勘定元帳から読み取った、未払い残高の経過期間別内訳
vat_return	総勘定元帳から集計した期間内の申告欄
instalment_plan	会社の VAT 方式で期間内に求められる予定納税額：期限、納付済み額、未納額
ec_sales_list	欧州連合域内供給の集計明細：顧客の VAT 番号と取引の種類ごとに1行
portfolio_upcoming_filings	ポートフォリオ = 閲覧可能な会社。会計事務所の場合は顧客を指します（docs/firms.md）。filings.read 権限を持つすべての会社について、2つの日付の間に期限を迎えるものを表示します。会社ごとに最低1行を返します。期限を指定していないパックは日付なしで表示され、その旨も示します
portfolio_filings_touched_since	同じ会社群について、提出済みで、その対象期間に後から仕訳が記録された申告を、会社名とともに表示します
list_statements / financial_statement	会社が表示に使用できる様式と、1件の財務諸表
financial_analysis	分析の売上高、純損益、資本、資産合計、流動資産、現金、売掛金、買掛金、その他の集計値と、それらを構成する勘定を返します。国別パックで定義されている場合はその定義に従い、定義されていない場合は汎用フレームワークで勘定タイプ別に読み取ります。どちらの方法を使用したかは source に示されます（docs/analysis.md）
list_analytic_axes	会社の分析軸（コストセンター、プロジェクト、拠点など）と、それぞれの値を表示します。値は階層化でき、転記時に明細行全体への分析軸の指定が必須となる対象を required_on で示します
analytic_report	期間内における1つの分析軸の値ごとの収益、費用、損益、固定資産の増減を、転記済み総勘定元帳から取得します。損益計算書全体も含まれます。親項目には子項目の小計、分析軸の値が割り当てられていない部分には unassigned、合計には total を表示します（決定 0076）
generate_fec	フランスの帳簿を使用する会社について、検証結果とファイル名を含むフランス FEC をテキストで生成します
read_audit_log	誰が、いつ、何を変更したかを表示します。会社の設定と、状態を変更する操作が対象です。すべてのクライアントで追記専用であり、データベースのみが記録します
get_preferences	設定されているユーザー設定と、ラベルを読み取る際に使用する言語の優先順位
list_invitations	会社に招待されたものの、まだ参加していないユーザー
list_api_keys	会社のマシン用キーと、それぞれのキーで実行できる操作
describe_pack	このインストールで利用できる国別パックと、そのバージョン、どれだけ参照されたか、各パックの作成元となった文書の一覧（タイトル、公式発行元、リンク、確認日）を表示します。検証済みパックについては、範囲ごとに申告の種類、対象年、再現した内容、テストしていない内容を示す根拠も表示します
status	スキーマのバージョン、インスタンス、接続、会社
create_contact	顧客、仕入先、またはその他の第三者を作成します
merge_contacts	同一の取引先である2件の連絡先を統合します。統合対象の連絡先を参照するすべての情報（転記済み明細行や発行済み書類を含む）を残す連絡先に付け替え、残す連絡先の空欄を埋めます。統合対象の連絡先は無効化されます。異なる VAT 番号または登録番号を持つ2件、以前に統合された連絡先、または統合によって複数の取引先にまたがる組み合わせは、理由を明示して拒否されます
create_product	商品カタログの項目：コード、名前、単位、価格、勘定、税
update_product	項目を変更するか、active: false を指定して無効化します
pin_accounts	会社が最初に表示する作業用勘定科目表に勘定を追加するか、pinned: false を指定して勘定を外します
create_document	明細行を含む、下書きの請求書、クレジットノート、または見積書を作成します。client_ref を指定すると、2回呼び出しても作成されるのは1件だけです
update_document_lines	下書きの明細行を置き換えます
post_document	書類を、レビューまたは自動処理で記帳します（下記の「レビューまたは自動処理」）。review の場合は、担当者が現在の内容の下書きを承認した後にのみ記帳されます。そうでなければ approval_required として拒否されます。autopilot の場合は直接記帳します。どちらの場合も dry_run: true を指定すると、データベースが書き込む仕訳を返しますが、データは書き込みません
cancel_document	転記済み請求書を取り消し、undone_by に取り消し方法を示します。国の posted_edit_policy で認められ、請求書に関する情報が外部に出ていない場合は、draft に戻します（unpost_document()）。それ以外の場合は、元の請求書を指定したクレジットノートを作成し、転記して元の請求書と消し込み、請求書を取り消します（cancel_document()）。下書きに戻せない理由は why に示されます。期間が開いている場合、クレジットノートの日付は請求書の日付になります。それ以外の場合は、呼び出し元が日付を指定します。日付または credit_note: true を指定すると、クレジットノートの作成を要求します
reverse_entry	手動でキーを指定した転記済み仕訳を取り消します。反対仕訳を次の番号で転記し、元の仕訳と消し込みます。日付の規則は同じです
record_payment	入金または出金を記帳し、未消込請求書と消し込みます。document_id を指定した場合は、その書類だけを対象にし、書類から連絡先と入出金の方向を特定します。client_ref を指定すると、2回記録しても記録されるのは1回だけです
set_line_contact	この種の明細行に連絡先を指定します。連絡先が未指定の明細行に対し、会社の連絡先を一度だけ設定できます。また、そのラベルをパターンとして学習します。すでに連絡先が指定されている明細行、消し込み済みの明細行、売掛金または買掛金の勘定に属さない明細行、別の会社の連絡先を指定する場合は、理由を明示して拒否されます
leave_line_unnamed / undo_leave_line_unnamed	この種の明細行に連絡先を意図的に指定せず、その理由を記録して候補に表示されないようにします。または、その指定を取り消します
reconcile_many	1社の取引先と1つの勘定に属する複数の明細行を、借方と貸方の未消込額がセント単位で一致する場合に、1つの照合記号でまとめて消し込みます
reconcile_with_difference	差額が小さい場合に、同様の方法で消し込みます。会社の許容差の範囲内で、理由（rounding、exchange_difference）に応じてパックが指定する勘定に差額を記帳してから消し込みます
reconcile / unreconcile	総勘定元帳の2つの明細行を消し込むか、消し込みを取り消します
create_bank_account	会社の国で使われる方式の識別子（IBAN、ルーティング番号と口座番号、ソートコードと口座番号など）で銀行口座を登録し、銀行仕訳帳に接続します。同じ識別子で2回実行しても、何も作成されません
create_bank_transaction	銀行取引データの連携機能がないインストール環境で、手動で明細行を1件作成します
settle_from_statement	明細行を実際の入出金として記帳し、指定された書類または未消込項目と1つの仕訳で消し込みます。amounts では各項目に充当する金額を指定します。extra_lines では、決済事業者が差し引いた手数料や銀行手数料を、ユーザーが指定する勘定と税区分で記録します。明細行の金額がセント単位で一致しない場合は拒否されます（settlement_unbalanced）。追加明細行だけを指定して銀行手数料を決済することもできます
import_bank_statement	明細ファイル（camt.053、coda、cfonb120）を明細書と未処理明細行として取り込みます。記帳は行いません。同じファイルを2回取り込んでも何も作成されません。不明な口座や合計が一致しない明細書は理由を明示して拒否され、明細書が見つからない場合はその旨が通知されます
lock_period	会計および VAT のロック日を変更します。company.write が必要です
opening_balance	以前の帳簿の試算表を期首仕訳として記録します。年度の初日、または帳簿を引き継いだ日である年度内の opening_date を指定できます。items は、その日に未消込の請求書とクレジットノートです。それぞれに転記済み書類、番号、支払参照、期日を指定します。これらは請求書と同様に明細書との照合に使用されます。勘定ごとの項目の合計は、その勘定の明細行と一致する必要があります
import_books	別のシステムの帳簿（FEC、仕訳項目のエクスポート、仕訳帳レポート、試算表）を、全件まとめて取り込むか、まったく取り込まないかのいずれかで取り込みます。試算表の場合は open_items も合わせて取り込めます。まず dry_run: true で実行します。すべての勘定と仕訳帳に対して提案される対応関係（ファイル側と同じコードで、ファイル内に矛盾がない場合のみ exact、それ以外は理由付きの suggested、または none）、対応関係が見つからない項目、データベースで実行して取り消したインポートのリハーサル結果が返されます。次に、対応関係を完成させた mapping を指定するか、ユーザーがすべての提案を確認した後に accept_suggestions を指定して再実行します。未確認の項目がある間は、何も転記されません。すべての仕訳は post_entry() を通して処理され、税は含まれません。同じファイルを再度取り込むと、いつ何を取り込んだかを示して拒否されます。ファイルはテキストとして渡し、サイズは最大 256 KiB です。これを超える場合、ツールはディスク上のファイルを読み込む ekwo import コマンドを返します。ekwo import は同じ機能です
close_fiscal_year / reopen_fiscal_year	国別パックの規則に従って年度を締めます。final_close で、その国で最終締めも必要かどうか、および期限を指定できます。または、後続の年度がどのような状態であっても、修正のために年度を再開できます。後続の年度が締め済みの場合は、先に再開します
close_fiscal_year_finally	締め済み年度の最終締めを行います。オペレーターを含め、以後誰も再開できません。ユーザーが明示的に要求した場合のみ実行します
create_company	国別パック、勘定科目表、最初の会計年度を設定して会社を作成します。インスタンスレベルの操作です
update_company_profile	会社の書類に表示する会社情報と、書類番号の形式を変更します
set_number_prefix	仕訳帳の番号で {CODE} の代わりに出力する文字列を設定します
set_preferences	自身の言語、タイムゾーン、形式、デフォルトの会社を設定します
invite_member / revoke_invitation	会社にメールアドレスを招待するか、招待を取り消します。トークンは一度だけ表示されます
remove_member / set_member_role	メンバーを会社から削除します（自身の退出に members.manage は不要です）。または、別の既定ロールに変更して、そのメンバー固有の調整をすべてクリアします。最後のオーナーを削除または降格することはできません
create_api_key / revoke_api_key	1つの会社と操作権限の一覧を対象とした、マシン用キーを作成または取り消します
share_document / list_shares / revoke_share	アカウントなしで顧客が開けるリンクから、転記済み販売書類を公開します。各リンクの閲覧回数を含む一覧を表示するか、リンクを無効化します（docs/sharing.md）
list_accounts が返すのは、勘定科目表全体ではなく、業務で使う勘定科目です。 国別パックには法規制に記載された勘定科目が反映されており、その数は千を超えることもありますが、会社が使うのはそのうち数十科目です。デフォルトでは、仕訳が計上されている勘定科目、会社の設定または有効なモジュールが参照する勘定科目、そして誰かが pin_accounts でピン留めした勘定科目が返されます。include_all を指定すると勘定科目表全体が返されます。また、すべての書き込みツールでは、勘定科目表にある任意の勘定科目を引き続き指定できます。

post_document、cancel_document、reverse_entry、record_payment、update_document_lines、unreconcile、settle_from_statement、lock_period、opening_balance、import_books、close_fiscal_year、reopen_fiscal_year、close_fiscal_year_finally、revoke_invitation、remove_member、set_member_role、revoke_api_key、revoke_share は、プロトコル上で破壊的操作として注釈されています。そのため、クライアントは呼び出し前に確認を求めることができます。

ツールが実行できる操作は、そのツール自体の権限ではなく、ユーザーが持つ権限によって決まります。 サーバーはサインインしたユーザーとして動作するため、post_document は会計担当者には許可されますが、閲覧者にはデータベースによって拒否され、その際はデータベース独自のメッセージが返されます。get_company が your_capabilities を返すのは、まさにこのためです。

モジュール。 このインストール環境の各モジュールには、module.json で宣言されたプレフィックスが付いた専用ツールがあります。起動時にサーバーは public.modules を読み込み、どのモジュールがあるかを確認します。利用できるツールは次のとおりです。fixed_assets_list、fixed_assets_create、fixed_assets_schedule、fixed_assets_run_depreciation、fixed_assets_dispose、budgets_list、budgets_upsert_lines、budgets_variance、einvoicing_validate、einvoicing_issue、einvoicing_status、einvoicing_list、einvoicing_fiscalise、einvoicing_fiscalisation_status、einvoicing_clearance、tax_estimate、tax_parameters、tax_declare_parameter、tax_adjustments、tax_declare_adjustment、tax_losses、tax_record_computation、tax_computations、crm_search、crm_card、crm_segments、crm_board、crm_timeline、crm_upsert_card、crm_log_activity、crm_join_segment、crm_leave_segment、crm_open_deal、crm_move_deal、contracts_list、contracts_card、contracts_upsert、contracts_schedule、contracts_issue_due、contracts_deadlines、contracts_amend、contracts_from_template。モジュールは、同じプレフィックスでプロンプトも提供できます。tax_review_year、crm_morning_review がその例です。インストールされていないモジュールは提供されません。プロジェクトでモジュールのスキーマがまだ公開されていない場合、ツールは変更すべき設定を示します。

電子請求書ツールは、サーバーに渡されたトランスポートを通じて送信します。モデルが選んだトランスポートは使用しません。トランスポートは EKWO_EINVOICE_DIRECTORY のフォルダー、またはホストが buildServer() に einvoiceTransport として渡すものです。ネットワークの認証情報がツールに渡ることはありません。詳細は modules/einvoicing をご覧ください。

会社のパックで制度が宣言されている場合、税務処理ツールは、サーバーに渡された EKWO_FISCAL_SYSTEM の請求システムに基づいて、計上済みの各売上の記録を連鎖させます。モデルが指定した請求システムは使用しません。

リソース。 ekwo://companies/{id}/chart は勘定科目表全体です。ekwo://companies/{id}/taxes は、各税の仕訳が転記される勘定科目と申告書の欄を含む、すべての税を示します。

プロンプト。 close_month は月末チェックリストに沿って、下書き、照合されていない銀行明細行、残高、VAT、未処理の項目を確認します。prepare_vat_return は申告前に各欄の値を取得し、元帳と照合します。

レビューまたは自動実行

コーディングエージェントの権限と同様に、設定でのデフォルトモード、1 セッションだけに適用するフラグ、そしてそのフラグを禁止する設定があります。データベースには、その設定に至るすべての経路が保持されています。

設定：会社の agent_posting（get_company、update_company_profile、ekwo company agent-posting、Ekwo Cloud の Settings ページ）	デフォルトは review です。post_document は、担当者が文書を変更せずに承認した場合にのみ下書きを登録します（ekwo doc approve <document> またはウェブアプリケーション）。それ以外の場合は approval_required で拒否され、下書きが変更された場合も再度承認が必要です。autopilot の場合は、担当者の権限の範囲内で直接登録します。review_only の場合はレビューが必要で、すべてのセッションで自動実行が拒否されます。
セッション：サーバーを起動する担当者が選択	--autopilot（または EKWO_AGENT_POSTING=autopilot）を指定すると、会社で許可されている範囲で承認なしに登録します。これは、Claude Code の1セッションで --dangerously-skip-permissions を指定する場合と同様です。review_only の会社では、autopilot_forbidden と明示して拒否されます。--review を指定すると、会社が自動実行に設定されていても承認が必要です。どちらも指定しない場合は、会社ごとの設定に従います。
マシンキー：発行時に一度だけ選択	create_api_key の posting_mode（ekwo key create --autopilot）です。デフォルトの review は会社の設定に従います。autopilot は承認なしで登録します。このキーは company.write を持つ担当者のみが発行でき、review_only の会社では発行できません。また、そのキーの使用も拒否されます。キーを使ったリクエストでは X-Ekwo-Agent は無視され、発行後にキーのモードを変更することもできません。変更するには別のキーを発行します。list_api_keys にはモードが表示されます。

サーバーは、開いたすべてのトランザクションにエージェントであることを示す情報を付与します。直接接続では ekwo.agent、PostgREST 経由では X-Ekwo-Agent を使ってセッションの選択を伝え、X-Ekwo-Agent-Session でそのセッションを特定します。マシンキーも、発行時に設定されたモードでエージェントとして扱われます。HTTP トランスポートのホストは、担当者の選択を接続の agent として渡します。エージェントによるすべての登録は、モード、設定、セッション、キーとともに、監査記録に document_posted_by_agent として記録されます。エージェントは承認できません。また、設定をより厳しくすることはできますが、より緩くすることはできません。サーバーは起動時に、status と post_document の説明で、そのセッションがどのように登録するかを示します。自動実行は担当者が自分のセッションに対して選ぶものであり、エージェントが選ぶものではありません。詳しくは決定 0089を参照してください。

エージェントが最初に読む内容

ハンドシェイクの手順は、5 段階の初回セッションです。 list_companies を実行し、次に会計年度と締め日を確認するために get_company を実行します。その後、明細に記載されたコードを確認するために list_accounts と税金リソースを使用し、続いて search_contacts と create_document を実行します。ユーザーの同意を得てから post_document を実行します。vat_return の読み方や、転記済みの伝票または仕訳を修正する方法 （cancel_document、reverse_entry）、拒否された場合に次に何をすべきかも記載されています。各ツールの説明には、次に呼び出すツールが記されています。 docs/agents.md には、エージェントを設定する人向けに、コマンドラインも併記した同じセッションが記載されています。

Ekwo に登録されていない環境では、手順にもう 1 行加わります。エージェントは、自然な区切りのタイミングで一度だけ、登録することで得られる内容とコマンドを添えて、登録の案内をユーザーに伝えられます。status ツールでは、registration フィールドとして案内を確認できます。登録は任意で、このサーバーの動作には何も影響しません。サーバーの環境変数に EKWO_NO_REGISTER_INVITE=1 を設定すると案内は表示されず、ホスト型サーバーが案内を追加することもありません。

手順には、無料の Ekwo Cloud アカウントの案内も一度だけ記載されています。エージェントは、初回タスクの完了後にアカウントを持っていないユーザーへこの案内を伝えられます。案内には、同じ帳簿を扱えるウェブアプリケーション、リンクしたすべての会社の夜間バックアップ、そしてファイルにキーとパスワードを保存する代わりに上記の URL で接続するコネクターが含まれます。この案内はどのツールの結果にも含まれず、何かを利用する条件にもなりません。また、サーバーが案内のために Ekwo へ情報を送信することもありません。サーバーの環境変数に EKWO_NO_CLOUD_OFFER=1 を設定すると案内は表示されず、CI が設定されている場合も同様です。ホスト型サーバーが案内を追加することもありません。

規約

• 金額は小数を表す文字列です。 "1210.00" のように指定し、浮動小数点数は使いません。numeric は正確ですが、浮動小数点数は正確ではないため、指定した形式のまま送信され、同じ形式で返されます。
• 日付は ISO 形式です。 2026-06-15 のように指定します。識別子は UUID です。
• 合計はデータベースで計算されます。 create_document は呼び出し元が指定した値ではなく、スキーマが計算した合計を含む下書きを返します。
• 拒否理由は変更されずに返されます。 period_locked:、entry_unbalanced:、document_total_mismatch: などは、データベースが返したメッセージと、それが何を意味するかを説明する 1 文とともに返されます。これらは回避すべき障害ではなく、応答です。
• 商品は明細を補完しますが、明細を制限することはありません。 product_code を指定した明細には、カタログの商品名、説明、単位、価格、勘定科目、税が反映されます。明細に指定された値があれば、そちらが優先されます。すでに転記済みの内容は、カタログが変更されても変更されません。また、明細から参照されている商品は削除せず、active: false にして廃止します。
• 税がない場合、税はありません。 税を指定しない明細は、VAT の区分なしで課税標準額を記帳します。これは税率 0％とは異なります。勘定科目がない場合は異なります。商品明細の勘定科目がないとチェック制約によって拒否されるため、「解決してください」という意味にしかなりません。そのため、明細では account_code を省略できます。その場合、データベースが会社のデフォルト値、次に国別モデルの順で補完します。

手動で試す

自動テストでは、拒否ケースも含め、すべてのツールを WebAssembly にコンパイルされた Postgres の実際のスキーマに対して実行します（tests/mcp/）。PostgREST と Supabase Auth も試すには、使い捨て可能なプロジェクトにインストールし（npx -y ekwo-os@latest init）、上記のブロックを使ってクライアントを接続し、最初のセッションを試してください。

1. 「自分の会社を一覧表示して。」 作成した会社が your_role: owner とともに表示されます。
2. 「顧客を作成して、標準料金でコンサルティング料 1 000 を請求して。」 create_contact の後に create_document を実行します。回答に表示される合計額はデータベースで計算されます。
3. 「それを転記して。」 post_document が売上仕訳帳の次の番号を割り当てます。
4. 「10日に 500 を支払ってもらった。」 record_payment を実行すると、請求書は一部支払済みになります。
5. 「試算表と四半期の VAT を表示して。」 trial_balance と vat_return を実行します。
6. 「6月を締めて。」 lock_period を実行すると、6月の日付が付いた取引はすべて period_locked: で拒否されます。

国別パックからインストールした会社では、銀行仕訳帳と現金仕訳帳がすでにそれぞれの勘定科目に接続されているため、ほかに何も設定しなくても record_payment を使えます。実際の口座を登録するには create_bank_account を使います。

ライセンス

AGPL-3.0-only © Ekwo AI.