mcp-reportia

mcp-reportia

MCP（Model Context Protocol）の独立したサーバーです。Reportia の実際の HTTP APIをラップし、stdio トランスポートを通じて 改行区切りの JSON-RPC として公開します。MCP クライアント（Claude Desktop、Cursor、Hermes Agent など）から、独自のサーバーコードを実行することなく、npx だけで利用できます。

このレイヤーにはビジネスロジックや独自のシークレットは含まれません。MCP プロトコルと Reportia の REST エンドポイントの間のトランスレーターとして機能します。認証情報は環境変数から注入します。

---

目次

• インデックス登録先
• インストールとクイックスタート
• 環境変数
• MCP クライアントでの設定
• リリースの流れ
• 利用可能なツール
• 既知の制限事項
• セキュリティ
• 対象および対象外のルート
• ローカル開発
• テスト
• MCP Inspector での検査
• 内部アーキテクチャ
• ライセンス

---

インデックス登録先

この MCP サーバーは、以下で公開され、検索可能です。

プラットフォーム	URL	形式
公式 MCP Registry（modelcontextprotocol.io）	io.github.javalenciacai/mcp-reportia	server.json
npm レジストリ	@james.valencia/mcp-reportia	npm パッケージ
skills.sh（Agent Skills Directory）	javalenciacai/mcp-reportia	skills/reportia-mcp-usage/SKILL.md

skills.sh 経由でインストール：

npx skills add javalenciacai/mcp-reportia --skill reportia-mcp-usage

---

リリースの流れ

このリポジトリは、main に v* タグをプッシュすると、npm と公式 MCP Registryに自動で公開されます。skills.sh へのインデックス登録は自動です（GitHub のスクレイピングによるものです）。

初期設定（初回のみ）

選択した方法：npm Trusted Publishing（OIDC）

設定はパッケージのページにあります（/settings/james.valencia/security ではありません。この URL は従来のトークン用です）。

1. https://www.npmjs.com/package/@james.valencia/mcp-reportia/settings を開きます（ブラウザーで james.valencia としてログインします）。

2. 「Trusted Publisher」 セクションで、**「Add a trusted publisher」**をクリックします（npmjs.com のバージョンによっては「GitHub Actions」と表示されます）。

3. 公式ドキュメントに記載されているとおり、以下の値を正確に入力します。

   フィールド	値
   Provider	GitHub Actions
   Organization or user	javalenciacai
   Repository	mcp-reportia
   Workflow filename	publish.yml（ファイル名のみ。パス .github/workflows/ は含めません）
   Environment name	（空欄） — このワークフローは GitHub Environments を使用しません
   Allowed actions	npm publish（少なくとも 1 つ）

4. **「Add」または「Save」**をクリックします。npm は保存時に設定を検証しませんが、値が完全に一致しない場合、ワークフローは実行時に失敗します。

Trusted Publishing に必要な、ワークフローの Node 24 への更新

Trusted Publishing には npm >= 11.5.1 が必要で、これは Node.js 24 に同梱されています。現在のワークフローは Node 22（npm 10.9）を使用しているため、publisher が正しく設定されていても ENEEDAUTH で失敗します。

ステップ 1 を確認してもらった後、こちらで行うこと：ワークフローを Node 24 に更新し、コミットして、タグ v0.1.2 を新しいコミットを指すように再作成し、publish を再実行します。

正しく設定されているか簡単に確認する方法

ワークフローを手動で再実行し、publish-npm ジョブのログを確認してください：

gh workflow run Publish --ref v0.1.2
gh run watch --exit-status

最後のステップに OK: @james.valencia/[email protected] publicado と表示されていれば、正常に動作しています。再び失敗した場合は、「Publish」ステップの出力を送ってください（トークンは含めないでください）。

現在の要件の状況

