b1-mcp-server for SAP B1

b1-mcp-server

Model Context Protocol に対応した安全なサーバーです。 AI クライアント（Claude Code など）が、データベース（HANA / MS SQL）と Service Layer OData API の両方を通じて、SAP Business One に制限付きでアクセスできます。

特長

• 7 つの MCP ツール：connect_database、execute_sql、execute_service_layer （GET）、execute_service_layer_write（PATCH / POST / DELETE）、 execute_service_layer_write_unattended（承認なしで同じ書き込みを実行。 開発プロファイルのみ）、get_schema_info、check_connection。
• 複数環境への対応：名前付き接続プロファイルを使って、実行時にクライアントの データベースを切り替えられます。再起動は不要です。
• 設計上の読み取り専用：SQL の実行経路では SELECT のみを実行します。 すべての INSERT/UPDATE/DELETE/DROP/CREATE/ALTER/EXEC はサーバー側で ブロックされ、確認による回避もできません。書き込みは、実際の DB クライアントで 人間が実行するように引き渡されます。
• サーバー側のガードレール：execute_sql に送信されたすべての生 SQL は、 ユーザーと AI のどちらが記述した場合も同じ検証を受けます。匿名の DO BEGIN..END ブロックは、その内部にある最も危険なステートメントに基づいて 分類されるため、末尾の SELECT の後ろに隠された書き込みも書き込みとして扱われます。
• 監査証跡：選択されたプロファイルへの接続試行と、ポリシー判定または実行に 到達したデータベース／Service Layer 呼び出しを、ポリシーによる拒否も含めて JSON Lines 形式で記録します。
• ツールごとにスライディングウィンドウ方式のレート制限を適用します。

インストール

Node.js 20 以降が必要です。

npx b1-mcp-server

または、Claude Code の MCP 設定に追加します。

{
  "mcpServers": {
    "b1-db": {
      "command": "npx",
      "args": ["-y", "b1-mcp-server"]
    }
  }
}

依存関係

実行時の依存関係は 5 つです：@modelcontextprotocol/sdk、zod、 @sap/hana-client、mssql（および HANA 接続プールを支える generic-pool）。 データベースへのアクセスには、HANA および MS SQL クライアントを直接利用する ローカルドライバー src/db/directDb.ts を使用します。Service Layer の通信には、 Node.js 標準の fetch と https を使用する、厳格な TLS 対応アダプター src/sl/serviceLayerAdapter.ts を使用します。HTTP フレームワークも axios も PostgreSQL ドライバーも使用しません。

クリーンインストールでは overrides ブロックなしで found 0 vulnerabilities となるため、npx -y b1-mcp-server でも問題ありません。npx はルートの package.json なしで実行されるため、オーバーライドが適用されることはありません。

接続プロファイル

サーバーは未接続の状態で起動します。接続情報は ~/.claude/connections.json（環境ごとに 1 つのプロファイル）から読み込まれ、 実行時に AI が connect_database ツールを使って選択します。

connect_database におけるプロファイルの照合動作：

• id または dbName の完全一致が優先されます。
• 部分一致は、該当するプロファイルが 1 つだけの場合に限り受け付けられます。
• 部分一致の候補が複数ある場合は、候補の一覧とともに拒否されます。

~/.claude/connections.json の例：

[
  {
    "id": "client_a_prd",
    "dbType": "hana",
    "dbServer": "10.0.0.10:30015",
    "dbName": "SBO_CLIENT_A",
    "dbUser": "B1ADMIN",
    "dbPassword": "•••",
    "slUrl": "https://10.0.0.10:50000/b1s/v2",
    "slUser": "manager",
    "slPassword": "•••",
    "slAllowedMethods": ["GET", "PATCH", "POST"]
  },
  {
    "id": "client_b_hmg",
    "dbType": "mssql",
    "dbServer": "10.0.0.20:1433",
    "dbName": "SBO_CLIENT_B_HMG",
    "dbUser": "SA",
    "dbPassword": "•••"
  }
]

各プロファイルには id、dbType、dbName が必要です。DirectDb を設定するには dbServer と dbUser を追加し、Service Layer を設定するには slUrl と slUser を追加します。設定した各接続先には、空ではないパスワード（dbPassword または slPassword）も必要です。パスワードがない、または空の場合は、ログインを試みずにローカルで失敗します。これにより、設定済みのログインポリシーでアカウントロックの回数に加算される可能性がある、不要な失敗を回避できます。空ではないパスワード文字列は、トリミングせずにそのまま渡されます。1つのプロファイルで、いずれか一方または両方の接続先を設定できます。

