ASAM ODS odsbox jaquel MCP Server

ASAM ODS Jaquel MCP サーバー

odsbox Jaquel クエリツール、ODS 接続管理、測定データへのアクセスを提供する、ASAM ODS 用の Model Context Protocol（MCP）サーバーです。

---

概要

• 🔌 ODS 接続管理機能を標準搭載
• 🧰 MCP ツール：スキーマの確認、クエリの検証、ODS クエリの直接実行、測定データの分析
• 🏗️ エンティティ階層の可視化（AoTest → AoMeasurement）
• 🚀 ASAM ODS 用 JAQueL クエリの検証、説明、実行
• 📦 時系列／サブマトリックスデータの一括アクセスとスクリプト生成
• 📊 測定値の比較用 Jupyter ノートブックを自動生成
• 📈 Matplotlib の可視化コードを生成
• 📉 測定値の統計的比較と相関分析
• 🔎 測定階層の探索と検出
• 💡 ワークフローをガイドする対話型の開始プロンプト
• 🤖 help_bulk_api ツールによる、AI がガイドする一括 API の学習
• 📝 包括的なドキュメントとテストスイート

---

ドキュメント

• プロンプトガイド： 開始プロンプトの説明については、PROMPTS.md を参照してください
• ツールリファレンス： TOOLS_GUIDE.md を参照してください
• 変更履歴： CHANGELOG.md を参照してください

クイックスタート

インストール

uvx を使用する（推奨）

この MCP サーバーを使用する最も簡単な方法は、uvx を使うことです。

uvx odsbox-jaquel-mcp@latest

これにより、仮想環境を管理することなく、サーバーが自動的にインストールされて実行されます。

uv tool を使用する（永続インストール）

永続的にインストールするには、次のようにします。

uv tool install odsbox-jaquel-mcp
odsbox-jaquel-mcp

プロジェクトの仮想環境を使用する

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install odsbox-jaquel-mcp[play]

注： [play] エクストラには、Jupyter ノートブックやデータ分析で使用する、オプションのデータ分析および可視化用依存関係（pandas、matplotlib、scipy）が含まれています。

サーバーの実行

サーバーは stdin/stdout で動作し、MCP クライアントからの MCP メッセージを待ち受けます。

# With uvx (auto-installs and runs)
uvx odsbox-jaquel-mcp@latest

# With uv tool (if installed)
odsbox-jaquel-mcp

# With project environment
uv run python -m odsbox_jaquel_mcp

MCP クライアントの設定

MCP クライアントの設定に追加してください（例：Claude Desktop、VS Code）。

{
  "mcpServers": {
    "ods-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["odsbox-jaquel-mcp@latest"]
    }
  }
}

または、uv tool を使う場合：

{
  "mcpServers": {
    "ods-mcp": {
      "type": "stdio",
      "command": "odsbox-jaquel-mcp"
    }
  }
}

環境変数

変数	デフォルト	説明
ODSBOX_STATS_ENABLED	未設定（無効）	ツールとリソースの呼び出し監視を有効にするには、1、true、または yes を設定します。統計情報は、セッションをまたいだ追跡のために SQLite データベース（odsbox-jaquel-mcp-stats.db）に保存されます。
FASTMCP_LOG_LEVEL	INFO	サーバー側のログレベル（DEBUG、INFO、WARNING、ERROR、CRITICAL）を制御します。stdio トランスポートでは、すべてのログが stderr に出力され、MCP クライアントに警告として表示される場合があります。ノイズを減らすには、WARNING を設定してください。
ODSBOX_MCP_MODE	basic	ods_connect_using_env の認証モード：basic、m2m、または oidc
ODSBOX_MCP_URL	未設定	ods_connect_using_env 用の ODS サーバー URL
ODSBOX_MCP_USER	未設定	ODS ユーザー名（basic モード）
ODSBOX_MCP_PASSWORD	未設定	ODS パスワード（basic モード。keyring にフォールバックし、最初に ods-pilot を確認します）
ODSBOX_MCP_M2M_TOKEN_ENDPOINT	未設定	OAuth2 トークンエンドポイント（m2m モード）
ODSBOX_MCP_M2M_CLIENT_ID	未設定	クライアント ID（m2m モード）
ODSBOX_MCP_M2M_CLIENT_SECRET	未設定	クライアントシークレット（m2m モード。keyring にフォールバックし、最初に ods-pilot を確認します）
ODSBOX_MCP_OIDC_CLIENT_ID	未設定	クライアント ID（oidc モード）
ODSBOX_MCP_OIDC_REDIRECT_URI	未設定	リダイレクト URI（oidc モード。例：http://127.0.0.1:1234）
ODSBOX_MCP_VERIFY	true	TLS 証明書の検証（true／false）

