SAP Business One MCP Server Sample

• SAP Business One MCP Server Sample

  • はじめに

  • アーキテクチャの概要

  • 利用可能なMCPツール

    • コアの発見・実行ツール

      • 3ステップの段階的発見

    • 会社選択ツール

    • ワークフローヘルパーツール

    • MCPリソース

  • 前提条件

  • インストール

  • 設定

    • 直接モード（開発専用）

    • OAuthモード（本番・デフォルト）

    • HTTPS / トランスポート

  • サーバーの起動

  • AIクライアントの接続

    • Cline（VS Code）

    • GitHub Copilot（VS Code）

    • Goose（デスクトップ）

    • MCP Inspector（ブラウザ）

  • MCPクライアントの統合

  • 人間による確認（MCPエリシテーション）

  • 個人データの分類

    • フィールドの分類方法

    • 分類が表示される場所

    • 実行時の保護

    • 読み取り結果のマスキング動作

  • UDO/UDT/UDFサポート

    • UDOの命名

    • 発見の遅延

  • マルチテナントサポート

  • 使用例

    • 自然言語クエリ

    • ワークフロー例

      • 基本CRUDワークフロー

      • 注文から現金化までのワークフロー（ステップバイステップ）

    • ビジネスインテリジェンスクエリ

    • データ操作

  • サーバーのテスト

    • 単体テスト

    • 統合テスト

    • 総合品質チェック

  • ログ

    • アプリケーションログ

    • 監査ログ

  • セキュリティ上の考慮事項

    • 認証

    • 認可

    • 本番構成

  • トラブルシューティング

    • サーバーまたは接続の問題

    • 認証と会社コンテキスト

    • エンティティ、フィールド、書き込みの問題

    • デバッグオプションの有効化

  • 設定リファレンス

  • 制限事項

はじめに

SAP Business One 10.0 FP2608 以降、SAP Business One MCP Server のサンプルが提供され、SAP B1 Service Layer の OData サービスを、Model Context Protocol (MCP) をサポートする AI エージェント向けの動的なツールとして公開する方法を示しています。

このサンプルサーバーは、最小限で理解しやすい設計を保ちながら、MCP サーバーの核となるパターンと機能を紹介することを目的としています。数百もの個別の CRUD ツール（エンティティ × 操作ごとに 1 つ）を登録する代わりに、このサーバーは段階的発見アーキテクチャを採用し、数百の候補ツールをいくつかの高機能で再利用可能なツールに集約しています。

この設計により、AI エージェントは以下のことが可能になります。

• 発見 — 軽量なセマンティック検索により、関連する B1 エンティティを発見

• 理解 — プロパティ、型、機能を含む完全なエンティティスキーマを理解

• 実行 — 自動 OData クエリ生成による認証付き CRUD 操作を実行

「残高の上位 10 社の売上を表示して」や「仕入先 V00001 の注文書を作成して」といった自然言語リクエストは、適切な Service Layer API 呼び出しに自動的に変換されます。

このプロジェクトは、参考および学習を目的としたサンプルとしてのみ提供されています。 必ずしも本番で使用できる製品ではありません。SAP B1 パートナーや開発者の皆様には、このアーキテクチャを学び、コードを適応し、組み込み機能を評価し、それぞれのビジネス要件やデプロイ環境に合わせた独自の MCP サーバー実装を構築することをお勧めします。

バージョン要件: この MCP サーバーは SAP Business One 10.0 FP2608 以降 が必要です。これは FP2608 で導入された Service Layer API に依存しており、以前のバージョンでは正しく機能しません。

MCP プロトコルバージョン: このサンプルは、SAP Business One 10.0 FP2608 向けに、Model Context Protocol 仕様 の最新版である MCP プロトコルバージョン 2025-11-25 を実装しています。このサーバーに接続する MCP クライアントもプロトコルバージョン 2025-11-25 をサポートしている必要があります。MCP プロトコルの進化に伴い、このサンプルも新しい仕様リリースに合わせて更新されます。

Related MCP server: SAP OData MCP Server

アーキテクチャの概要

MCP サーバーは、AI エージェント（Cline、GitHub Copilot、Cursor など）と SAP B1 Service Layer の間に位置します。SAP Business One MCP Server は、OData サービス契約を AI に活用しやすい MCP ツールに変換する、モダンなレイヤード（階層型）アーキテクチャを実装しています。このアーキテクチャは、トークン効率と包括的な機能公開のバランスを実現すえた、プログレッシブ（段階的）発見パターンを中心に構成されています。