slAllowedMethods（任意）では、そのプロファイルの Service Layer ツールが送信できる HTTP メソッドを指定します。GET、PATCH、POST、DELETE のいずれかを指定できます（大文字と小文字は区別されません）。指定しない場合、プロファイルは読み取り専用（["GET"]）となり、書き込みメソッドを使うには、それぞれを明示的に指定する必要があります。PUT はサポートされていません。エンティティ全体を置き換え、リクエストボディから省略されたすべてのフィールドを消去するためです。無効な値（未知のメソッド、空のリスト、配列以外）がある場合、推測して処理するのではなく、そのプロファイルをスキップします。このリストは接続時に適用され、connect_database によって出力されます。編集した場合は、次回の connect_database 呼び出し時に Service Layer へ再ログインします。書き込みメソッドを許可しても、承認が不要になるわけではありません。すべての書き込みには、セキュリティポスチャの説明にある、呼び出しごとのユーザー承認が引き続き必要です。

slWriteApproval（任意）では、書き込みを誰が承認するかを選択します。"elicitation"（デフォルト）：サーバーが MCP 承認フォームを通じて確認を求めます。"client"：サーバーはフォームを送信せず、MCP クライアント独自の権限確認プロンプトに依存します。Claude Code Remote Control のように、権限確認プロンプトは転送するものの MCP フォームは転送しないなど、フォームをユーザーに届けられない環境向けです。client が適用されるのは、MCP クライアントが Claude Code であると識別された場合のみです。それ以外のクライアントでは elicitation に切り替わります。サーバーからそのプロンプトは見えないため、このモードの安全性はクライアントの権限設定に依存します。mcp__<server-name>__execute_service_layer_write は permissions.ask に指定し、allow には指定しないでください。また、--dangerously-skip-permissions と併用しないでください。このルールがないと、最初のプロンプトで「はい、今後は確認しない」を選んだ際に allow ルールが保存され、以後の書き込みがすべて確認なしで実行されます。本番環境のプロファイルでは elicitation を使用してください。connect_database は現在のクライアントに適用されるモードを出力します。編集した場合は、Service Layer に再ログインします。

"none" は、書き込みのたびに確認を求めると作業が遅くなる開発会社向けです。execute_service_layer_write は client モードと同様に動作し、プロファイルではさらに execute_service_layer_write_unattended が有効になります。このツールは、どの MCP クライアントから呼び出しても、承認を一切求めずに同じ書き込みを実行します。このツールは "none" に設定されていないプロファイルではすべての実行を拒否するため、mcp__<server-name>__execute_service_layer_write_unattended は permissions.allow に指定し、通常の書き込みツールは permissions.ask に指定できます。これにより、開発用プロファイルでは確認なしで実行され、それ以外のすべてのプロファイルでは引き続き確認が求められます。このオプトイン設定は接続ファイルにのみ存在するため、その安全性はファイルの管理に依存します。本番データを指すプロファイルでは、決して "none" に設定しないでください。

SAP Service Layer のルートはどちらもサポートされています。OData v3 の /b1s/v1 と OData v4 の /b1s/v2 です。ログイン、ヘルスチェック、相対 Service Layer リクエストには、プロファイルで設定したルートがそのまま使用されます。リクエストの検証はバージョンに依存しません。呼び出し側は相対エンドポイントのみを渡します（例：Items?$select=ItemCode&$top=1）。OData のクエリやペイロードの違いへの対応は、引き続き呼び出し側の責任です。対象の SAP B1 インストール環境でサポートされるルートを設定してください。SAP は SAP Business One 10.0 FP 2405 から OData v3 を非推奨とし、OData v4 を主要プロトコルとしました。そのため、対象のインストール環境がサポートしている場合は /b1s/v2 を優先してください。詳細はService Layer API リファレンスを参照してください。

セキュリティモデル

サーバーは、プロファイルのパスワードを MCP ツールの応答や監査ログに意図的に埋め込みません。 サーバープロセス内で ~/.claude/connections.json からパスワードを読み取り、ログインのために設定済みのデータベースまたは Service Layer エンドポイントへ直接渡します。その後、Service Layer アダプターが保持するのはセッション Cookie のみで、ユーザー名やパスワードは保持しません。ただし、診断用にデータベースドライバーと Service Layer のエラーメッセージをそのまま返し、監査ログにも記録するため、任意の上流エラーテキストに対する汎用的なシークレットの秘匿境界はありません。プロファイル ID、データベース名、URL、その他パスワード以外のメタデータにシークレットを含めないでください。このプロトコルレベルの保護では、同じユーザーのシェルやファイルシステムに無制限にアクセスできる AI ホストが、ファイルを直接開くことは防げません。以下のフックに関するガイダンスを参照してください。