プラットフォーム	要件	状態
npm Trusted Publishing	/package/@james.valencia/mcp-reportia/settings で、javalenciacai/mcp-reportia + publish.yml を使って publisher を設定する	あなたの作業
Workflow Node 24	Node 24 に更新する（確認後、こちらで対応します）	保留中
MCP Registry	なし — ワークフローを自動で署名する github-oidc を使用します	完了
skills.sh	なし — 自動スクレイピング	完了
GitHub Release	ワークフローで contents: write 権限を設定済み	完了

ステップ 1 が完了した後の計画

以下の順番で実行します（あなたからの入力は不要です）。

1. publish ワークフローの両方のジョブで node-version: '22' → '24' に変更する
2. ローカルで npm test && npm run build を実行して確認する
3. コミットして push する
4. タグ v0.1.2 を新しいコミットを指すように再作成する
5. publish-npm が成功するまで Publish ワークフローを確認する
6. 最終結果を報告する（npm のバージョンと、作成された GitHub Release）

リリースする

# 1. Bump de version (esto actualiza package.json y server.json automaticamente)
cd /c/james/mcp-reportia
npm version patch    # 0.1.1 -> 0.1.2 (o minor/major)

# 2. Push del commit + tag a GitHub
git push origin main --follow-tags
# (npm version ya crea el tag v0.1.2 y lo pushea junto con el commit)

GitHub Actions が自動的に実行されます。

1. Job validate — typecheck + test + build + smoke。package.json.version と server.json.version がタグと一致していることを確認します。
2. Job publish-npm — OIDC 経由で npm に公開します（長期間有効なトークンは不要です）。
3. Job publish-mcp-registry — server.json を公式 MCP Registry に公開します。
4. Job release — 自動生成されたリリースノートを使って GitHub Release を作成します。

手動で公開する（タグなし）

通常のフロー以外でリリースする必要がある場合は、GitHub → Actions → "Publish" → "Run workflow" に移動し、必要に応じて version override を指定します。

ロールバック

npm に公開したバージョンを取り消す必要がある場合（72 時間以内）：

npm unpublish @james.valencia/[email protected]

72 時間を過ぎると取り消しはできません。patch を公開する必要があります。MCP Registry はロールバックに対応していないため、修正を含む上位バージョンを公開する必要があります。

---

インストールとクイックスタート

公開後は、通常 npx 経由で使用します。

# 1) Construir dist/ localmente (la primera vez, o al actualizar):
npm run build

# 2) Ejecutar el binario MCP directamente:
npx mcp-reportia

MCP クライアント（Claude Desktop、Cursor、Hermes など）がサブプロセスとして呼び出すため、手動で実行する必要はありません（デバッグ時を除く）。

---

環境変数

変数	必須	説明
REPORTIA_BASE_URL	はい	Reportia API のルート URL。末尾にスラッシュを付けないでください（例：https://reportia.example.com）。
REPORTIA_TOKEN	条件付き*	Bearer トークン。セッションログインの代替です。
REPORTIA_COOKIE	条件付き*	事前発行された Reportia セッション Cookie（例：connect.sid=s%3A...）。ユーザーのセッションがすでに確立されており、再ログインせずに子プロセスをそのユーザーとして認証したい呼び出し元向けです。
REPORTIA_EMAIL	条件付き*	セッション（Cookie）ログイン用のメールアドレス。
REPORTIA_PASSWORD	条件付き*	セッション（Cookie）ログイン用のパスワード。
REPORTIA_COMPANY_ID	いいえ	ツールが対応している場合に使用されるデフォルトの companyId。正の整数を指定できます。
REPORTIA_TIMEOUT_MS	いいえ（デフォルト：30000）	HTTP リクエストごとのタイムアウト（ミリ秒）。
REPORTIA_DOWNLOAD_DIR	いいえ（デフォルト：./downloads）	ダウンロードしたバイナリ（エクスポートされた Excel／PDF）の保存先フォルダー。
REPORTIA_USER_AGENT	いいえ（デフォルト：mcp-reportia/0.1.0）	各リクエストの User-Agent ヘッダー。

* 認証方法は次の3つの選択肢のうち、いずれか1つだけを設定してください。