このアーキテクチャでは、AI エージェント内の MCP クライアントは、MCP プロトコルを実装する安全な HTTP トランスポート層を通じて MCP サーバーと通信します。認証には、MCP サーバーが Keycloak と連携した OAuth2 を利用します。MCP クライアントまたは AI エージェントは、Extension SSO Manager を通じて OAuth クライアントとして登録し、標準 Key OAuth2 フローでアクセストークンを取得します。このトークンを使用して、クライアントは必要に応じて SLD から会社リストを取得し、リクエストに正しい会社コンテキストを含めることができます。サーバーは、受信した各リクエストを検証し、Bearer トークンを Keycloak で検証して認証済みクライアントのみが MCP ツールにアクセスできることを確認するとともに、audience クレームを検証してトークンがこのサーバーに送られることを確認します。

利用可能なMCPツール

重要: ツールは AI モデルが利用するものであり、安定した API を構成するわけではありません。ツール名、パラメータ、動作はバージョンによって変更されることがあります。特定のツール署名に過度に依存しないでください。

コアの発見・実行ツール

このサーバーは、数百もの個別の CRUD ツールではなく、4 つのコアとなる発見・実行ツール を使用します。

段階的な3ステップのディスカバリー

サーバーは、すべてを3ステップのフローに凝縮することで、ツール爆発を回避しています：

Step 1: b1_find_entities        → Lightweight semantic search; returns entity names and categories
Step 2: b1_get_entity_schema    → Full schema for a selected entity (properties, types, keys)
Step 3: b1_read / b1_write      → Execute the read or write operation with schema-informed parameters

• 効率性: ステップ1は、完全なスキーマと比べて約90%少ないデータを返します

• 明確な選択肢の分離: LLMは完全なスキーマを取得する前に、スキャンして選択できます

• 段階的な詳細: 複合タイプは、すべてを事前に取得せずにステップ2.2で詳細を確認できます

会社選択ツール

OAuthモードでは、エンティティツールを呼び出す前に会社を選択します：

ワークフローヘルパーツール

2つのワークフローヘルパーツールが、一般的なB1ビジネスワークフローを簡素化します：

実行時にワークフローツールを検出：

Show me what workflow tools are available in the B1 MCP server

AIエージェントは、category: 'workflow' を指定した b1_find_entities を呼び出すと、b1_copy_document と b1_create_payment の完全な説明を受け取ります。

コメントリソース

ツール呼び出しなしでコンテキスト知識を提供する2種類のリソースがあります：

利点: AIアシスタントはツール呼び出しなしでこれらのリソースに即座にアクセスできます。ワークフローにとってより効率的です！

前提条件

インストール

1. オンラインヘルプからこのパッケージ b1-mcp-server.zip をダウンロードし、展開してから、展開したプロジェクトフォルダーに移動します。

2. 依存関係をインストールしてコンパイルします:

npm install
npm run build

設定

すべての設定は、プロジェクトルートにある .env ファイルで管理されます。開始点として .env.example をコピーしてください:

cp .env.example .env

利用可能なすべての変数の完全なリファレンスについては、設定リファレンス の章を参照してください。

ダイレクトモード（開発専用）

SAP B1 Service Layer にユーザー名とパスワードでアクセスできる場合は、このモードを使用します。ローカル開発環境でのクイックプロトタイピングとテストのみに適しています。

注: .env ファイルでユーザー名とパスワードを使用していますが、これはHTTP Basic Authenticationではありません。この資格情報は、MCP サーバーが SAP B1 Service Layer のログインAPI（/b1s/v2/Login）を介してセッショントークンを取得するために使用され、以降のすべてのリクエストはそのセッショントークンで認証されます。

NODE_ENV=development
AUTHENTICATION_MODE=direct

# B1 Service Layer host (server appends /b1s/v2/ internally)
SERVICE_LAYER_ROOT_URL=https://servicelayer.b1.example.com:50000

B1_COMPANY_DB=yourCompanyDB
B1_USERNAME=yourUsernameHere
B1_PASSWORD=yourPasswordHere

# Accept self-signed certs for local development/testing only
AUTH_ALLOW_SELF_SIGNED=true

OAuth モード（本番環境、デフォルトモード）

Service Layer は常に Keycloak の前段に配置されるため、このデフォルトモードを使用してください。受信したベアラートークンは、B1 リクエストが転送される前に OAuth プロバイダーに対して検証されます。

