hilan-mcp

Hilanには公式APIがありません。hilan-mcpはPlaywrightを介して実際の（ヘッドレス）Chromiumブラウザーを操作してログインし、同じ認証済みセッションを再利用してHilanの内部エンドポイントを呼び出し、PDFをダウンロードします。不安定な手作りのCookie再送信は不要で、プレーンテキストの秘密情報がどこにも保存されることもありません。

目次

• 機能
• 仕組み
• セットアップ
  • 0. npm 12以降をお使いの場合
  • 1. テナントを登録して認証情報を入力する
  • 2. MCPクライアントの設定にサーバーを追加する
  • 3. 使用する
• ユーザーに代わってセットアップするAI エージェント向け
• MCPツール
• 対象範囲
• 信頼性に関する注意事項
• セキュリティモデル
• 開発
• ライセンス

機能

• 📄 給与明細 — テナントの履歴にある任意の月について、Bruto／Neto／給与項目の構造化データとPDFを取得できます。
• 🧾 Form 106 — 年ごとの税務サマリーPDFを取得できます。
• 🔐 暗号化されたローカルストレージ — SQLCipherで暗号化されたSQLiteを使用します。鍵がプレーンテキストでディスクに書き込まれることはありません。OS標準の認証情報ストア（Keychain／DPAPI／Secret Service）にも対応しています。
• 🏢 あらゆるHilanテナントに対応 — ログインフォームのフィールドは特定の雇用主にハードコードせず、テナントごとに検出します。
• 💬 生のJSONではなく回答を返します — queryなどのツールは、ネットワークへの再アクセスなしでローカルデータから「6月の収入はいくらでしたか？」に直接回答します。
• 🔄 自動更新の確認機能 — サーバーが新しいバージョンを確認し、専用のUIなしでAI エージェントが更新を提案できるようにします。

仕組み

このサーバーはPlaywrightを介して実際の（ヘッドレス）Chromiumブラウザーを操作してログインし、認証済みブラウザーコンテキストのHTTPクライアント（context.request）を再利用してHilanの内部.asmx JSONエンドポイントを呼び出し、PDFをダウンロードします。これにより、不安定な手作りのCookie再送信ではなく、通常のページ読み込みで設定されるCookieやヘッダーが自動的に引き継がれます。

Hilanのテナントによってログインフォームのフィールドは異なり（2つのテナントもあれば3つのテナントもあります）、1つの会社にハードコードするのではなく、認証情報を初めて登録する際に、各テナントのログインフォームをあらためて調査します。

セットアップ

0. npm 12以降をお使いの場合

npm 12では、許可しない限り依存関係のインストールスクリプトがブロックされます。このパッケージの依存関係の1つ（暗号化SQLiteエンジンのbetter-sqlite3-multiple-ciphers）は、ネイティブバインディングのコンパイルにインストールスクリプトが必要です。これを許可しないと、セットアップは成功したように見えても、データベースにアクセスするすべてのツールが失敗します。今後のすべてのnpxおよびグローバルインストールで有効にするには、一度だけ許可してください。

npm config set allow-scripts=better-sqlite3-multiple-ciphers --location=user

グローバルには設定したくない場合は、インストールごとに許可することもできます。

npm install -g --allow-scripts=better-sqlite3-multiple-ciphers hilan-mcp

npm 11以前では不要です。インストールスクリプトは引き続きデフォルトで実行されます。npm --versionで確認してください。

1. テナントを登録して認証情報を入力する

これをご自身で、ご自身のターミナルから直接実行してください。実際の認証情報を AI チャットに貼り付けてはいけません。Chromium ブラウザーをインストールし（初回のみ）、ヘッドレスブラウザーを起動して、テナントの実際のログインフィールドを検出し、それぞれの入力を求めます（パスワードはマスクされます）。ローカルへのクローンも npm install も不要です。npx がその場でパッケージを取得します。

npx hilan-mcp setup --tenant amdocs        # tenant subdomain
# or
npx hilan-mcp setup --tenant 5227          # numeric org code, resolved automatically

すでに別の方法でパッケージをインストールしている場合、同等の低レベルコマンドは npx hilan-mcp ingest-creds --tenant <...> です。setup は、初回の Chromium インストールも先に処理します。

初回の実行時に、ローカルデータベース用の暗号化キー（6 文字以上）の設定を求められます。このキーが平文でディスクに書き込まれることはありません。

MCP サーバーが人間による都度のプロンプトへの応答なしに、単独でデータベースを開けるよう、次の順にキーを探します。

