Gmail + SAP MCP アシスタント

Gmail の読み取り・管理、SAP の Business Partner / Sales / Billing / Product データの参照、そして受信トレイ（および SAP レコード）に関する自然言語での質問を AI アシスタントに投げられる Streamlit アプリケーションです。これらすべてを単一の Model Context Protocol（MCP）サーバー経由で行います。

                              Streamlit UI (app.py)
                                       │
                       ┌───────────────┴───────────────┐
                       ▼                               ▼
           Gmail / SAP / Admin tabs                  Ai tab
           (direct button click)              EmailAssistant (ai_agent.py)
                       │                       → Mistral LLM decides which
                       │                         tool(s) to call, if any
                       │                                │
                       └───────────────┬────────────────┘
                                       ▼
                     MCPClient (mcp_client.py) — one persistent
                     background event loop for every call, either path
                                        │
                                        │  Streamable HTTP transport
                                        ▼
                        FastMCP server (server.py) — dispatches
                              the tool call by name
                                        │
                       ┌────────────────┴────────────────┐
                       ▼                                 ▼
                GmailService                        SAPService
              (gmail_service.py)                  (sap_service.py)
                       │                                  │
                       ▼                                  ▼
                  Gmail API                          SAP OData API
                (OAuth credentials)                  (API key, sandbox)

UI は Gmail や SAP に直接通信しません。ボタンクリックであれ、AI アシスタントが判断したアクションであれ、すべての操作は同じ MCPClient → FastMCP サーバー → サービス層という経路を通ります。これにより、アプリと 2 つの外部システムの間に、単一の監査可能な境界が維持されます。

リクエストの流れ

リクエストがシステムに入る経路は 2 つあり、どちらも MCPClient に収束します。

1. UI からの直接操作（Gmail / SAP / Admin タブ）

1. ボタンをクリックします（例: Gmail タブの「検索」）。app.py が共有の MCPClient インスタンスのメソッドを直接呼び出します（例: mcp_client.gmail_search_messages(query, max_results)）。

2. MCPClient はそのコルーチンを専用のバックグラウンドイベントループにスケジュールし、完了するまでブロックします（mcp_client.py の _loop.run(...)）。これにより、Streamlit の「操作ごとに再実行」モデル全体で MCP セッションの安全性が保たれます。

3. FastMCP サーバー（server.py）が Streamable HTTP 経由でツール呼び出しを受信し、対応する関数（例: gmail_search_messages()）にディスパッチします。

4. その関数が GmailService（gmail_service.py）または SAPService（sap_service.py）を呼び出し、実際のネットワーク呼び出し（Gmail API（OAuth）または SAP OData API（API キー））を実行して、パース済みのプレーンな dict 結果を返します。

5. 結果は逆方向に伝搬します: MCP サーバー → MCPClient._unwrap() → app.py。app.py はそれを st.session_state に保存してレンダリングします。

どの層でエラーが発生しても（MCPToolError、MCPConnectionError、または予期しないエラー）、app.py の run_action() が一元的に捕捉し、st.error として表示するため、失敗した呼び出しで UI がクラッシュすることはありません。

2. AI アシスタントへの質問（Ai タブ）

これは同じパイプラインの前に判断ループが付いたものです:

1. 質問（チャット履歴を含む）は ai_agent.py の EmailAssistant.ask() に送られます。prompts.py でシステムプロンプトを構築し（今日・明日の日付を注入）、TOOLS スキーマとともに Mistral に送信します。

2. Mistral はツールが必要かどうかを判断します。必要な場合、ai_agent.py は手動タブと同じ MCPClient インスタンスを通じて呼び出しを実行します（EmailAssistant は Gmail/SAP に直接通信しません）。そして JSON 結果を会話にフィードバックします。

3. ステップ 1〜2 を繰り返し（検索 → 特定メッセージの読み取り → さらに検索、という流れ）、最大 MISTRAL_MAX_STEPS 回（デフォルト 12 回）まで実行します。

4. Mistral が十分な情報を得たらツール呼び出しを停止し、最終的な自然言語の回答を返します。app.py がそれをチャットにレンダリングします。デバッグ用に、折りたたみ可能な「使用したツール呼び出し」エクスパンダーで完全なツール呼び出しトレースを確認できます。

エージェントのツールリストは意図的に狭く（Gmail/SAP の読み取り専用ルックアップのみ）、何を質問しても送信・削除・変更はできません。それらの操作ができるのは Gmail タブの手動フローのみで、それぞれ破壊的操作の実行前に明示的な確認ステップが必要です。

3. アプリ起動時（プロセスごとに 1 回）

app.py の get_mcp_client() は @st.cache_resource でラップされているため、正確に 1 回だけ実行されます: MCPClient を作成し、.connect() を呼び出します。これによりバックグラウンドスレッドとイベントループが起動し、FastMCP サーバーへの Streamable HTTP セッションが開かれます。そのセッションは Streamlit プロセスの存続期間中維持され、再実行のたびに再作成されることはありません。

機能

Gmail（「Gmail」タブ経由）

• Gmail のネイティブ検索構文を使用したメッセージの一覧表示・検索

• メッセージ全体の読み取り（本文、ヘッダー、添付ファイル）

• メール送信、下書き作成、メッセージのゴミ箱への移動（それぞれ UI での明示的な確認ステップが必要）

• メッセージの既読/未読切り替え、ラベルの一覧表示、添付ファイルのバイトデータ取得

SAP（「SAP」タブ経由）

• SAP OData サンドボックスへの設定・接続確認

• Business Partner の一覧表示・検索、単一パートナーの表示

• 登録済みメールアドレスの一覧表示

• （デフォルトでは読み取り専用 — 下記の SAP 書き込み を参照）