# Default mode, validate incoming requests via OAuth 2.0 / OIDC (requires OAUTH_BASE_URL and OAUTH_CLIENT_ID)
AUTHENTICATION_MODE=oauth

SERVICE_LAYER_ROOT_URL=https://servicelayer.b1.example.com:50000
SLD_ROOT_URL=https://sld.b1.example.com:40000

OAUTH_BASE_URL=https://keycloak.b1.example.com/auth/realms/sapb1/
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret

HTTPS / トランスポート

サーバーはデフォルトでHTTPSを使用し、ローカル開発では自己署名証明書を使用します。必要に応じてHTTPに切り替えることもできます。

HTTPS（デフォルト）:

HTTPS_ENABLED=true
HTTPS_KEY_PATH=./certs/server.key
HTTPS_CERT_PATH=./certs/server.crt
PORT=3000

# Optional:
# HTTPS_CA_PATH=./certs/ca.crt
# HTTPS_PASSPHRASE=your-cert-passphrase

HTTP:

ローカルテストやブラウザのセキュリティ警告の回避、その他の理由（例: 前段にHTTPSゲートウェイやリバースプロキシがすでにある場合）により、HTTPSではなくHTTPを使用する場合は、次のように設定します:

HTTPS_ENABLED=false
PORT=3000

公開URL（MCP_BASE_URL）:

デフォルトでは、サーバーはアクティブなリスナー設定から公開URLを導出します。サーバーがリバースプロキシの後方にある場合や、OAuth メタデータと MCP エンドポイントに特定のベースURLをクライアントに使用させる必要がある場合は、この値を明示的に設定してください:

MCP_BASE_URL=https://mcp.example.com

ローカル開発では未設定のままにしてください。サーバーが正しいURLを自動的に推測します。

サーバーの起動

サーバーを起動します:

npm start

起動していることを確認します:

curl http://localhost:3000/health

サーバーは、組み込みの REST エンドポイントを3つ提供します:

OAuth に関する注: OAuth モードでは、GET /mcp のリクエストに Authorization ヘッダーの有効なベアラートークンが必要です。

GET /health — 応答例:

{
  "status": "healthy",
  "timestamp": "2026-06-17T03:50:58.338Z",
  "version": "1.0.0",
  "checks": {
    "auditLogger": { "healthy": true },
    "personalFieldCache": { "healthy": true }
  }
}

GET /mcp — 応答例:

{
  "name": "b1-mcp-server",
  "version": "1.0.0",
  "protocol": { "version": "2025-11-25", "transport": "streamable-http" },
  "capabilities": { "tools": {}, "resources": {}, "logging": {} },
  "features": [
    "Dynamic SAP Business One Service Layer OData service discovery",
    "CRUD operations for all discovered entities",
    "Natural language query support",
    "Session-based HTTP transport",
    "Real-time service metadata"
  ],
  "endpoints": { "health": "/health", "mcp": "/mcp", "docs": "/docs" },
  "activeSessions": 1
}

AIクライアントの接続

サーバーは Streamable HTTP の MCP エンドポイントを以下の場所に公開します:

http(s)://<host>:<port>/mcp

MCP 互換の AI クライアントはすべてこのエンドポイントに接続できます。以下の表は、サポートされているクライアント間の主な機能をまとめたものです。

MCPエリシテーションは、書き込み操作と機密読み取りの人間による確認に使用されます。クライアントがエリシテーションをサポートしていない場合は、.env で MCP_HUMAN_CONFIRMATION_ENABLED=false を設定してください。設定しない場合、それらの操作は拒否されます。詳細は 人間確認（MCPエリシテーション） を参照してください。

Cline (VS Code)

セットアップ手順、LLMプロバイダー設定、OAuth / Keycloak 設定、およびすべての CRUD 操作とワークフローツールを網羅したテスト例については、docs/B1_CLINE_INTEGRATION_GUIDE.md を参照してください。

GitHub Copilot (VS Code)

セットアップ手順、OAuth / Keycloak 設定、静的クライアント ID 設定、OAuth 会社選択フロー、エリシテーションのテスト例については、docs/B1_GITHUB_COPILOT_INTEGRATION_GUIDE.md を参照してください。

Goose (Desktop)

セットアップ手順、設定オプション、OAuth / Keycloak 設定、使用例については、docs/B1_GOOSE_INTEGRATION_GUIDE.md を参照してください。