• Bearer 認証の場合は REPORTIA_TOKEN、または
• REPORTIA_EMAIL + REPORTIA_PASSWORD による Cookie セッション（package が POST /api/auth/login を実行して Cookie を取得します）、または
• 事前発行された Cookie セッションの場合は REPORTIA_COOKIE（package は再ログインせず、これを直接使用します）。

REPORTIA_TOKEN と REPORTIA_COOKIE を同時に指定すると、loadConfig は REPORTIA_TOKEN y REPORTIA_COOKIE son mutuamente excluyentes — usa solo uno. というメッセージで ConfigError をスローします。誤ってトークンがユーザーごとのセッションを上書きするのを防ぐためです。

1つだけ設定されている場合の優先順位は、cookie > bearer > session です。cookie は上流で確立された ID と一致するため優先されます。Bearer はサービスアカウント、session はメールアドレスとパスワードによるログイン（子プロセス自身がログイン）です。

どれも設定されていない場合、サーバーの起動時に loadConfig が ConfigError をスローします。

⚠️ C:\james\Reportia\.env の認証情報をこのリポジトリにコピーしないでください。このプロジェクトにシークレットを含めてはいけません。呼び出し元となる MCP クライアントの環境に設定してください。

すべての変数については .env.example を確認してください。

---

MCP クライアントでの設定

Claude Desktop（%APPDATA%\Claude\claude_desktop_config.json）

mcpServers 内にエントリーを追加します。

{
  "mcpServers": {
    "reportia": {
      "command": "npx",
      "args": ["-y", "mcp-reportia"],
      "env": {
        "REPORTIA_BASE_URL": "https://reportia.example.com",
        "REPORTIA_TOKEN": "<tu-token>",
        "REPORTIA_COMPANY_ID": "123"
      }
    }
  }
}

開発中は mcp-reportia をローカルのパス C:\\james\\mcp-reportia に置き換え、args: ["-y", "--prefix", "C:\\james\\mcp-reportia", "mcp-reportia"] を指定するか、npm run start を直接コマンドとして実行してください。

Cursor（%USERPROFILE%\.cursor\mcp.json）

{
  "mcpServers": {
    "reportia": {
      "command": "npx",
      "args": ["-y", "mcp-reportia"],
      "env": {
        "REPORTIA_BASE_URL": "https://reportia.example.com",
        "REPORTIA_TOKEN": "<tu-token>"
      }
    }
  }
}

Hermes Agent（~/.hermes/config.toml または UI 経由の MCP プラグイン）

reportia という名前の stdio MCP サーバーを追加し、npx mcp-reportia を指定して、環境変数を env でエクスポートします。

一般的な形式：

[[mcp_servers]]
name = "reportia"
command = "npx"
args = ["-y", "mcp-reportia"]
[mcp_servers.env]
REPORTIA_BASE_URL = "https://reportia.example.com"
REPORTIA_TOKEN    = "<tu-token>"
REPORTIA_COMPANY_ID = "123"

フィールド名は Hermes のバージョンによって異なります。hermes mcp --help を参照してください。

ユーザーのセッションをすでに持つ呼び出し元（ユーザーごと、AI サーバーに推奨）

呼び出し元（たとえば、マルチテナントの AI サーバー）がアクティブユーザーの Reportia セッションをすでに解決しており、再ログインやサービスアカウントを使わずに、子プロセスを同じユーザーとして認証したい場合は、事前に発行された Cookie を渡します。

{
  "mcpServers": {
    "reportia": {
      "command": "npx",
      "args": ["-y", "mcp-reportia"],
      "env": {
        "REPORTIA_BASE_URL": "https://reportia.example.com",
        "REPORTIA_COOKIE": "connect.sid=s%3A<session-id-from-resolved-user>",
        "REPORTIA_COMPANY_ID": "123"
      }
    }
  }
}

子プロセスは /api/auth/login を呼び出しません（その手順をスキップします）。終了時に /api/auth/logout も呼び出しません（セッションは子プロセスではなく呼び出し元のものです）。また、Reportia へのすべてのリクエストを、解決済みユーザーの ID で実行します。呼び出し元が、実行時にユーザーの Cookie を取得するリレー（たとえば、Cowork サーバーのセッション由来パス）の背後で動作している場合、この認証モードがそのフローに適しています。

