{"id":34875132,"url":"https://github.com/totonga/odsbox-jaquel-mcp","last_synced_at":"2026-04-11T17:49:07.114Z","repository":{"id":326427802,"uuid":"1087200550","full_name":"totonga/odsbox-jaquel-mcp","owner":"totonga","description":"MCP server to work with odsbox to access ASAM ODS HTTP API.","archived":false,"fork":false,"pushed_at":"2026-04-04T23:07:30.000Z","size":2604,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-05T01:25:28.470Z","etag":null,"topics":["ai-agents","asam","data-analysis","data-science","mcp","ods"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/totonga.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-31T14:27:37.000Z","updated_at":"2026-04-04T23:04:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/totonga/odsbox-jaquel-mcp","commit_stats":null,"previous_names":["totonga/odsbox-jaquel-mcp"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/totonga/odsbox-jaquel-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totonga%2Fodsbox-jaquel-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totonga%2Fodsbox-jaquel-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totonga%2Fodsbox-jaquel-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totonga%2Fodsbox-jaquel-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/totonga","download_url":"https://codeload.github.com/totonga/odsbox-jaquel-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totonga%2Fodsbox-jaquel-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31689762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T13:07:20.380Z","status":"ssl_error","status_checked_at":"2026-04-11T13:06:47.903Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","asam","data-analysis","data-science","mcp","ods"],"created_at":"2025-12-26T00:48:36.456Z","updated_at":"2026-04-11T17:49:07.107Z","avatar_url":"https://github.com/totonga.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# ASAM ODS Jaquel MCP Server\n\n![PyPI version](https://img.shields.io/pypi/v/odsbox-jaquel-mcp.svg)\n![Apache 2.0 License](https://img.shields.io/badge/license-Apache%202.0-green.svg)\n![Python](https://img.shields.io/badge/python-3.13%2B-blue.svg)\n![Status](https://img.shields.io/badge/status-experimental-orange)\n![Build Status](https://img.shields.io/github/actions/workflow/status/totonga/odsbox-jaquel-mcp/build.yml?branch=main)\n![Stars](https://img.shields.io/github/stars/totonga/odsbox-jaquel-mcp?style=social)\n\n\u003c!-- mcp-name: io.github.totonga/odsbox-jaquel-mcp --\u003e\n\n**A Model Context Protocol (MCP) server for ASAM ODS with odsbox Jaquel query tools, ODS connection management, and measurement data access.**\n\n---\n\n## Overview\n\n- 🔌 Built-in ODS connection management\n- 🧰 MCP tools: schema inspection, query validation, direct ODS query execution and measurement data analysis\n- 🏗️ Entity hierarchy visualization (AoTest → AoMeasurement)\n- 🚀 Validate, explain and execute JAQueL queries for ASAM ODS\n- 📦 Bulk timeseries/submatrix data access and script generation\n- 📊 Automatic Jupyter notebook generation for measurement comparison\n- 📈 Matplotlib visualization code generation\n- 📉 Statistical measurement comparison and correlation analysis\n- 🔎 Measurement hierarchy exploration and discovery\n- 💡 Interactive starting prompts for guided workflows\n- 🤖 AI-guided bulk API learning with `help_bulk_api` tool\n- 📝 Comprehensive documentation and test suite\n\n---\n\n## Documentation\n\n- **Prompts Guide:** See [`PROMPTS.md`](https://github.com/totonga/odsbox-jaquel-mcp/blob/main/PROMPTS.md) for starting prompts documentation\n- **Tool Reference:** See [`TOOLS_GUIDE.md`](https://github.com/totonga/odsbox-jaquel-mcp/blob/main/TOOLS_GUIDE.md)\n- **Changelog:** See [`CHANGELOG.md`](https://github.com/totonga/odsbox-jaquel-mcp/blob/main/CHANGELOG.md)\n\n## Quick Start\n\n### Installation\n\n#### Using uvx (Recommended)\n\nThe easiest way to use this MCP server is with `uvx`:\n\n```bash\nuvx odsbox-jaquel-mcp@latest\n```\n\nThis automatically installs and runs the server without managing virtual environments.\n\n#### Using pipx\n\nFor a persistent installation:\n\n```bash\npipx install odsbox-jaquel-mcp\nodsbox-jaquel-mcp\n```\n\n#### Traditional pip Installation\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\npip install odsbox-jaquel-mcp[play]\n```\n\n\u003e **Note:** The `[play]` extra includes optional data analysis and visualization dependencies (pandas, matplotlib, scipy) for working with Jupyter notebooks and data analysis.\n\n### Running the Server\n\nThe server runs on stdin/stdout and waits for MCP messages from an MCP client:\n\n```bash\n# With uvx (auto-installs and runs)\nuvx odsbox-jaquel-mcp@latest\n\n# With pipx (if installed)\nodsbox-jaquel-mcp\n\n# With pip in virtual environment\npython -m odsbox_jaquel_mcp\n```\n\n### Configuration for MCP Clients\n\nAdd to your MCP client configuration (e.g., Claude Desktop, VS Code):\n\n```json\n{\n  \"mcpServers\": {\n    \"ods-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"odsbox-jaquel-mcp@latest\"]\n    }\n  }\n}\n```\n\nOr with pipx:\n\n```json\n{\n  \"mcpServers\": {\n    \"ods-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"odsbox-jaquel-mcp\"\n    }\n  }\n}\n```\n\n## Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `ODSBOX_STATS_ENABLED` | not set (disabled) | Set to `1`, `true`, or `yes` to enable tool and resource call monitoring. Statistics are persisted to a SQLite database (`odsbox-jaquel-mcp-stats.db`) for cross-session tracking. |\n| `FASTMCP_LOG_LEVEL` | `INFO` | Controls the server-side log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`). With stdio transport all logs go to stderr, which MCP clients may display as warnings. Set to `WARNING` to reduce noise. |\n| `ODSBOX_MCP_MODE` | `basic` | Authentication mode for `ods_connect_using_env`: `basic`, `m2m`, or `oidc` |\n| `ODSBOX_MCP_URL` | not set | ODS server URL for `ods_connect_using_env` |\n| `ODSBOX_MCP_USER` | not set | ODS username (basic mode) |\n| `ODSBOX_MCP_PASSWORD` | not set | ODS password (basic mode; falls back to keyring) |\n| `ODSBOX_MCP_M2M_TOKEN_ENDPOINT` | not set | OAuth2 token endpoint (m2m mode) |\n| `ODSBOX_MCP_M2M_CLIENT_ID` | not set | Client ID (m2m mode) |\n| `ODSBOX_MCP_M2M_CLIENT_SECRET` | not set | Client secret (m2m mode; falls back to keyring) |\n| `ODSBOX_MCP_OIDC_CLIENT_ID` | not set | Client ID (oidc mode) |\n| `ODSBOX_MCP_OIDC_REDIRECT_URI` | not set | Redirect URI (oidc mode, e.g. `http://127.0.0.1:1234`) |\n| `ODSBOX_MCP_VERIFY` | `true` | TLS certificate verification (`true`/`false`) |\n\nSee [TOOLS_GUIDE.md](TOOLS_GUIDE.md#ods_connect_using_env) for the full list of authentication variables and keyring fallback details.\n\n### Usage Monitoring\n\nWhen `ODSBOX_STATS_ENABLED=true` is set, the server records tool call and resource read statistics to a local SQLite database:\n\n- **Location**: `~/.local/share/odsbox-jaquel-mcp/odsbox-jaquel-mcp-stats.db` (Linux/macOS) or `%APPDATA%\\odsbox-jaquel-mcp\\odsbox-jaquel-mcp-stats.db` (Windows), with fallback to the system temp directory.\n- **Tracked per tool**: call count, error count, total execution time (ms), last called timestamp.\n- **Tracked per resource**: read count, error count, total execution time (ms), last read timestamp.\n- **Cross-process safe**: uses SQLite WAL mode, so multiple concurrent MCP sessions can write safely.\n\nYou can query the stats database directly:\n\n```bash\nsqlite3 ~/.local/share/odsbox-jaquel-mcp/odsbox-jaquel-mcp-stats.db \\\n  \"SELECT name, calls, errors, total_ms FROM tool_stats ORDER BY calls DESC\"\n```\n\nExample MCP client configuration with monitoring enabled:\n\n```json\n{\n  \"mcpServers\": {\n    \"ods-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"odsbox-jaquel-mcp@latest\"],\n      \"env\": {\n        \"ODSBOX_STATS_ENABLED\": \"true\",\n        \"FASTMCP_LOG_LEVEL\": \"WARNING\"\n      }\n    }\n  }\n}\n```\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/totonga/odsbox-jaquel-mcp.git\ncd odsbox-jaquel-mcp\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\npip install -e \".[dev]\"\n```\n\n### Common Tasks\n\n```bash\n# Run server locally\npython -m odsbox_jaquel_mcp\n\n# Run tests\npytest tests/\n# or\npython run_tests.py\n\n# Code formatting and linting\nblack .\nisort .\nflake8 .\n\n# Build package\npython -m build\n\n# Test with MCP Inspector\nnpx @modelcontextprotocol/inspector uvx odsbox-jaquel-mcp@latest\n```\n\n## Contributing\n\nPull requests and issues are welcome! Please:\n- Follow PEP8 and use type hints\n- Add/maintain tests for new features\n- Update documentation as needed\n\n## License\n\nThis project is licensed under the Apache License 2.0. See [LICENSE](https://github.com/totonga/odsbox-jaquel-mcp/blob/main/LICENSE).\n\n## Links\n\n- [ASAM ODS](https://www.asam.net/standards/detail/ods/)\n- [MCP Protocol](https://github.com/modelcontextprotocol)\n- [odsbox](https://pypi.org/project/odsbox/)\n\n\n## Features\n\n### Core MCP Tools\n\n#### Connection Management\n- **ods_connect** - Establish ODS connection\n- **ods_connect_using_env** - Establish ODS connection using environment variables\n- **ods_disconnect** - Close ODS connection\n- **ods_get_connection_info** - Get connection status\n\n#### Schema Inspection\n- **schema_get_entity** - Get all fields for entity\n- **schema_list_entities** - List all entities with relationships\n- **schema_test_to_measurement_hierarchy** - Get ASAM ODS test hierarchy structure\n\n#### Query Building \u0026 Validation\n- **query_validate** - Check query syntax and structure\n- **query_describe** - Get plain English explanation\n- **query_execute** - Execute query on ODS server\n\n#### Timeseries/Submatrix Data Access\n- **data_get_quantities** - List measurement quantities for submatrix\n- **data_read_submatrix** - Read timeseries data from submatrix\n- **data_generate_fetcher_script** - Generate Python scripts for data fetching\n\n#### Pattern \u0026 Example Library\n- **query_generate_skeleton** - Generate query skeleton (basic query) for entity\n- **query_get_pattern** - Get template for common patterns\n- **query_list_patterns** - List available patterns\n- **query_get_operator_docs** - Learn about operators\n\n\n### Starting Prompts\nDiscover and use the server's capabilities through **interactive guided prompts**:\n- **ODS Server Connection** - Set up and manage connections\n- **Validate a Jaquel Query** - Learn query validation\n- **Explore Query Patterns** - Find common query templates\n- **Bulk Data Access** - Master the 3-step Bulk API workflow\n- **Measurement Analysis** - Compare measurements and visualize data\n\nSee [`PROMPTS.md`](https://github.com/totonga/odsbox-jaquel-mcp/blob/main/PROMPTS.md) for complete details on all starting prompts.\n\n\n## Error Handling\n\n### Common Errors and Solutions\n\n#### Not connected\n```json\n{\n  \"error\": \"Model not loaded\",\n  \"hint\": \"Connect to ODS server using 'ods_connect' tool first\"\n}\n```\nSolution: Call ods_connect first\n\n#### Invalid entity\n```json\n{\n  \"error\": \"Entity not found: InvalidEntity\",\n  \"available_entities\": [\"AoUnit\", \"AoMeasurement\", ...]\n}\n```\nSolution: Use valid entity from available_entities\n\n#### Invalid field\n```json\n{\n  \"valid\": false,\n  \"issues\": [\"Field 'invalid_field' not found\"],\n  \"suggestions\": [\"id\", \"name\", \"description\"]\n}\n```\nSolution: Use one of the suggested fields\n\n#### Connection failed\n```json\n{\n  \"success\": false,\n  \"error\": \"Connection refused\",\n  \"error_type\": \"ConnectionError\"\n}\n```\nSolution: Check URL, server availability, firewall\n\n## Troubleshooting\n\n### Issue: Tools not discovered\n- Ensure mcp\u003e=0.1.0 is installed\n- Check ToolsCapability is set in ServerCapabilities\n- Restart MCP client\n\n### Issue: Schema tools fail\n- Ensure ODS server is accessible\n- Check username/password\n- Verify network connectivity\n- Review server logs\n\n### Issue: Queries timeout\n- Increase request_timeout in connect\n- Reduce $rowlimit\n- Check ODS server performance\n\n## Performance Tips\n\n1. **Use specific filters** - Avoid querying all records\n2. **Limit rows** - Always use `$rowlimit` appropriately\n3. **Select attributes** - Only retrieve needed columns/attributes\n4. **Index awareness** - Filter on indexed fields first\n5. **Connection reuse** - Keep connection open when possible\n6. **Cache schemas** - Schema inspection is cached\n\n## Security Notes\n\n- Credentials are only held in memory during connection\n- Connection is cleaned up on disconnect\n- No credentials stored in config files\n- Use HTTPS with `verify_certificate: true` for production\n\n## Install in VSCode\n\n![install in VSCode](https://github.com/totonga/odsbox-jaquel-mcp/blob/main/docs/install_in_vscode.gif){width=300px}\n\nTry with example server configuration using all three authentication modes via different env prefixes:\n\n```json\n{\n\t\"servers\": {\n\t\t\"ods\": {\n\t\t\t\"type\": \"stdio\",\n\t\t\t\"command\": \"uvx\",\n\t\t\t\"args\": [\n\t\t\t\t\"odsbox-jaquel-mcp@latest\"\n\t\t\t],\n\t\t\t\"env\": {\n\t\t\t\t\"ODSBOX_MCP_URL\": \"https://docker.peak-solution.de:10032/api\",\n\t\t\t\t\"ODSBOX_MCP_USER\": \"Demo\",\n\t\t\t\t\"ODSBOX_MCP_PASSWORD\": \"mdm\",\n\t\t\t\t\"ODSBOX_MCP2_MODE\": \"m2m\",\n\t\t\t\t\"ODSBOX_MCP2_URL\": \"https://ods.example.com/api\",\n\t\t\t\t\"ODSBOX_MCP2_M2M_TOKEN_ENDPOINT\": \"https://auth.example.com/realms/myrealm/protocol/openid-connect/token\",\n\t\t\t\t\"ODSBOX_MCP2_M2M_CLIENT_ID\": \"my-service-client\",\n\t\t\t\t\"ODSBOX_MCP3_MODE\": \"oidc\",\n\t\t\t\t\"ODSBOX_MCP3_URL\": \"https://ods.example.com/api\",\n\t\t\t\t\"ODSBOX_MCP3_OIDC_CLIENT_ID\": \"my-oidc-client\",\n\t\t\t\t\"ODSBOX_MCP3_OIDC_REDIRECT_URI\": \"http://127.0.0.1:1234\"\n\t\t\t}\n\t\t}\n\t},\n\t\"inputs\": []\n}\n```\n\n## Support\n\nFor issues or questions:\n1. Check the error message and hints\n2. Review the documentation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftotonga%2Fodsbox-jaquel-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftotonga%2Fodsbox-jaquel-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftotonga%2Fodsbox-jaquel-mcp/lists"}