MCP Inspector (Browser)

MCP Inspector を使用して、ツールを対話的に閲覧し、生の MCP メッセージを検査できます。OAuth モードでベアラートークンを取得し、必要なヘッダーを設定する方法を含む完全な使用手順は、docs/MCP_INSPECTOR.md を参照してください。

MCPクライアントの統合

OAuth モードでサーバーに接続するカスタム MCP クライアントアプリケーションを構築する場合、統合は標準的な PKCE OAuth 2.0 フローに従います:

1. GET /mcp から OAuth メタデータを取得します（サーバーは認可エンドポイントとトークンエンドポイントを公開します）。

2. PKCE 認可リクエストを開始し、ユーザーを Keycloak にリダイレクトします。

3. 認可コードをトークン（アクセストークン＋リフレッシュトークン）と交換します。

4. b1_list_companies で利用可能な会社を取得します。

5. ユーザーに会社を選択させ、b1_select_company を呼び出します。

6. すべての MCP リクエストにアクセストークンと会社 ID を含めます。

   • Authorization: Bearer <access_token>

   • x-b1-companyID: <companySchemaName>

7. 有効期限前にトークンを更新します。更新に失敗した場合は、PKCE フローを再開します。

注釈付きコードを含む完全な動作例（クライアント登録、OAuth フロー、会社選択、期待される出力を含む）については、docs/SIMPLE_MCP_CLIENT.md を参照してください。

人間の確認（MCPエリシテーション）

MCPエリシテーションは、MCP サーバがツール呼び出しの実行途中で一時停止し、続行する前に接続中のクライアントに追加の入力や確認を求めるためのプロトコルレベルの仕組みです。単なるプロンプトとは異なり、エリシテーションは MCP プロトコルに組み込まれています。サーバーは構造化されたリクエストをクライアントに送信し、クライアントはそれをユーザーに提示し（通常はインラインダイアログまたはフォーム）、サーバーは応答を待ってから続行するか中止するかを決定します。これにより、AIエージェントが確認フローを独自に即興で作る必要なく、機密操作で人間をループに保つことができます。

MCP_HUMAN_CONFIRMATION_ENABLED=true（デフォルト）の場合、サーバーは次の操作の前に一時停止します:

• 書き込み操作 (create, update, delete) — 明示的なユーザー承認を求めるプロンプトを表示します

• 機密読み取り — クエリが個人データ（メール、電話、身分証明番号）に分類されるフィールドを選択する場合にプロンプトを表示します

エリシテーションをサポートするクライアント（GitHub Copilot など）はインラインの確認ダイアログを表示します。サーバーが続行する前にユーザーが承認する必要があります。拒否すると、データは変更されずに操作がキャンセルされます。

書き込み確認プロンプトの例:

CONFIRM WRITE OPERATION | OPERATION: update | ENTITY: BusinessPartners |
TARGET: C00001 | FIELDS: Phone1=+1 555-1234 |
RISK: This action will modify SAP Business One data. |
ACTION: Set confirmed=true only if you intend to continue.

エリシテーションをサポートしないクライアント（例: Cline v4.0.8）:

サーバーは確認なしに進めるのではなく、機密読み取りと書き込み操作を拒否します。自動化または開発パイプラインでこれを回避するには、以下のように設定します:

MCP_HUMAN_CONFIRMATION_ENABLED=false

個人データの分類

サーバーは、SAP Business One PersonalFieldsSetups メタデータ（PersonalFieldsSetupsService_GetPersonalFieldsByTable を介してテーブルごと解決）を使用して、機密フィールドを分類し、読み取り時と書き込み時に保護を適用します。

フィールドの分類方法

• 分類ソース: PersonalFieldsSetupsService_GetPersonalFieldsByTable が返す、Service Layer のテーブルスコープの個人フィールドエントリ。

• 照合ルール: テーブル名とフィールド名が PersonalFieldsSetups の行と一致する場合、そのプロパティは個人としてマークされます。

• スコープ: 分類は、トップレベルのエンティティプロパティとネストされた複合型プロパティの両方に適用されます。

• ネスト解決: 複合プロパティの場合、テーブルコンテキストは子テーブルのマッピングに切り替わり、より深いネストを再帰的に処理します。

分類が確認される場所

• b1_get_entity_schema による Step 2 のスキーマ出力で、個人プロパティには isPersonalField が付与されます。