Service Layer 接続では、デフォルトで通常の証明書検証を伴う HTTPS が必要です。内部の認証局を使用する場合は、MCP プロセスを起動する前に NODE_EXTRA_CA_CERTS に CA バンドルを設定してください。

証明書を更新できないレガシー SAP インストール環境では、最初の connect_database 呼び出し時に、認証情報を送信せずに TLS を検査し、MCP フォームのエリシテーションを通じて明示的な承認を求めます。承認された証明書は、正規化された https://host:port オリジンをキーとして ~/.claude/service-layer-trust.json（モード 0600）に保存されるため、同じ SL エンドポイントを共有するプロファイル間で同一のピンが使われます。このファイルは、明示的な承認を得た後、または一致するレガシー手動プロファイルのピンを正常に移行した後に作成され、認証情報は含まれません。証明書が変更された場合は再度承認が必要です。エリシテーションに対応していないクライアントでは、安全側に失敗します。レガシーの手動プロファイルのピンフィールドは、このローカルストアへの一度限りの移行に限り引き続き受け付けられます。

証明書をピン留めした後は、その正確なフィンガープリントだけで検証が完了し、その上にホスト名検証は適用されません。SAP B1 は自己署名の Service Layer 証明書をマシンの短縮名（DNS:MYSERVER）に対して発行しますが、クライアントは通常 FQDN で接続するため、名前を再検証すると、すでに承認済みの証明書が拒否され、受け入れる方法がなくなります。そのため slTlsServerName は、名前ごとに異なる証明書を配信するホストに対して、ハンドシェイク時に送信する SNI 名としてのみ使用します。ピン留め済みの FQDN 接続を機能させるためには必要ありません。Service Layer の URL には、DNS 名、IPv4、IPv6 を使用できます。IP アドレスの URL では、slTlsServerName に DNS ホスト名が指定されていない限り SNI は省略されます。IP アドレスを指定したレガシーの slTlsServerName は、何もしない値として受け付けられます。古いトラストストアのレコードには、互換性のためのフォールバックとして serverName が残っている場合がありますが、新しい SNI 設定は証明書の信頼メタデータではなく、接続プロファイルに記述してください。

プロファイルは connect_database を呼び出すたびに再読み込みされます。DB 専用プロファイルには、DB 接続がアクティブな間に slUrl、slUser、slPassword を追加できます。次の呼び出しでは、その DB 接続を維持したまま Service Layer のみを初期化します。

証明書のグローバルな検証無効化は一切サポートされません。NODE_TLS_REJECT_UNAUTHORIZED=0 が設定されている場合、アダプターは接続を拒否します。

AI が connect_database に "list" を指定して呼び出したときに確認できる情報は次のとおりです。

• プロファイルの id
• dbName、dbType
• 機能フラグ（DB、SL、DB+SL）
• 設定済みのいずれかの側が現在接続中の場合の active マーカー

connections.json に関する推奨事項：

• ファイルへのアクセスを自分のユーザーのみに制限してください。
  • Linux/macOS：chmod 600 ~/.claude/connections.json。
  • Windows：icacls "%USERPROFILE%\.claude\connections.json" /inheritance:r /grant:r "%USERNAME%:F"。
• Git リポジトリにコミットしたり、クラウド同期で共有したりしないでください。
• POSIX システムでは、グループまたは他のユーザーに権限を与えるプロファイルファイルの読み込みをサーバーが拒否し、安全側に失敗します。
• 各ユーザーがそれぞれ自分のコピーを管理します。認証情報がこの npm パッケージから取得されることはありません。

Claude Code のフックとサンドボックスに関するガイダンス

中央管理される Claude Code の PreToolUse フック、または同等のホストポリシーを使用して、connections.json の正規化された解決済みパスへの AI によるアクセスを拒否してください。ファイルシステムを操作できるすべてのツール（Read、Grep、Glob、編集／書き込みツール、ファイルシステム MCP サーバー）を対象にし、ファイル名の文字列そのものに一致する場合だけに限定しないでください。シェルコマンドは難しいケースです。コマンド、作業ディレクトリ、シンボリックリンクを介して間接的にアクセスできるため、パス文字列の照合だけでは不十分です。認証情報のパスを拒否するホストのファイルシステムサンドボックスを優先してください。それ以外の場合は、ワークスペース外へのシェルアクセスに承認を必須としてください。