認証変数の全リストと keyring へのフォールバックの詳細については、TOOLS_GUIDE.md を参照してください。

シークレットは、まず ods-pilot keyring サービスで <service>::<username> レコードを使って検索され、見つからない場合は従来の直接サービス検索が行われます。

使用状況の監視

ODSBOX_STATS_ENABLED=true が設定されている場合、サーバーはツール呼び出しとリソース読み取りの統計情報をローカルの SQLite データベースに記録します。

• 保存場所：~/.local/share/odsbox-jaquel-mcp/odsbox-jaquel-mcp-stats.db（Linux／macOS）または %APPDATA%\odsbox-jaquel-mcp\odsbox-jaquel-mcp-stats.db（Windows）。利用できない場合は、システムの一時ディレクトリに保存されます。
• ツールごとの追跡項目：呼び出し回数、エラー回数、合計実行時間（ms）、最終呼び出し日時。
• リソースごとの追跡項目：読み取り回数、エラー回数、合計実行時間（ms）、最終読み取り日時。
• プロセス間で安全：SQLite の WAL モードを使用するため、複数の MCP セッションから同時に安全に書き込めます。

統計データベースに直接クエリを実行できます。

sqlite3 ~/.local/share/odsbox-jaquel-mcp/odsbox-jaquel-mcp-stats.db \
  "SELECT name, calls, errors, total_ms FROM tool_stats ORDER BY calls DESC"

監視を有効にした MCP クライアント設定の例：

{
  "mcpServers": {
    "ods-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["odsbox-jaquel-mcp@latest"],
      "env": {
        "ODSBOX_STATS_ENABLED": "true",
        "FASTMCP_LOG_LEVEL": "WARNING"
      }
    }
  }
}

開発

セットアップ

git clone https://github.com/totonga/odsbox-jaquel-mcp.git
cd odsbox-jaquel-mcp
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync --all-extras --group dev

よく使うタスク

# Run server locally
uv run python -m odsbox_jaquel_mcp

# Run tests
uv run pytest tests/
# or
python run_tests.py

# Code formatting and linting
ruff check .
ruff format .

# Build package
uv build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector uvx odsbox-jaquel-mcp@latest

コントリビューション

プルリクエストやイシューを歓迎します。以下に従ってください。

• PEP8 に準拠し、型ヒントを使用する
• 新機能のテストを追加・維持する
• 必要に応じてドキュメントを更新する

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。LICENSE を参照してください。

リンク

• ASAM ODS
• MCP プロトコル
• odsbox

機能

MCP の主要ツール

接続管理

• ods_connect - ODS 接続を確立します
• ods_connect_using_env - 環境変数を使用して ODS 接続を確立します
• ods_disconnect - ODS 接続を閉じます
• ods_get_connection_info - 接続状態を取得します

スキーマの調査

• schema_get_entity - エンティティのすべてのフィールドを取得します
• schema_list_entities - 関連情報を含むすべてのエンティティを一覧表示します
• schema_test_to_measurement_hierarchy - ASAM ODS のテスト階層構造を取得します

クエリの作成と検証

• query_validate - クエリの構文と構造を確認します
• query_describe - 平易な英語で説明を取得します
• query_execute - ODS サーバーでクエリを実行します

時系列／部分行列データへのアクセス

• data_get_quantities - 部分行列の測定量を一覧表示します
• data_read_submatrix - 部分行列から時系列データを読み取ります
• data_generate_fetcher_script - データ取得用の Python スクリプトを生成します

パターンとサンプルのライブラリ

• query_generate_skeleton - エンティティのクエリの骨組み（基本クエリ）を生成します
• query_get_pattern - 一般的なパターンのテンプレートを取得します
• query_list_patterns - 利用可能なパターンを一覧表示します
• query_get_operator_docs - 演算子について確認します

