odsbox-jaquel-mcp 0.3.4

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

Install Requirements

python -m venv .venv
.venv/bin/activate
pip install odsbox-jaquel-mcp[play]

Remark: [play] extra includes optional data analysis and visualization dependencies to allow using the virtual environment to work with the MCP server and do data analysis in Jupyter notebooks ans so on.

Running the Server

.venv/bin/activate
python -m odsbox_jaquel_mcp

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

Development

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 .
pip install -e ".[dev]"

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

MCP Inspector

Make sure npm and uv are installed, then run:

npx @modelcontextprotocol/inspector uvx odsbox-jaquel-mcp

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