• テーブルマッピングで個人としてマークされた場合、スカラーフィールドとネストされた用の構造型プロパティが含まれます。

実行時の保護

MCP_HUMAN_CONFIRMATION_ENABLED=true の場合:

• 書き込み操作（create、update、delete）には、MCP エリシテーションによる明示的な確認が必要です。

• 機密読み取りには、selectString が個人のトップレベルフィールドを明示的に含む場合に確認が必要です。

クライアントが MCP エリシテーションをサポートしていない場合、これらの保護された操作はブロックされます。

読み取り結果のマスキング動作

読み取り時のマスキングは、selectString に意味があるかどうかによって異なります:

• selectString がない場合（空白または空白のみ）: トップレベルとネストされた複合データの両方で、個人フィールドに対してレスポンス全体のマスキングが再帰的に適用されます。

• スカラーの選択のみを含む意味のある selectString: 選択されたスカラーフィールドはリクエストされたとおり返されます。

• 複合プロパティを含む意味のある selectString: 選択されたスカラーフィールドは表示されたままとなり、選択された複合プロパティ内の個人フィールドは再帰的にマスキングされます。

つまり、ユーザー確認後に選択されたトップレベルのスカラー個人フィールドは表示できますが、選択された複合プロパティ内のネストされた個人フィールドは引き続きマスキングされます。

個人データ設定の詳細は、次のリンク参照することをお勧めします: SAP Business Oneヘルポータル - 個人データの保護。

UDO/UDT/UDF サポート

サーバーは、標準の SAP B1 エンティティに加えて、ユーザー定義 テーブル (UDO) オブジェクト (UDO)、ユーザー定義テーブル (UDT)、ユーザー定義フィールド (UDF) を自動的に検出して公開します。追加設定は不要です。

• UDOs は SAP B1 に登録すると、b1_find_entities で照会可能かつ書き込み可能なエンティティとして表示され、割り当てられたビジネスカテゴリの下で見つけることができます。

• UDTs（@ でプレフィックスが付けられたカスタムテーブル）は、普通のエンティティとして表面化され、標準エンティティと同じ CRUD 操作をサポートします。

• UDFs は標準またはカスタムテーブルに追加すると、b1_get_entity_schema が返すスキーマに、正しい型とメタデータとともに自動的に含まれます。

これは、SAP B1 で行われたカスタマイズ（パートナー拡張機能、ローカライゼーションアドオン、顧客固有フィールド）が、サーバー側の変更なしに、同じ3ステップのディスカバリーフローを介して AI エージェントに即座に利用できるようになることを意味します。

UDO の命名規則

UDO コードは Service Layer で認識されるよう、OData 識別子規則に準拠する必要があります。使用できるのは英字、数字、アンダースコアのみで、スペースやその他の特殊文字は使用できないことに注意してください（例: My Custom Object ではなく MY_CUSTOM_OBJECT を使用）。準拠していないコードの UDO はディスカバリできません。

ディスカバリの遅延

SAP B1 クライアント、Web クライアント、またはアドオンで追加・変更された UDO と UDT は、MCP サーバーに即座には反映されません。サーバーは Service Layer から取得した OData メタデータを、設定可能な期間（デフォルト: 30分、METADATA_CACHE_TTL_MINUTES で制御）キャッシュします。新規または変更された UDO/UDT は、キャッシュが自然に失効した後、または MCP サーバーを再起動した後にのみディスカバリ可能になります。カスタムオブジェクトを盛んに開発している間は、METADATA_CACHE_TTL_MINUTES を小さい値（例: 5）に設定すると、変更をより早く取得できます。

マルチテナントサポート

1つの MCP サーバーインスタンスで、設定変更なしに複数の SAP Business One の会社に対応できます。OAuth モードでは、アクティブなテナントまたは会社が、ランシステムランドスケープディレクトリ（SLD）?? のシステム・ランドスケープ・ディレクトリ（SLD）を使用してランタイムに動的に選択されます。

仕組み:

1. MCP クライアントは b1_list_companies を呼び出して、SLD に登録されているすべての利用可能な会社とそのステータスを取得します。

2. ユーザー（またはユーザーに案内された AI エージェント）は、選択した CompanySchemaName を指定して b1_select_company を呼び出し、対象とする会社を選択します。

3. その後のすべてのツール呼び出し（b1_find_entities、b1_read、b1_write など）は、セッション中は選択した会社の Service Layer データベースに対してルーティングされます。

