Dmap Ai Mcp Server

DMAP-AI MCP サーバー

このサービスは、既存の FastMCP ツールを /mcp/ で、非公開のオーナー向け分析 API を /admin/analytics/ で公開します。分析では、分析対象となるツール呼び出しごとに、最終状態を示す SQLite の行を 1 件記録します。{ "ok": false } を返した場合と例外が発生した場合は失敗として扱います。プロトコルの探索、ヘルスチェックの通信、および debug_ping はカウントしません。

ローカル開発

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
Copy-Item .env.example .env
python -m pytest -q
$env:DMAP_ANALYTICS_MARK_TEST_TRAFFIC='true'
uvicorn server:app --host 127.0.0.1 --port 8001

SQLite は自動的に初期化されます。WAL、外部キー、5 秒のビジータイムアウト、短いトランザクション、パラメーター化 SQL、および時刻、ツール、ステータス、識別子、マッピング済み位置情報用のインデックスを使用します。タイムスタンプは UTC です。ダッシュボードのクエリでは既定で America/Chicago を使用しますが、インストール済みの IANA タイムゾーンであればいずれも指定できます。

設定

• DMAP_ANALYTICS_DB_PATH：SQLite のパス。ローカルでの既定値は data/analytics.sqlite3 です。本番環境では、Git チェックアウトの外部に永続化ディレクトリを使用してください。
• DMAP_ANALYTICS_HASH_SECRET：サーバーだけが保持する、長くランダムな HMAC シークレットです。変更すると識別子の継続性が失われます。識別子を作り出すためには使用されません。
• DMAP_ANALYTICS_ADMIN_SUBS：Auth0 の sub の許可リスト。カンマ区切りで指定します。フロントエンドのコードで公開しないでください。
• DMAP_ANALYTICS_MARK_TEST_TRAFFIC：新たに記録するイベントをテストトラフィックとしてマークします。
• DMAP_ANALYTICS_ALLOWED_ORIGINS：本番環境および開発環境で許可する CORS オリジンを、カンマ区切りで正確に指定します。
• AUTH0_DOMAIN：スキームを含まない Auth0 テナントのドメインです。
• AUTH0_AUDIENCE：想定する API オーディエンスです。
• DMAP_API_BASE：既存の DMAP 分析バックエンドのベース URL です。

すべての分析ルートでは、JWKS、発行者、オーディエンス、有効期限を検証して、Auth0 の RS256 トークンを検証します。認可には、permissions または scope 内の read:dmap-analytics、あるいはサーバーのみが保持する許可リスト内の完全一致するサブジェクトが必要です。非公開のレスポンスには Cache-Control: no-store が設定されます。

現在の MCP サービスはステートレスで、呼び出し元を認証しないため、サーバーが発行した安定したセッション識別子も、検証済みのエンドユーザーのサブジェクトもありません。そのため、session_hash と user_hash は null のままで、ダッシュボードでは Estimated Sessions、Authenticated Users、Active Sessions が Unavailable と表示されます。IP アドレスやユーザーエージェントから ID を導き出すことはありません。

履歴データのインポート

インポーターは、timestamp,service,priority,pid,message 列を持つジャーナル CSV を受け付けます。繰り返し現れるヘッダーと探索トラフィックは無視し、信頼できる根拠によって対応が確認できる既知のツール名のみをインポートします。重複排除の前に api_key のクエリ値を秘匿化し、メッセージも URL も保存しません。

python scripts\import_journal_csv.py C:\path\to\dmap_ai_mcp_logs_30days.csv --dry-run
python scripts\import_journal_csv.py C:\path\to\dmap_ai_mcp_logs_30days.csv
python scripts\import_journal_csv.py C:\path\to\test_logs.csv --mark-test

SHA-256 のソースイベントフィンガープリントにより、履歴データを繰り返しインポートしても冪等性が保たれます。履歴ログからユーザー数やセッション数が生成されることはありません。

本番環境へのデプロイ概要

バックアップと承認を得たうえで、サーバーに既存のデプロイ方法を使用してください。DMAP_ANALYTICS_DB_PATH に /var/lib/dmap-ai-mcp/analytics.sqlite3 のような永続パスを設定し、systemd サービスユーザーが所有するディレクトリを作成して、requirements.txt をインストールした後、dmap-ai-mcp を再起動します。シークレット値をコマンドラインや Git に記載しないでください。既存の保護された環境ファイルに設定してください。

アップグレード前に、現在のデプロイで必要な場合は書き込みを短時間停止し、SQLite のオンラインバックアップコマンドでバックアップを取得してください。

sqlite3 /var/lib/dmap-ai-mcp/analytics.sqlite3 ".backup '/var/backups/dmap-ai-mcp/analytics-$(date -u +%Y%m%dT%H%M%SZ).sqlite3'"

ロールバックするには、既存のサービス手順に従って以前の Git コミットまたは仮想環境を復元し、環境ファイルのバックアップを復元してから、サービスを再起動します。スキーマは追加型です。アプリケーションコードをロールバックする場合も、データベースのバックアップは保持してください。

集計トレンドを比較するため、推奨するデータ保持期間は 13 か月です。実際のデータ量とポリシーに照らして見直してください。自動削除は有効になっていません。意図的に削除する場合は、事前にデータベースをバックアップし、UTC の期間を区切って削除してください。