1. OS の認証情報ストア（推奨） — ご自身のターミナルから npx hilan-mcp setup-key を一度実行してください。キーを入力するか、Enter キーを押して強力なランダムキーを生成すると、OS のネイティブなセキュアストレージに保存されます。macOS Keychain（検証済み — Wi-Fi／ブラウザーのパスワードを保存するものと同じファイルに保存され、通知やダイアログは表示されません）、Windows（DPAPI。Windows ユーザーアカウントに紐付けられます）、または Linux（Secret Service／secret-tool。GNOME Keyring や KWallet などのキーリングデーモンが必要です）。設定ファイルには一切保存されません。
2. HILAN_DB_KEY 環境変数 — サーバーの env ブロックで設定してください（手順 2 を参照）。mcp.json 内で MCP サーバー用に設定する他の API キー／シークレットと同じ信頼モデルです（ローカルファイルで、git にコミットされません）。
3. デスクトップ通知（最後の手段） — サーバーはシステム通知での確認に切り替えます（さらにその代替手段として、通常のターミナルプロンプトも使用します）。ただし、データベースを必要とするツール呼び出しのたびに、約 30 秒以内に人間が応答する必要があるため、通常の使用には推奨されません。

2. MCP クライアントの設定にサーバーを追加する

引数なしでパッケージを実行すると、MCP サーバー自体が起動します（stdio トランスポート）。実際に MCP クライアントの設定から呼び出すのはこちらです。

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

{
  "mcpServers": {
    "hilan": {
      "command": "npx",
      "args": ["-y", "hilan-mcp"],
      "env": {
        "COMPANY_TENANT": "amdocs",
        "HILAN_DB_KEY": "the-encryption-key-you-set-during-ingest-creds",
        "NODE_EXTRA_CA_CERTS": "/path/to/your-corporate-ca-bundle.pem"
      }
    }
  }
}

「Hilanから直近3か月分の給与明細を同期して」「2025年のForm 106をダウンロードして」「2026年6月の手取り／総支給額はいくら？」などとアシスタントに尋ねてください（その月を少なくとも一度同期していれば、ローカルデータベースからqueryツールを使ってネットワーク往復なしですぐに回答できます）。以下のツール一覧をご覧ください。

ユーザーに代わってセットアップするAIエージェント（例：Claude）向け

ユーザーからhilan-mcpのセットアップを頼まれた場合：

1. 自分でシェルツールを使ってingest-creds／setup／setup-keyを実行してはいけません。これらのコマンドはパスワードや暗号化キーを対話形式で求めるため、シェルツールの実行記録にユーザーの入力内容が残る可能性があります。ユーザー自身のターミナルを開き、npx hilan-mcp setup --tenant <their-org-code-or-subdomain>を実行するよう伝えてください。その後、npx hilan-mcp setup-keyも実行することをおすすめします。まずnpm --versionを確認してください。npm 12以降の場合は、手順0も必要です。実行しないと、インストールとは関係なさそうな形で、後からデータベースを開けなくなります。
2. それが済んだら、クライアントの設定ファイルにMCP サーバーのエントリー（上記のJSONブロック）を安全に追加できます。ユーザーがHILAN_DB_KEY環境変数を代わりに使わず、setup-key（OSの資格情報ストア）を使っていれば、この設定にはシークレットは含まれません。
3. 設定を追加したら、新しいツールを使えるようにするため、ユーザー（またはクライアント）がMCP接続を再読み込み／再起動する必要があります。
4. ユーザーから明示的に求められない限り、HILAN_ENABLE_DEBUG_TOOLSを有効にしないでください。生の.asmx／PDFを調査するためのツールは意図的に用意された非常用手段であり（セキュリティモデルを参照）、通常の使用には必要ありません。
5. ツールの応答に_updateNoticeフィールドが含まれている場合は、ユーザーに伝えて更新するか尋ねてください。更新しない場合は、そのバージョンを指定してdismissUpdateNoticeを呼び出してください（MCPツールを参照）。

MCPツール

更新通知：このサーバーには独自のUIがないため、更新チェックはエージェントが次に呼び出すツールに便乗して行われます。1日に最大1回、ツールの呼び出しが成功すると、_updateNoticeフィールドが追加され、「新しいhilan-mcpバージョンが利用可能です：0.1.0 -> 0.2.0...」のようなメッセージが含まれる場合があります。これを読んでいるAIエージェントは、ユーザーに伝えて更新するかどうかを尋ねてください。ユーザーが更新しないと答えた場合は、そのバージョンを引数にしてdismissUpdateNoticeを呼び出し、再通知されないようにしてください（後日、新しいバージョンがあれば通知されます）。更新チェック自体は、3秒のタイムアウトでnpmレジストリにアクセスします。レジストリに到達できない場合（オフラインや企業プロキシなど）は何もせずに終了し、ツール呼び出しが失敗することはありません。