4. 会社を切り替えるには、別のスキーマ名で b1_select_company を呼び出し直すだけです。サーバーの再起動は不要です。

主な特徴:

• セッションスコープ: 会社の選択は MCP セッションに結び付けられます。異なる AI クライアントセッションは、同じサーバーインスタンス上で同時に異なる会社を操作できます。

• SLD 駆動: 会社リストは SLD から直接取得され、登録済み会社の最新状態を反映します。設定に静的会社リストを保持する必要はありません。

• OAuth 限定: マルチテナントでの会社切替には OAuth モードが必要です。ダイレクトモードは単一のみのみ対応です（B1_COMPANY_DB は .env に固定されます）。

注: リクエストに有効な x-b1-companyID ヘッダーがすでに含まれている場合は、MCP サーバーはそれを直接使用するため、b1_list_companies と b1_select_company を呼び出す必要はありません。これらのツールの目的は、AI エージェントまたはユーザーが正しい会社スキーマ名を決定し、会社コンテキストがまだ不明な場合にそれを確立するのを支援することだけです。目的の会社が分かれば、その会社 ID（CompanySchemaName から解決される）を、以後の MCP リクエストすべての x-b1-companyID ヘッダーに直接渡すことができます。

使用例

自然言語クエリ

ワークフロー例

追加のビジネスワークフローを実装したり、新しい MCP ツールを追加したりするには、docs/DEVELOPER_GUIDE.md を参照してください。

基本的な CRUD ワークフロー

1. b1_find_entities → "BusinessPartners"
  ↓ Returns: List of matching entities

2. b1_get_entity_schema → "BusinessPartners"
  ↓ Returns: scalar properties plus structuralProperties[]

3. b1_get_entity_schema → "BusinessPartners", structuralPropertyName="ContactEmployees"
  ↓ Returns: sub-properties for that structural property when needed

4. b1_read or b1_write → execute the selected operation
   ✓ Executes operation with proper parameters

Order to Cash ワークフロー（ステップバイステップ）

1. b1_write → Create Sales Order
   ↓ Returns: DocEntry 123

2. b1_copy_document → Order → Delivery
   ↓ Returns: DocEntry 456 (automatic BaseType handling)

3. b1_copy_document → Delivery → Invoice
   ↓ Returns: DocEntry 789 (automatic BaseType handling)

4. b1_create_payment → Create Payment
   ✓ Validates and creates payment (automatic balance checking)

ビジネスインテリジェンスクエリ

User: "Show me top 10 customers by balance"
→ Tool: b1_read
→ Parameters:
  {
    "entityName": "BusinessPartners",
    "operation": "read",
    "filterString": "CardType eq 'cCustomer'",
    "orderbyString": "CurrentAccountBalance desc",
    "topNumber": 10
  }

User: "How many open sales orders are there?"
→ Tool: b1_read
→ Parameters:
  {
    "entityName": "Orders",
    "operation": "read",
    "filterString": "DocumentStatus eq 'bost_Open'",
    "selectString": "DocEntry"
  }

データ操作

User: "Update supplier V10000 to have phone number 123-456-7890"
→ Tool: b1_write
→ Parameters:
  {
    "entityName": "BusinessPartners",
    "operation": "update",
    "parameters": {
      "CardCode": "V10000",
      "Phone1": "123-456-7890"
    }
  }

サーバーのテスト

ユニットテスト

npm test

これは npm run test:unit のエイリアスです。ユニットテストは src/tests/unit/ の下にあります。

統合テスト

統合テストには、Service Layer と OAuth プロバイダーに到達できる稼働中の MCP サーバーが必要です。また、Keycloak で b1_mcp:access スコープを設定する必要があります（セットアップ手順は KEYCLOAK_SETUP.md を参照）。テストクライアントの認証情報を .env に設定してから、次を実行してください:

npm run test:integration

統合テストの主要変数:

統合テストは src/tests/integration/ の下にあります。

注: 依存関係を更新した後にテストが失敗する場合は、最初に npm run build を実行してください。コンパイル時エラーはテストランナーよりも先にそこで検出されることがよくあります。

総合品質チェック

lint、ビルド、ユニットテストを順番に実行:

npm run lint
npm run build
npm test
npm run test:integration

ログ記録

サーバーは、それぞれ独立して設定可能な2つのログストリームを生成します。

アプリケーションログ