フック／ポリシーは、AI が書き込み可能なプロジェクト設定およびユーザー設定の外部に置く必要があります。Claude Code のエンタープライズ環境では、プロジェクトの指示によって上書きされないよう、プラットフォームの管理対象設定にインストールしてください。service-layer-trust.json への AI による書き込みも拒否してください。このファイルの読み取りは秘密情報の漏えいにはあたりませんが、完全性によって信頼されるレガシー証明書が決まります。

フックは多層防御策であり、OS のセキュリティ境界ではありません。AI ホスト経由で発行されたツール呼び出しを制御しますが、この MCP プロセス、別のローカルプロセス、または同じ OS ユーザーとして実行される悪意のある npm パッケージによる、モード 0600 のファイルの読み取りを阻止することはできません。強力な分離には、専用の OS ID、サンドボックス、またはリモートホスト型の認証情報ブローカーが必要です。Claude Code のフックとサーバー管理設定のガイダンスを参照してください。

Configuration（環境変数）

すべて任意です。

.env ファイルはありません。 サーバーは process.env を直接読み取り、dotenv ファイルを読み込まないため、サーバーの隣に .env を置いても何も起こりません。stdio MCP サーバーの場合、環境変数はクライアント側で管理します。MCP 設定の env ブロックに変数を設定すると、クライアントが起動したプロセスに渡します。

{
  "mcpServers": {
    "b1-db": {
      "command": "npx",
      "args": ["-y", "b1-mcp-server"],
      "env": {
        "MCP_QUERY_TIMEOUT_MS": "120000",
        "MCP_SL_WRITES_ENABLED": "false"
      }
    }
  }
}

認証情報はこの方法では設定しません。認証情報は connections.json のみに保存されます。このファイルはホームディレクトリから解決されるため、npx をどこから実行しても見つかります。

変数	デフォルト値	用途
MCP_CONNECTIONS_FILE	~/.claude/connections.json	プロファイルファイルのパス
MCP_AUDIT_LOG_PATH	~/.claude/logs/b1-mcp-audit.jsonl	監査ログの JSONL ファイル。未設定または空の場合はデフォルトのパスを使用します
MCP_LOG_LEVEL	info	標準エラー出力のログ詳細度：debug / info / warn / error。JSONL ファイルへのログ記録には影響しません
MCP_MAX_QUERY_LENGTH	8000	SQL の最大文字数
MCP_RATE_LIMIT_MAX_CALLS	60	期間あたりのツールごとの最大呼び出し回数
MCP_RATE_LIMIT_WINDOW_MS	60000	レート制限の期間
MCP_QUERY_TIMEOUT_MS	60000	ステートメントの実行上限時間。この時間に達しても実行中のクエリは中断されます。正当なレポートの実行にさらに時間が必要な場合は、値を大きくしてください
MCP_SL_TIMEOUT_MS	30000	Service Layer のログイン／リクエストのタイムアウト
MCP_SL_TRUST_FILE	~/.claude/service-layer-trust.json	ローカルの非機密証明書信頼ストア
MCP_SL_MAX_URL_LENGTH	2048	相対 OData URL の最大長
MCP_SL_MAX_BODY_CHARS	50000	シリアライズされた PATCH／POST ボディの最大文字数
MCP_SL_WRITES_ENABLED	true	Service Layer のすべての書き込み（PATCH、POST、DELETE）を対象とする緊急停止スイッチ。true／false は大文字と小文字を区別せず、無効な値の場合は書き込みを無効にします。読み込まれなくなった MCP_SL_PATCH_ENABLED に代わる変数です。ただし、旧変数に true 以外の値が指定されている場合も書き込みは無効になるため、アップグレードによって書き込みが再び有効になることはありません
MCP_ELICITATION_TIMEOUT_MS	120000	証明書の信頼設定や Service Layer の書き込みなどの承認フォームに人間が回答できる時間。時間切れの場合は安全側に倒して失敗します
MCP_MAX_RESULT_ROWS	500	モデルに返す最大行数。超過した行は切り捨てられ、その旨が通知されます
MCP_MAX_RESULT_CHARS	100000	結果 JSON の最大文字数。行数制限の適用後に適用されます
MCP_DRY_RUN	false	値が正確に true の場合、実行せずに生 SQL と Service Layer の書き込みを検証します。接続と Service Layer の GET は引き続き実行されます