---

利用可能なツール

サーバーは reportia_ プレフィックスの66 個のツールを公開します。すべて JSON（JSON.stringify で整形した文字列）を返し、Zod で入力を検証します。機能別に次のように分類されています。

ドメイン	モジュール	数
ヘルスと認証	src/tools/auth-health.ts	3
企業	src/tools/companies.ts	5
会計上の移動	src/tools/accounting-movements.ts	4
勘定科目のマッピング	src/tools/account-mappings.ts	5
コミッションレポート	src/tools/commission-reports.ts	2
第三者	src/tools/third-parties.ts	4
営業担当者 × 請求書	src/tools/salesperson-invoice.ts	11
明細行 × コストセンター	src/tools/line-cost-center.ts	22
オペレーション（アップロード、キュー、SIIGO）	src/tools/operations.ts	10
合計		66

ヘルスと認証（src/tools/auth-health.ts）

ツール	説明
reportia_health	MCP クライアントの診断と GET /api/health への ping。
reportia_whoami	認証済みユーザーのプロフィール（GET /api/auth/me）。
reportia_logout	Reportia のセッションを終了します（POST /api/auth/logout）。

企業（src/tools/companies.ts）

ツール	種類	説明
reportia_companies_list	一覧	アクセス可能な企業の一覧を取得します（GET /api/companies）。
reportia_company_get	詳細	企業の詳細を取得します（GET /api/companies/:id）。
reportia_company_settings_get	設定	企業の設定を取得します（GET /api/companies/:id/settings）。
reportia_company_settings_update	変更	設定をパッチします（PATCH /api/companies/:id/settings）。
reportia_company_activate ⚠️	破壊的	企業を有効化します（POST /api/companies/:id/activate）。confirm:true が必要です。

仕訳（src/tools/accounting-movements.ts）

ツール	種類	説明
reportia_movements_list	一覧	フィルターとページネーションを使用して仕訳を一覧表示します。
reportia_movements_export_excel	バイナリダウンロード	仕訳を Excel にエクスポートし、ローカルパスを返します。
reportia_movements_export_pdf	バイナリダウンロード	仕訳を PDF にエクスポートし、ローカルパスを返します。
reportia_movements_delete_all ⚠️	破壊的	会社のすべての仕訳を削除します。confirm:true が必要です。

勘定科目マッピング（src/tools/account-mappings.ts）

ツール	種類	説明
reportia_account_mappings_list	一覧	勘定科目マッピングを一覧表示します（GET /api/companies/:companyId/account-mappings）。
reportia_account_mapping_create	ミューテーション	マッピングを作成します（POST /api/account-mappings）。
reportia_account_mapping_update	ミューテーション	マッピングを更新します（PATCH /api/account-mappings/:mappingId）。
reportia_account_mapping_delete ⚠️	破壊的	マッピングを削除します（DELETE /api/account-mappings/:mappingId）。confirm:true が必要です。
reportia_account_codes_search	検索	オートコンプリート用の勘定科目コードを検索します（GET /api/companies/:companyId/account-codes/search）。

コミッションレポート（src/tools/commission-reports.ts）

ツール	種類	説明
reportia_commission_list	一覧	コミッション計算を一覧表示します（GET /api/commission-reports）。
reportia_commission_export_excel	バイナリダウンロード	コミッションレポートを Excel にエクスポートします。

取引先（src/tools/third-parties.ts）

ツール	種類	説明
reportia_third_parties_list	一覧	取引先（顧客／仕入先）を一覧表示します。
reportia_third_parties_search	検索	取引先を高度な条件で検索します。
reportia_third_parties_get_by_nit	詳細	NIT で取引先を取得します。
reportia_third_parties_portfolio_balance	概要	取引先ごとの売掛金残高を表示します。

販売担当者 × 請求書（src/tools/salesperson-invoice.ts）