AI アシスタント（「Ai」タブ経由）

Mistral を搭載したエージェント（ai_agent.py / EmailAssistant）が、以下のような自然言語の質問に回答します:

• 「今日の重要なメールを要約して」

• 「添付ファイル付きのメールを探して」

• 「明日、面接の予定はありますか？」

• 「過去 7 日間のメールを要約して」

エージェントは意図的に読み取り専用です: gmail_search_messages、gmail_read_message、gmail_list_messages（および prompts.py に記載されている読み取り専用の SAP ルックアップ）のみを呼び出せます。送信・返信・削除のツールは一切なく、システムプロンプトでも、そのように尋ねられた場合はその旨を伝えるよう明示的に指示されています。回答内のすべての事実は実際のツール結果に基づく必要があり、捏造は一切許されません。

管理タブ

MCP 接続のライブステータス、サーバーが現在公開しているツールの一覧、最後に取得した Gmail/SAP 設定を表示します。サーバーが到達可能で正しく設定されていることを確認するのに役立ちます。

プロジェクト構成

前提条件

• Python 3.10 以上

• Gmail API が有効で、OAuth デスクトップアプリクライアント（credentials.json）を持つ Google Cloud プロジェクト

• SAP タブ/ツールを使用する場合は、API キー付きの SAP OData サンドボックス（例: SAP Business Accelerator Hub）へのアクセス

• AI アシスタントタブを使用する場合は、Mistral API キー

セットアップ

1. 依存関係のインストール

   python -m venv .venv
   source .venv/bin/activate   # Windows: .venv\Scripts\activate
   pip install -r requirements.txt

2. Gmail OAuth 認証情報

   Google Cloud Console から OAuth クライアントの credentials.json をダウンロードし、credentials/credentials.json に配置します（または GMAIL_CREDENTIALS_FILE で別のパスを指定）。サーバーが初めて Gmail ツールを呼び出すと、ブラウザウィンドウが開いて認証を求められます。生成されたトークンは credentials/token.json に書き込まれます。

3. 環境変数

   プロジェクトルートに .env ファイルを作成します:

   # --- MCP server ---
   MCP_SERVER_HOST=127.0.0.1
   MCP_SERVER_PORT=8000
   LOG_LEVEL=INFO
   
   # --- MCP client (Streamlit side) ---
   MCP_SERVER_URL=http://127.0.0.1:8000/mcp
   MCP_CONNECT_TIMEOUT_SECONDS=20
   MCP_CALL_TIMEOUT_SECONDS=60
   
   # --- Gmail ---
   GMAIL_CREDENTIALS_FILE=credentials/credentials.json
   GMAIL_TOKEN_FILE=credentials/token.json
   
   # --- SAP ---
   SAP_MODE=sandbox
   SAP_BASE_URL=https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_BUSINESS_PARTNER
   SAP_API_KEY=your-sap-api-key
   SAP_VERIFY_SSL=true
   SAP_WRITE_ENABLED=false
   SAP_TIMEOUT_SECONDS=30
   
   # --- AI Assistant ---
   MISTRAL_API_KEY=your-mistral-api-key
   MISTRAL_MODEL=mistral-large-latest
   MISTRAL_MAX_STEPS=12

   認証情報/API キー自体を除き、すべての変数には適切なデフォルト値があります。正確なフォールバック値は各 *_service.py / *_client.py ファイルの先頭を参照してください。

4. MCP サーバーの起動

   python server.py

   これにより、FastMCP サーバーが Streamable HTTP トランスポートを使用して MCP_SERVER_HOST:MCP_SERVER_PORT で起動します。

5. Streamlit アプリの起動（別のターミナルで）

   streamlit run app.py

   Streamlit が表示する URL（通常は http://localhost:8501）を開きます。

SAP 書き込み

SAPService はすでに SAP の OData 書き込みエンドポイントに対する create_business_partner と update_business_partner を実装していますが、対応する MCP ツールは server.py でコメントアウトされており、呼び出しは sap_service.py の SAP_WRITE_ENABLED=true でハードゲートされています。有効にするには:

1. .env で SAP_WRITE_ENABLED=true を設定します。

2. server.py で sap_create_business_partner / sap_update_business_partner ツール定義のコメントを解除します。

3. MCP サーバーを再起動します。

それまでは、フラグに関係なくすべての SAP アクセスは読み取り専用です。

安全に関する注意事項

• AI アシスタントは Gmail の読み取りのみ可能です。送信/削除/変更ツールはなく、ai_agent.py の TOOLS リストと prompts.py のシステムプロンプトの両方で強制されています。

• Gmail タブでのメール送信、下書き作成、メッセージの削除/ゴミ箱移動は、それぞれ破壊的操作の実行前に明示的な確認チェックボックスまたは「検索 → 開く → 確認」フローが必要です。

• SAP 書き込みはデフォルトでオフ（SAP_WRITE_ENABLED=false）で、実行するツールはオプトインしない限り MCP サーバーに登録すらされません。

トラブルシューティング

• 「MCP サーバーに接続できません」 — server.py が実行中であること、.env の MCP_SERVER_URL がそのホスト/ポートと一致していることを確認してください。

• 古い/無効なトークンに関する Gmail OAuth エラー — GMAIL_TOKEN_FILE のファイルを削除して再試行してください。アプリが OAuth フローを再実行します。

• SAP リクエストが HTTP エラーで失敗する — 一部の SAP サンドボックステナントでは、すべての OData サービス（例: API_SALES_ORDER_SRV、API_BILLING_DOCUMENT_SRV）がデフォルトで有効になっていません。エラーボディを API カタログと照合してください。

• 「AI アシスタントを利用できません」 — .env に MISTRAL_API_KEY がないか空です。