アプリケーションログには、リクエスト処理、ツールのディスパッチ、セッションライフサイクル、Service Layer 呼び出しが含まれます。デフォルのレベルは info です。開発中は詳細ログを有効にして、サーバーの動作を追跡してください:

APP_LOG_LEVEL=debug
APP_LOG_CONSOLE_ENABLED=true

ログはデフォルトでローテーションファイルに書き込まれます（APP_LOG_FILE_ENABLED=true）。ファイルサイズと保持期間は APP_LOG_MAX_SIZE_BYTES（デフォルト 10 MB）と APP_LOG_RETENTION_DAYS（ヘルツ90日）で制御されます。

監査ログ

監査ログは、セキュリティ関連のイベント（書き込み確認、セッションの開始・失効、認証失敗など）を記録します。デフォルトではローテーションファイルに書き込まれ、本番環境では有効のままに設定してください。

開発中に監査イベントをコンソールにも出力するには:

AUDIT_LOG_CONSOLE_ENABLED=true

ファイルサイズと保持期間は、AUDIT_LOG_MAX_SIZE_BYTES（デフォルト 10 MB）と AUDIT_LOG_RETENTION_DAYS（デフォルト365日）で制御されます。

ログ関連変数の完全な一覧は、docs/CONFIGURATION_REFERENCE.md を参照してください。

OAuth モードに必要な Keycloak の手順（MCP サーバーのクライアント登録、クライアントスコープ、オーディエンスマッパー、信頼済みホストを含む）については、docs/KEYCLOAK_SETUP.md を参照してください。

セキュリティに関する考慮事項

注: このプロジェクトはサンプルです。本番環境にデプロイする前に、組織のセキュリティ基準とコンプライアンス要件に準拠していることを確認し、すべてのセキュリティ設定を強化してください。

認証

この MCP サーバーは、OAuth 2.0 フレームワークでは リソースサーバー（RS） として動作し、標準のMCPを認証メカニズムを使用します。AI エージェントからのすべてのリクエストには有効なベアラーアクセストークンが必要で、サーバーはリクエストを処理する前にトークンを検証します。

アクセストークンは、SAP Business One の Identity and Authentication Management サービスから有効なユーザー認証情報を提供して取得します。このサービスは Keycloak 上に構築されており、SAP IAS（Identity Authentication Service）や他の ID プロバイダーに接続してユーザー認証を行うように設定できます。

認可

認可は2つのレイヤーで強制されます:

レイヤー 1 — MCP サーバー: アクセストークンの scope と aud（オーディエンス）クレームを検証し、AI エージェントが要求された MCP ツールを呼び出せるかどうかを判断します。必要なスコープ b1_mcp:access を持ち、このサーバーを宛先とするトークンだけが受け入れられます。

レイヤー 2 — SAP B1 Service Layer: データアクセスの承認は Service Layer に委譲され、標準の SAP Business One アクセス制御モデルに照らして、トークンに関連付けられたユーザーロールと権限が評価されます。管理者はユーザーやグループごとにきめ細かいアクセスポリシーを定義できます。Service Layer が HTTP 403（Forbidden）を返した場合は、MCP サーバーは権限が不十分であることを知らせるエラーを AI エージェントに通知し、データは返しません。

本番環境の設定

本番デプロイを行う前には、次の設定を確認してください。

トランスポート

• HTTPS_ENABLED — デフォルトは true です。本番では必ず HTTPS を使用してください。TLS 終端のリバースプクキシのドールでのみ無効にできます。

• AUTH_ALLOW_SELF_SIGNED — デフォルトは false です。本番では有効にしないでください。有効な CA 証明書または NODE_EXTRA_CA_CERTS を使用します。

トークン検証

• TOKEN_VALIDATION_MODE — 本番では introspection または introspection-with-jwt-fallback（デフォルト）を使用してください。jwt のみのモードは、トークンが短時間（5分未満）でない限り（グブル）、失効済みトークンが期限まで有効なため避けてください。

• VALIDATE_AUDIENCE — デフォルトは true です。無効にすると他のサービス向けトークンが認証される可能性があります。OAuth プロバイダーが aud クレームを制限できない場合のだけ無効にしてください。

• OAUTH_VERIFY_SCOPES / OAUTH_REQUIRED_SCOPES — テレーム、スコープ検証は有効のままにし、必要最小限のスコープ（b1_mcp:access）に限定します。

ネットワークとアクセス制御

• MCP_ALLOWED_HOSTS — サーバーに到達できるホスト名をすべて指定します。一致しない Host ヘッダーを含むリクエストは拒否されます（DNS リバインディング保護）。