上記の数値制限には、正の整数を指定する必要があります。未設定または空白のみの値にはデフォルト値が使用されます。それ以外の無効な値（0、負の数、整数以外など）が指定された場合は、標準エラー出力にフォールバック値を表示してデフォルト値を使用します。制限の設定ミスによって「制限なし」になることはありません。MCP_LOG_LEVEL も同様に、未設定または空の場合は info を使用し、それ以外の無効な値にはフォールバック値を表示します。

ガードレールの概要

SQL パスは読み取り専用のため、どのテーブルを操作するかによって実行中の応答が変わることはありません。

操作	任意のテーブル（SAP コア、UDT、カスタム、一時テーブル）
SELECT	許可。ただし、以下の SELECT 固有の制限に従います
INSERT / UPDATE / DELETE / DROP	ブロック — DB クライアントでご自身で実行してください
CREATE / ALTER	ブロック
EXEC / EXECUTE / CALL	ブロック — このサーバー経由ではストアドプロシージャを実行できません

ほかにも、複数ステートメントのクエリ（BEGIN..END の外にセミコロンがあるもの）、閉じられていない引用符や角括弧、シーケンスの進行（NEXTVAL / NEXT VALUE FOR）、OPENQUERY / OPENROWSET / OPENDATASOURCE、 SELECT ... INTO <table>、および影響の大きい SQL Server のロックヒント（UPDLOCK、 XLOCK、TABLOCK、TABLOCKX、HOLDLOCK、SERIALIZABLE、 REPEATABLEREAD）もブロックされます。

Service Layer リクエストで許可されるのは、プロファイルの slAllowedMethods （デフォルトは GET のみ）に指定されたメソッドだけです。PUT は常に利用できません。PATCH と DELETE には、キーを直接指定したエンティティエンドポイントが 1 つ必要です。POST では、エンティティセット、サービス操作、またはキーを指定したエンティティに対する単一のアクション（Orders(12)/Close）を指定できます。書き込みではクエリオプションを使用できません。書き込みは専用ツール execute_service_layer_write を経由するため、クライアントはツール名を使って書き込みを制限し、GET は確認なしで実行できます。すべての書き込みでは対象の database を指定する必要があり、接続先の Service Layer と一致しなければなりません。デフォルトでは、すべての書き込みで MCP フォームによる確認を通じて、ユーザーの明示的な承認が必要です。承認画面は、データベース、Service Layer のルート、エンドポイント、本文全体、フィールド一覧、および本文の SHA-256 ハッシュに紐付けられます。エリシテーションに対応していないクライアントでは書き込みできません。slWriteApproval: "client" を指定したプロファイルではフォームの代わりに Claude Code の権限確認が使用され、slWriteApproval: "none" を指定したプロファイルでは、execute_service_layer_write_unattended による未承認の書き込みも受け付けます（上記のプロファイルフィールドを参照してください）。 MCP_DRY_RUN=true の場合、書き込みは実行されません。また、MCP_SL_WRITES_ENABLED=false にすると、すべての書き込みが全体で無効になります。

テーブルごとの分類モデル（SAP_CORE / SAP_USER / CUSTOM / TEMP と操作ごとのルール）は、現在も src/guardrails/rules/ に存在し、十分にテストされていますが、読み取り専用サーバーの実行パスからはアクセスできません。モデルの詳細と既知の制限については、SECURITY.md を参照してください。

エージェントスキル

skills/b1-mcp-server/SKILL.md では、AI エージェントがこれらのツールを使用する方法を説明しています。最初に接続する方法、拒否メッセージの意味と対処方法、HANA のタイムアウトでソケット切断が報告される理由、結果が切り詰められた場合の表示、および Service Layer の書き込みが承認される仕組みについて説明します。Claude Code にインストールするには、フォルダーを ~/.claude/skills/ にコピーしてください。SKILL.md ファイルを読み込むほかのエージェントの場合は、各エージェントのスキルディレクトリに配置してください。

開発

npm install
npm run build
npm run test
npm run test:watch
# Optional aliases (same behavior, useful if you prefer explicit naming):
npm run test:bash
npm run test:watch:bash

ソースをチェックアウトした場合に限り、connections.json のプロファイルを使って、次の簡易接続確認を実行してください（scripts/ は npm の tarball には含まれていません）。

npx tsx scripts/test-connection.ts <profile-id>

ライセンス

MIT — LICENSE を参照してください。