販売担当者 → 請求書のマッピング、販売担当者のオプション、請求書一覧、請求書設定、請求書の送信（個別および一括メール）。

ツール	種類	説明
reportia_salesperson_mappings_list	一覧	企業の販売担当者 × 請求書のマッピング一覧を表示します。
reportia_salesperson_mapping_create	変更	販売担当者 × 請求書のマッピングを作成します。
reportia_salesperson_mapping_update	変更	販売担当者 × 請求書のマッピングを更新します。
reportia_salesperson_mapping_delete ⚠️	破壊的操作	販売担当者 × 請求書のマッピングを削除します。confirm:true が必要です。
reportia_salesperson_options_list	一覧	選択／オートコンプリート用の販売担当者オプション一覧を表示します。
reportia_invoices_list	一覧	フィルター条件を指定して請求書一覧を表示します。
reportia_invoice_settings_get	設定	企業の請求書設定を読み取ります。
reportia_invoice_settings_create	変更	請求書設定を作成します。
reportia_invoice_settings_update	変更	請求書設定を更新します。
reportia_invoice_email_send	通知	請求書をメールで送信します（Reportia サーバーが送信を実行します）。
reportia_invoices_send_multiple	通知	1 回の呼び出しで複数の請求書をメールで送信します。

明細 × コストセンター（src/tools/line-cost-center.ts）

最も広範なドメインです。明細グループのマッピング、コストセンターのマッピング、利用可能なコストセンター、およびコストセンターレポートのライフサイクル全体（CRUD ＋ 実行 ＋ 複製 ＋ エクスポート）を管理します。

ツール	種類	説明
reportia_line_group_mappings_list	一覧	明細グループのマッピングを一覧表示します。
reportia_line_group_mapping_create	変更	明細グループのマッピングを作成します。
reportia_line_group_mapping_update	変更	明細グループのマッピングを更新します。
reportia_line_group_mapping_delete ⚠️	破壊的操作	明細グループのマッピングを削除します。confirm:true が必要です。
reportia_line_group_suggestions_lines_groups	候補	オートコンプリート用の明細グループ候補を提示します。
reportia_line_group_suggestions_by_type	候補	種類でフィルタリングした明細グループ候補を提示します。
reportia_line_group_description	詳細	明細グループのマッピングをわかりやすく説明します。
reportia_cost_center_mappings_list	一覧	コストセンターのマッピングを一覧表示します。
reportia_cost_center_mapping_create	変更	コストセンターのマッピングを作成します。
reportia_cost_center_mapping_update	変更	コストセンターのマッピングを更新します。
reportia_cost_center_mapping_delete ⚠️	破壊的操作	コストセンターのマッピングを削除します。confirm:true が必要です。
reportia_cost_center_mappings_suggestions	候補	コストセンターのマッピング候補を提示します。
reportia_cost_centers_available	一覧	企業で利用可能なコストセンターを一覧表示します。
reportia_cost_center_reports_list	一覧	コストセンターレポートを一覧表示します。
reportia_cost_center_report_get	詳細	コストセンターレポートの詳細を取得します。
reportia_cost_center_report_create	変更	コストセンターレポートを作成します。
reportia_cost_center_report_update	変更	コストセンターレポートを更新します。
reportia_cost_center_report_delete ⚠️	破壊的操作	コストセンターレポートを削除します。confirm:true が必要です。
reportia_cost_center_report_execute	実行	コストセンターレポートを実行します。
reportia_cost_center_report_duplicate	変更	コストセンターレポートを複製します（別名：コピー）。
reportia_cost_center_report_export_excel	バイナリダウンロード	レポートの結果を Excel にエクスポートします。
reportia_cost_center_report_export_pdf	バイナリダウンロード	レポートの結果を PDF にエクスポートします。

操作（src/tools/operations.ts）— アップロード、キュー、SIIGO

