odsbox-jaquel-mcp

totonga/odsbox-jaquel-mcp

3.3

If you are the rightful owner of odsbox-jaquel-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

ASAM ODS Jaquel MCP Server is a Model Context Protocol server designed for ASAM ODS with advanced query tools, connection management, and bulk data access capabilities.

Tools
3
Resources
0
Prompts
0

ASAM ODS Jaquel MCP Server

PyPI version Apache 2.0 License Python Status Build Status Stars

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

Overview

  • 🔌 Built-in ODS connection management
  • 🧰 MCP tools: schema inspection, query validation, direct ODS query execution and measurement data analysis
  • 🏗️ Entity hierarchy visualization (AoTest → AoMeasurement)
  • 🚀 Validate, explain and execute 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 help_bulk_api tool
  • 📝 Comprehensive documentation and test suite

Documentation

Quick Start

Installation

Using uvx (Recommended)

The easiest way to use this MCP server is with uvx:

uvx odsbox-jaquel-mcp@latest

This automatically installs and runs the server without managing virtual environments.

Using pipx

For a persistent installation:

pipx install odsbox-jaquel-mcp
odsbox-jaquel-mcp
Traditional pip Installation
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install odsbox-jaquel-mcp[play]

Note: The [play] extra includes optional data analysis and visualization dependencies (pandas, matplotlib, scipy) for working with Jupyter notebooks and data analysis.

Running the Server

The server runs on stdin/stdout and waits for MCP messages from an MCP client:

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

# With pipx (if installed)
odsbox-jaquel-mcp

# With pip in virtual environment
python -m odsbox_jaquel_mcp

Configuration for MCP Clients

Add to your MCP client configuration (e.g., Claude Desktop, VS Code):

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

Or with pipx:

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

Development

Setup

git clone https://github.com/totonga/odsbox-jaquel-mcp.git
cd odsbox-jaquel-mcp
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Common Tasks

# Run server locally
python -m odsbox_jaquel_mcp

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

# Code formatting and linting
black .
isort .
flake8 .

# Build package
python -m build

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

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

Features

Core MCP Tools

Connection Management
  • ods_connect - Establish ODS connection
  • ods_disconnect - Close ODS connection
  • ods_get_connection_info - Get connection status
Schema Inspection
  • schema_get_entity - Get all fields for entity
  • schema_list_entities - List all entities with relationships
  • schema_test_to_measurement_hierarchy - Get ASAM ODS test hierarchy structure
Query Building & Validation
  • query_validate - Check query syntax and structure
  • query_describe - Get plain English explanation
  • query_execute - Execute query on ODS server
Timeseries/Submatrix Data Access
  • data_get_quantities - List measurement quantities for submatrix
  • data_read_submatrix - Read timeseries data from submatrix
  • data_generate_fetcher_script - Generate Python scripts for data fetching
Pattern & Example Library
  • query_generate_skeleton - Generate query skeleton (basic query) for entity
  • query_get_pattern - Get template for common patterns
  • query_list_patterns - List available patterns
  • query_get_operator_docs - Learn about operators

Starting Prompts

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

  • ODS Server Connection - Set up and manage connections
  • Validate a Jaquel Query - Learn query validation
  • Explore Query Patterns - Find common query templates
  • Bulk Data Access - Master the 3-step Bulk API workflow
  • Measurement Analysis - Compare measurements and visualize data

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 'ods_connect' tool first"
}

Solution: Call ods_connect 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
  • 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/attributes
  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

Install in VSCode

{width=300px}

Support

For issues or questions:

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