開始時のプロンプト

対話形式のガイド付きプロンプトを通じて、サーバーの機能を確認して利用できます：

• ODS Server Connection - 接続を設定および管理します
• Validate a Jaquel Query - クエリの検証方法を確認します
• Explore Query Patterns - 一般的なクエリテンプレートを探します
• Bulk Data Access - Bulk API の 3 ステップのワークフローを習得します
• Measurement Analysis - 測定値を比較し、データを可視化します

開始時のプロンプトの詳細については、PROMPTS.mdを参照してください。

エラー処理

よくあるエラーと解決方法

未接続

{
  "error": "Model not loaded",
  "hint": "Connect to ODS server using 'ods_connect' tool first"
}

解決方法：まず ods_connect を呼び出します

エンティティが無効

{
  "error": "Entity not found: InvalidEntity",
  "available_entities": ["AoUnit", "AoMeasurement", ...]
}

解決方法：available_entities にある有効なエンティティを使用します

フィールドが無効

{
  "valid": false,
  "issues": ["Field 'invalid_field' not found"],
  "suggestions": ["id", "name", "description"]
}

解決方法：提案されたフィールドのいずれかを使用します

接続に失敗

{
  "success": false,
  "error": "Connection refused",
  "error_type": "ConnectionError"
}

解決方法：URL、サーバーの可用性、ファイアウォールを確認します

トラブルシューティング

問題：ツールが検出されない

• mcp>=0.1.0 がインストールされていることを確認します
• ServerCapabilities で ToolsCapability が設定されていることを確認します
• MCP クライアントを再起動します

問題：スキーマツールが失敗する

• ODS サーバーにアクセスできることを確認します
• ユーザー名／パスワードを確認します
• ネットワーク接続を確認します
• サーバーログを確認します

問題：クエリがタイムアウトする

• connect の request_timeout を増やします
• $rowlimit を小さくします
• ODS サーバーのパフォーマンスを確認します

パフォーマンスのヒント

1. 具体的なフィルターを使用する - すべてのレコードをクエリしないようにします
2. 行数を制限する - 常に $rowlimit を適切に使用します
3. 属性を選択する - 必要な列／属性のみを取得します
4. インデックスを意識する - まずインデックス付きフィールドでフィルターします
5. 接続を再利用する - 可能な限り接続を開いたままにします
6. スキーマをキャッシュする - スキーマの検査結果はキャッシュされます

セキュリティに関する注意

• 認証情報は接続中のみメモリ上に保持されます
• 切断時に接続はクリーンアップされます
• 設定ファイルに認証情報は保存されません
• 本番環境では verify_certificate: true を指定して HTTPS を使用します

VSCode へのインストール

{width=300px}

異なる env プレフィックスを使い、3 つすべての認証モードを利用するサーバー設定例を試してください：

{
	"servers": {
		"ods": {
			"type": "stdio",
			"command": "uvx",
			"args": [
				"odsbox-jaquel-mcp@latest"
			],
			"env": {
				"ODSBOX_MCP_URL": "https://docker.peak-solution.de:10032/api",
				"ODSBOX_MCP_USER": "Demo",
				"ODSBOX_MCP_PASSWORD": "mdm",
				"ODSBOX_MCP2_MODE": "m2m",
				"ODSBOX_MCP2_URL": "https://ods.example.com/api",
				"ODSBOX_MCP2_M2M_TOKEN_ENDPOINT": "https://auth.example.com/realms/myrealm/protocol/openid-connect/token",
				"ODSBOX_MCP2_M2M_CLIENT_ID": "my-service-client",
				"ODSBOX_MCP3_MODE": "oidc",
				"ODSBOX_MCP3_URL": "https://ods.example.com/api",
				"ODSBOX_MCP3_OIDC_CLIENT_ID": "my-oidc-client",
				"ODSBOX_MCP3_OIDC_REDIRECT_URI": "http://127.0.0.1:1234"
			}
		}
	},
	"inputs": []
}

サポート

問題や質問がある場合：

1. エラーメッセージとヒントを確認します
2. ドキュメントを確認します