このモジュールのすべてのツールは読み取り専用です。アップロードの履歴とステータス、キューシステムとワーカーの健全性、および SIIGO に関する照会ツール（設定、クライアント、実行、トレース、スケジュール、履歴）が含まれます。このバージョンには、変更ツール、multipart/form-data によるアップロードツール、キューを制御するツールはありません。

ツール	種類	説明
reportia_uploads_history_list	一覧	会社のアップロード履歴（GET /api/companies/:companyId/upload-history）。
reportia_upload_status_get	詳細	特定のアップロードのステータス（GET /api/upload/:uploadId/status）。
reportia_health_queue_system	診断	キューシステムの健全性（GET /api/health/queue-system）。
reportia_health_workers	診断	ワーカーの健全性とキューのラグ（GET /api/queue/workers/health）。
reportia_siigo_settings_get	設定	会社の SIIGO Pyme 設定（GET /api/companies/:companyId/siigo-settings）。
reportia_siigo_clients_list	一覧	会社で利用可能な SIIGO リモートクライアント（GET /api/companies/:companyId/siigo/clients）。
reportia_siigo_sync_runs_list	一覧	SIIGO 同期の実行履歴（GET /api/companies/:companyId/siigo/sync/runs）。
reportia_siigo_run_trace_get	詳細	SIIGO の実行トレース（GET /api/companies/:companyId/siigo/sync/runs/:runId/trace）。
reportia_siigo_schedules_list	一覧	SIIGO 同期スケジュール（GET /api/companies/:companyId/siigo/schedules）。
reportia_siigo_history_get	履歴	SIIGO コマンドの履歴（GET /api/companies/:companyId/siigo/history）。

⚠️ 破壊的とマークされたツールには、入力に { "confirm": true } パラメーターが必要です。指定されていない場合、ハンドラーは assertConfirmed(input, '<tool-name>')（src/tool-base.ts で定義）による検証を行い、HTTP 呼び出しを行う前に code: "GUARD_REJECTED" のエラーを返します。LLM は、これらのツールを呼び出す前にユーザーへ明示的な確認を求める必要があります。

REPORTIA_COMPANY_ID を設定している場合、companyId は省略できます。それ以外の場合、会社のデータを扱うすべてのツールで必須です。

---

既知の制限事項

• HTTP ストリーミング／SSE には対応していません： このサーバーは stdio のみを使用します。HTTP のみをサポートするクライアントからは直接利用できません。
• 1 プロセスにつき ReportiaClient は 1 つのみです： ログインは遅延実行され、グローバルに管理されます。同時に複数のアカウントを使用することはできません。
• ファイルのアップロード（multipart/form-data）： HTTP クライアントは undici の FormData を使用できるよう準備されていますが、現在のツールではアップロードエンドポイントを公開していません（multipart/form-data を使う POST／PUT はありません）。既存のアップロード履歴と状態については、読み取り専用のツールを 2 つ公開しています。reportia_uploads_history_list（GET /api/companies/:companyId/upload-history）と reportia_upload_status_get（GET /api/upload/:uploadId/status）です。Reportia が今後アップロードエンドポイントを追加した場合は、ctx.client.call(..., { formData }) を使う ToolDefinition を追加するだけで対応できます。
• 永続キャッシュはありません： 呼び出しのたびに API にリクエストします。LLM は必要に応じて自由に tools/list を実行できます。
• HTTP エラー： 構造化された型（AUTH_ERROR、NOT_FOUND、VALIDATION_ERROR、ROW_LIMIT_EXCEEDED、NETWORK_ERROR、TIMEOUT）に変換されます。クライアントがエラーメッセージで秘密情報を公開することはありません。
• オフラインのスモークテスト： npm run test:smoke は REPORTIA_BASE_URL=http://127.0.0.1:9（閉じたポート）でサーバーを起動します。実際の呼び出しは行わず、MCP のハンドシェイクのみを検証します。実際の統合テストを行うには、アクセス可能な Reportia サーバーを指定して npm run test:integration を実行してください。
• 自動再試行はありません： 5xx エラーが発生すると、サーバーはエラーを報告します。LLM は手動で再試行できます。

セキュリティ