並行処理に関する注意：特定のテナントに対するすべてのツール呼び出しは自動的にキューに登録され、内部で1つずつ順番に実行されます（TenantService.runExclusiveを参照）。Hilanのサイト（および／またはそこへのネットワーク経路）は、1つのセッションからの同時リクエストにうまく対応できず、同時に実行するとすべてタイムアウトします。呼び出しを自分で順番に実行する必要はありません。異なるテナントの処理は引き続き完全に並行して実行されます。

対応範囲（v1）

• ✅ 給与明細（一覧、構造化されたBruto／Neto／内訳、PDF）
• ✅ Form 106（PDF、年ごと）
• ⛔ 一般ファイルアーカイブ、Form 101 — 未実装（v1.1以降）
• ⛔ ワンタイムコード／2FAログイン — 要求するテナントではハングせず、明確な「未対応」エラーを返します

内部APIの応答が、参照テナント（Amdocs）で確認された構造化形式と一致しないテナントには、pdf_onlyのマークが付きます。給与明細の同期は引き続き機能し、PDFも保存されますが、Bruto／Netoの数値は解析されません。

信頼性に関する注意事項（実際のエンドツーエンド実行から得た知見）

• SQLite データベース全体（macOS では ~/Library/Application Support/HilanMcp/hilan.db、その他の環境では XDG/AppData に相当する場所）は、選択したパスフレーズを鍵として SQLCipher（better-sqlite3-multiple-ciphers）で保存時に暗号化されます。パスフレーズがディスクに保存されることはありません。PDF は同じ場所の .../HilanMcp/pdfs/<tenant>/ に、ローテーションするログファイルは .../HilanMcp/logs/ に保存されます（ログは秘匿化されます。以下を参照）。アプリデータ、PDF、ログの各ディレクトリには 0700 の権限が、DB ファイルと PDF ファイルには 0600 の権限が設定されます。
• credentials（ログイン情報）と sessions（保存されたブラウザー Cookie）は、暗号化されたデータベース内の通常のテーブルですが、query／listTables／describeTable ツールからアクセスすることはできません。これらのツールでは payslips と form106 のみを厳密に許可リストに指定し、正規表現ではなく完全な SQL AST 解析によって検証するため、JOIN、サブクエリ、引用符付き識別子を使って許可リストを回避することはできません（src/utils/sqlValidation.ts と src/tests/sqlValidation.test.ts を参照）。
• Cookie と認証ヘッダーはログファイル、およびツール呼び出しが返すエラーメッセージから秘匿化されます。そのため、Playwright のエラーによってセッション情報がチャット履歴に漏れることはありません（src/utils/redact.ts を参照）。
• 認証情報の入力（ingest-creds）は、必ずご自身のターミナルで直接実行してください。入力内容が記録される可能性のあるアシスタントのシェルツール経由で実行してはいけません。
• debugCallAsmx は、意図的に設けられた制限を回避するための手段です。ログイン済みのセッションから、任意の本文で任意の .asmx エンドポイントを呼び出せるため、上記の厳選されたツールを迂回できます。これは開発中の API 調査のために追加されたもので、対象は従業員 1 人に限定されます（同じセッションを使い、サイト上で既にお持ちの権限を使用します）。そのため、他の従業員のデータや他のテナントにはアクセスできません。ただし、原則として書き込みエンドポイントを呼び出せる可能性があります（Hilan では通常、承認フローを経なければ書き込みできませんが、これは監査されていません）。デフォルトでは無効です（HILAN_ENABLE_DEBUG_TOOLS）。query の SQL による制限回避手段と同様に扱ってください。探索を任せられると信頼できる AI アシスタントには問題ありませんが、信頼できない入力に公開するものではありません。

開発

このリポジトリをクローンして、コード自体を操作します（サーバーを使用するだけなら必要ありません。その場合は上記のセットアップを参照してください）。

npm install
npm run typecheck
npm test                 # unit tests (SQL allowlist, path-traversal, redaction, update checks, ...)
npm run build            # compile TypeScript -> dist/
npm run start:mcp        # run the server directly from source (stdio transport)
npm run setup            # local equivalent of `npx hilan-mcp setup`
npm run ingest-creds     # register a tenant + credentials (interactive, run yourself)
npm run setup-key        # store the DB encryption key in your OS credential store (interactive, run yourself)

npm publish で公開されるのは dist/、README.md、LICENSE のみです（package.json の files フィールドを参照）。ソース、テスト、ローカルの調査用成果物は含まれません。prepublishOnly では、最初に型チェック、テスト、ビルドが実行されるため、ビルドに失敗した状態では公開できません。公開された bin エントリ（dist/cli/index.js）は、npx hilan-mcp と npx hilan-mcp <subcommand> の両方から呼び出されます。

ライセンス

MIT