• REQUEST_BODY_LIMIT — メモリを制限し DoS リスクを下げるため、小さい値（デフォルト 1mb）を維持してください。

• CORS_ALLOWED_ORIGINS — ブラウザアベースのクライアントが必要しない限り、未設定（CORS 無効）のままにしてください。本番では * は避けてください。

• MCP_RATE_LIMIT_WINDOW_MINUTES / MCP_RATE_LIMIT_MAX — 予想されるクライアントのスループットに合わせて調整します。

セッションと書き込みの安全

• SESSION_TIMEOUT_MINUTES — アイドル中のセッションは失効し、監査されます。本番では短く保ちます（デフォルト: 30分）。

• MCP_HUMAN_CONFIRMATION_ENABLED — デフォルトは true です。書き込みの前にユーザーの確認を要求します。完全に自動化された非対話型パイプラインでのこの無効にしてください。

監査ログ

• AUDIT_LOG_FILE_ENABLED — デフォルトは true です。監査ログはすべての書き込み確認とセッションイベント記録します。本番では有効のままにし、AUDIT_LOG_RETENTION_DAYS をコンプライアンス要件に合わせて設定してください。

トラブルシューティング

サーバーまたは接続の問題

• Node.js >= 22.22.3 を使用していること（node --version）と、npm run build がエラーなく完了することを確認してください。

• SERVICE_LAYER_ROOT_URL はホストのみで指定し、/b1s/v2/ パスを含まないことを確認してください（例: https://servicelayer.b1.example.com:50000）。

• サーバーが実行中であることを curl http://localhost:3000/health で確認してください。

• クライアント設定の MC P エンドポイント URL がサーバーアドレスと一致していることを確認し、ツールが表示れない場合は VS Code を再起動してください。

認証と会社コンテキスト

• ダイレクトモード: B1_COMPANY_DB、B1_USERNAME、B1_PASSWORD を確認してください。

• OAuth モード: OAUTH_BASE_URL、OAUTH_CLIENT_ID、OAUTH_CLIENT_SECRET、SLD_ROOT_URL を確認してください。Service Layer が自己署名証明書を使用している場合は、AUTH_ALLOW_SELF_SIGNED=true（開発時対有効）に設定してください。

• VS Code で Failed to verify remote host というエラーが発生する場合は Keycloak の信頼済みホストを確認してください — docs/KEYCLOAK_SETUP.md を参照してください。

• OAuth モードでは、エンティティのツール呼び出しの前に必ず b1_list_companies と b1_select_company を実行してください。会社が選択されていない場合、ツールは SAP B1 データを返しません。

エンティティ、フィールド、書き込みの問題

• b1_find_entities を使用して正しいエンティティ名（大文字と小文字を区別）を確認し、b1_get_entity_schema を使用して、フィルター文字列またはセレクト文字列を構築する前にプロパティ名を検証します。

• 書き込み操作が拒否され、MCP_HUMAN_CONFIRMATION_ENABLED=true の場合、クライアントは MCP Elicitation をサポートする必要があります。GitHub Copilot を使用するか、自動化パイプラインでは MCP_HUMAN_CONFIRMATION_ENABLED=false に設定してください。

デバッグオプションを有効にする

リクエスト処理と Service Layer の呼び出しをトレースするために、詳細ログを有効にします。

APP_LOG_LEVEL=debug
APP_LOG_CONSOLE_ENABLED=true
AUDIT_LOG_CONSOLE_ENABLED=true

設定リファレンス

認証、HTTPS、OAuth、セッション、キャッシュ、ロギングのカテゴリごとにグループ化された環境変数の完全な一覧は、docs/CONFIGURATION_REFERENCE.md を参照してください。

制限事項

• stdio トランスポートはサポートされていません。ストリーマブル HTTP のみがサポートされています。

• OData アクション/ファンクションは、現在の MCP サーバーサンプルではサポートされていません。エンティティに対する標準 CRUD 操作のみが利用可能です。

• Attachment/Picture のアップロード/ダウンロードは、現在の MCP サーバーサンプルではサポートされていません。

• OData バッチ操作は、現在の MCP サーバーサンプルではサポートされていません。各エンティティ操作は個別に実行する必要があります。

• 高度な OData クエリは完全にはサポートされていません。基本的な $filter、$select、$top、$orderby のみが MCP ツールに実装されています。