このサーバーは、LLM から呼び出された際の攻撃対象領域を最小限に抑えるよう設計されています。

• 汎用 HTTP ツールはありません： ツールはドメインごとに厳選されています（特定の 66 個のエンドポイント）。LLM がクライアントの接続先として任意の URL や内部 IP アドレスを指定することはできません。
• すべての入力を Zod で検証： 無効な型、範囲、形式を拒否するスキーマを通過しない限り、ハンドラーがネットワークにアクセスすることはありません。
• 破壊的なツールには confirm: true の指定が必須です： destructive: true として宣言され、HTTP 呼び出しの前に assertConfirmed(...) で検証されます。confirm が指定されていない場合は、API にアクセスせず GUARD_REJECTED を返します。LLM は呼び出す前に、ユーザーに明示的な確認を求める必要があります。
• URL への安全な値の埋め込み： 数値 ID（companyId、mappingId、reportId、runId、uploadId）は、URL に埋め込む前に z.number().int().positive() で検証されます。パス内の文字列（NIT、invoiceId、行／センターの mappingId）には encodeURIComponent が使用され、かつ／または安全な文字セット（NIT には [A-Za-z0-9-]+）に制限されます。
• HTTP ヘッダーをサニタイズ： REPORTIA_USER_AGENT で設定できる User-Agent は、src/client.ts:sanitizeUserAgent で CRLF（ヘッダーインジェクション）を除去します。
• ログに秘密情報を記録しません： エラーメッセージにはエンドポイントと HTTP コードが含まれますが、トークン、Cookie、パスワード、本文全体が含まれることはありません。connect.sid Cookie はクライアントのメモリ内に保持され、JSON レスポンスに表示されることはありません。
• Cookie を使ったログイン状態の永続化： セッションモードでは /api/auth/login から受け取った connect.sid Cookie を再利用し、Reportia が更新した場合にのみローテーションします。ディスクに書き込まれることはありません。
• セキュリティ回帰テスト（tests/security.test.ts）：破壊的なツールで confirm が省略されないこと、危険な入力を受け付けるスキーマがないこと、ガードの実行順序（resolveCompanyId → assertConfirmed）により、設定に問題がある場合に GUARD_REJECTED よりも具体的なエラーが優先されることを検証する 16 件のテストです。

---

対応しているルートと省略しているルート

網羅する項目（tools/）

エンドポイント	ツール
GET /api/health	reportia_health
GET /api/auth/me	reportia_whoami
POST /api/auth/logout	reportia_logout
GET /api/companies	reportia_companies_list
GET /api/companies/:id	reportia_company_get
GET /api/companies/:id/settings	reportia_company_settings_get
PATCH /api/companies/:id/settings	reportia_company_settings_update
POST /api/companies/:id/activate	reportia_company_activate
GET /api/accounting-movements (フィルター付き)	reportia_movements_list
GET /api/accounting-movements/export/excel	reportia_movements_export_excel
GET /api/accounting-movements/export/pdf	reportia_movements_export_pdf
DELETE /api/accounting-movements	reportia_movements_delete_all
GET/POST/PATCH/DELETE /api/account-mappings/...	reportia_account_mapping_*
GET /api/account-codes/search	reportia_account_codes_search
GET /api/commission-reports	reportia_commission_list
GET /api/commission-reports/export/excel	reportia_commission_export_excel
GET /api/third-parties	reportia_third_parties_list
GET /api/third-parties/search	reportia_third_parties_search
GET /api/third-parties/by-nit/:nit	reportia_third_parties_get_by_nit
GET /api/third-parties/portfolio-balance	reportia_third_parties_portfolio_balance

対象外（このバージョンの範囲外）

