ASAM ODS odsbox jaquel MCP Server

ASAM ODS Jaquel MCP 服务

一个适用于 ASAM ODS 的模型上下文协议（MCP）服务，提供 odsbox Jaquel 查询工具、ODS 连接管理和测量数据访问。

---

概述

• 🔌 内置 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] 附加项包含可选的数据分析和可视化依赖项（pandas、matplotlib、scipy），用于处理 Jupyter 笔记本和数据分析。

运行服务

服务通过 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 模式；若未设置，则回退到密钥环，优先检查 ods-pilot）
ODSBOX_MCP_M2M_TOKEN_ENDPOINT	未设置	OAuth2 令牌端点（m2m 模式）
ODSBOX_MCP_M2M_CLIENT_ID	未设置	客户端 ID（m2m 模式）
ODSBOX_MCP_M2M_CLIENT_SECRET	未设置	客户端密钥（m2m 模式；若未设置，则回退到密钥环，优先检查 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）

完整的身份验证变量列表和密钥环回退详情，请参阅 TOOLS_GUIDE.md。

密钥会先使用 <service>::<username> 记录在 ods-pilot 密钥环服务中查找；如果未找到，则回退到旧版直接服务查找。

使用监控

设置 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 - 掌握 3 步 Bulk API 工作流
• 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. 缓存架构 - 架构检查会被缓存

安全说明

• 凭据仅在连接期间保存在内存中
• 断开连接时会清理连接
• 配置文件中不会存储凭据
• 在生产环境中使用 HTTPS，并设置 verify_certificate: true

在 VSCode 中安装

{width=300px}

尝试使用示例服务配置，通过不同的环境变量前缀配置全部三种身份验证模式：

{
	"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. 查阅文档