odsbox-jaquel-mcp 0.3.0

ASAM ODS Jaquel MCP Server - A Model Context Protocol server for creating and validating Jaquel queries

ASAM ODS Jaquel MCP Server

A Model Context Protocol (MCP) server for ASAM ODS with Jaquel query tools, ODS connection management, and bulk data access.

---

Overview

• 🔌 Built-in ODS connection management
• 🧰 29+ MCP tools: schema inspection, query validation, optimization, debugging, and direct ODS query execution
• 🏗️ Entity hierarchy visualization (AoTest → AoMeasurement)
• 🚀 Validate, build, and optimize Jaquel queries for ASAM ODS
• 📦 Bulk timeseries/submatrix data access and script generation
• 📊 Automatic Jupyter notebook generation for measurement comparison
• 📈 Matplotlib visualization code generation
• 📉 Statistical measurement comparison and correlation analysis
• 🔎 Measurement hierarchy exploration and discovery
• 💡 Interactive starting prompts for guided workflows
• 🤖 AI-guided bulk API learning with get_bulk_api_help tool
• 📝 Comprehensive examples, documentation, and test suite

---

Documentation

• Prompts Guide: See PROMPTS.md for starting prompts documentation
• Tool Reference: See TOOLS_GUIDE.md
• Setup: See docs/setup.md for installation and configuration
• Development:
  • Run: python -m odsbox_jaquel_mcp
  • Test: python run_tests.py or pytest tests/
  • Sort imports: python -m isort . (VS Code runs this automatically on save when source.organizeImports is enabled)
  • Lint: black . and flake8 .

Quick Start

Clone

git clone https://github.com/totonga/odsbox-jaquel-mcp.git
cd odsbox-jaquel-mcp

Install Requirements

python -m venv .venv
.venv/bin/activate
pip install .

dev requirements

pip install -e ".[dev]"

Running the Server

python -m odsbox_jaquel_mcp

Starts on stdin/stdout and waits for MCP messages (used with an MCP client).

Testing

Run tests:

python run_tests.py
# or
pytest tests/

Building the Package

python -m build

install whl package

pip install dist/odsbox_jaquel_mcp-0.1.0-py3-none-any.whl

Contributing

Pull requests and issues are welcome! Please:

• Follow PEP8 and use type hints
• Add/maintain tests for new features
• Update documentation as needed

License

This project is licensed under the Apache License 2.0. See LICENSE.

Links

• ASAM ODS
• MCP Protocol
• odsbox

Features

Core Validation Tools

Query Building & Validation

• validate_jaquel_query - Check query syntax and structure
• validate_filter_condition - Validate filter conditions
• build_filter_condition - Construct filter conditions
• explain_jaquel_query - Get plain English explanation

Pattern & Example Library

• get_query_pattern - Get template for common patterns
• list_query_patterns - List available patterns
• generate_query_skeleton - Generate query skeleton for entity
• get_operator_documentation - Learn about operators

Query Optimization

• suggest_optimizations - Get optimization suggestions
• merge_filter_conditions - Combine multiple conditions

Debugging Tools

• debug_query_steps - Break query into logical steps
• suggest_error_fixes - Get suggestions for errors

Schema Inspection (Requires Connection)

• check_entity_schema - Get all fields for entity
• validate_field_exists - Check if field exists
• validate_filter_against_schema - Validate against schema
• list_ods_entities - List all entities with relationships
• get_test_to_measurement_hierarchy - Get ASAM ODS test hierarchy structure

Connection Management (NEW)

• connect_ods_server - Establish ODS connection
• disconnect_ods_server - Close ODS connection
• get_ods_connection_info - Get connection status
• execute_ods_query - Execute query on ODS server
• get_submatrix_measurement_quantities - List measurement quantities for submatrix
• read_submatrix_data - Read timeseries data from submatrix
• generate_submatrix_fetcher_script - Generate Python scripts for data fetching

Starting Prompts

Discover and use the server's capabilities through interactive guided prompts:

• Validate a Jaquel Query - Learn query validation
• Explore Query Patterns - Find common query templates
• ODS Server Connection - Set up and manage connections
• Build Filter Conditions - Master WHERE clause construction
• Bulk Data Access - Master the 3-step Bulk API workflow
• Measurement Analysis - Compare measurements and visualize data
• Optimize & Debug - Improve query performance

See PROMPTS.md for complete details on all starting prompts.

Error Handling

Common Errors and Solutions

Not connected

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

Solution: Call connect_ods_server first

Invalid entity

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

Solution: Use valid entity from available_entities

Invalid field

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

Solution: Use one of the suggested fields

Connection failed

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

Solution: Check URL, server availability, firewall

Troubleshooting

Issue: Tools not discovered

• Ensure mcp>=0.1.0 is installed
• Check ToolsCapability is set in ServerCapabilities
• Restart MCP client

Issue: Schema tools fail

• Ensure ODS server is accessible
• Check username/password
• Verify network connectivity
• Review server logs

Issue: Queries timeout

• Increase request_timeout in connect
• Optimize query with suggest_optimizations
• Reduce $rowlimit
• Check ODS server performance

Performance Tips

1. Use specific filters - Avoid querying all records
2. Limit rows - Always use $rowlimit appropriately
3. Select attributes - Only retrieve needed columns
4. Index awareness - Filter on indexed fields first
5. Connection reuse - Keep connection open when possible
6. Cache schemas - Schema inspection is cached

Security Notes

• Credentials are only held in memory during connection
• Connection is cleaned up on disconnect
• No credentials stored in config files
• Use HTTPS with verify_certificate: true for production

Support

For issues or questions:

1. Check the error message and hints
2. Review the documentation and examples