• ツールからのセッションログイン（不要です。ReportiaClient からすでに遅延実行されています）。
• アップロードエンドポイント（multipart/form-data）全般 — 対象は GET /api/companies/:companyId/upload-history と GET /api/upload/:uploadId/status のみです（読み取り専用）。
• 公開されていないスコープが必要な内部管理用エンドポイント。
• 古いバージョン（/api/v0/*）。

⚠️ この表は、src/tools/*.ts の現在の対象範囲を示しています。新しいルートを追加する前に、src/tools/<modulo>.ts を編集し、src/tools/index.ts で再エクスポートして、npm run typecheck && npm test を実行してください。

---

ローカル開発

必要条件：

• Node.js ≥ 20
• npm ≥ 9

# 1) Instalar dependencias
npm install

# 2) Compilar TypeScript a dist/
npm run build

# 3) Verificar tipos sin emitir
npm run typecheck

# 4) Ejecutar el servidor (lee dist/server.js, stdio)
npm run start

テストの実行に Reportia の起動や認証情報は不要です。合成環境を使用します。

---

テスト

# Suite unitaria (Vitest) — sin red, sin credenciales
npm test

# Smoke de protocolo MCP sobre stdio (sin credenciales reales)
npm run test:smoke

# Smoke de integracion contra un servidor Reportia REAL
# (configura REPORTIA_BASE_URL y REPORTIA_TOKEN en tu entorno antes).
npm run build
REPORTIA_BASE_URL=https://reportia.example.com \
REPORTIA_TOKEN=<tu-token> \
  npm run test:integration

スモークテスト（scripts/jsonrpc-smoke.mjs）は、dist/server.js をサブプロセスとして起動し、JSON-RPC の改行区切り形式で initialize と tools/list を送信して、レスポンスに少なくとも 1 つのツールが含まれていることを確認します。Reportia への HTTP 呼び出しは行いません（127.0.0.1:9 を参照します）。

統合テスト（scripts/integration-smoke.mjs）は、実際の Reportia サーバーと通信します。initialize、tools/list を実行し、reportia_health（/api/health に ping を送信）と reportia_whoami（エラー処理を検証するため、無効なトークンでは AUTH_ERROR を返す必要があります）を呼び出します。デプロイ済みバージョンが実際のバックエンドとの互換性を維持していることの確認に役立ちます。

ビルドが壊れていないことだけを確認する場合：

npm test -- --passWithNoTests

---

MCP Inspector での検査

npm run inspect

これを実行すると npx @modelcontextprotocol/inspector node dist/server.js が起動し、プロトコルのメソッド（initialize、tools/list、tools/call など）を手動で送信できる Web UI が開きます。

---

内部アーキテクチャ

src/
├── server.ts               # Arranca McpServer + StdioServerTransport y registra tools.
├── config.ts               # Carga y valida env vars (Zod). Tres auth modes: bearer / session / cookie.
├── client.ts               # Cliente HTTP sobre undici. Bearer, sesión cookie propia, o cookie pre-emitida.
├── errors.ts               # Jerarquía ReportiaError.
├── tool-base.ts            # Helpers: ToolDefinition, ok/fail, resolveCompanyId, assertConfirmed.
└── tools/
    ├── index.ts            # allTools = union de los modulos.
    ├── auth-health.ts      # reportia_health / whoami / logout.
    ├── companies.ts        # reportia_companies_*.
    ├── accounting-movements.ts  # reportia_movements_*.
    ├── account-mappings.ts # reportia_account_mapping_* y account_codes_search.
    ├── commission-reports.ts # reportia_commission_*.
    └── third-parties.ts    # reportia_third_parties_*.

scripts/
└── jsonrpc-smoke.mjs       # Smoke de protocolo (sin red contra Reportia).

tests/
├── config.test.ts          # loadConfig.
├── resolve-company-id.test.ts # helpers de tool-base.
└── schema-validation.test.ts  # invariantes de allTools y Zod.

規約：

• 各ツールは、入力の検証に Zod スキーマ（z.object({...})）を必ず使用してください。
• ハンドラーは、ctx.client.call(...) を try/catch で囲み、tool-base.ts の ok(...)／fail(...) を使用してください。
• 破壊的な変更を行うツールは、destructive: true を宣言し、ハンドラー内で assertConfirmed(...) または同等の方法を使って confirm: true を確認してください。

---

ライセンス

MIT