返回正文目录

工具概述

Foggy MCP 提供一系列数据查询和分析工具，供 AI 助手调用。

工具列表

工具 说明 分类
dataset.list_models 首选模型发现和路由概览 元数据
dataset.describe_model_internal 获取模型详细字段信息 元数据
dataset.query_model 执行结构化数据查询 查询
dataset.compose_script 执行 Compose/跨模型受治理查询 查询
dataset.explain_query 获取查询定义、重编译和证据解释 解释
dataset_nl.query 自然语言数据查询 自然语言
chart.generate 生成数据图表 可视化
dataset.export_with_xchart 使用 JVM 原生 XChart 导出 导出
dataset.export_with_echarts 使用 ECharts 渲染服务导出 导出
dataset.get_metadata 兼容旧版本的元数据入口 兼容

工具分类

元数据工具

用于获取语义层模型和字段的元信息：

dataset.get_metadata 保留用于兼容和迁移，新集成不要再把它作为第一步。

适合在查询前了解数据结构。

查询工具

用于执行结构化数据查询：

需要了解语义层模型和查询语法，提供精确的查询控制。

自然语言工具

用于智能数据查询：

无需了解技术细节，适合普通业务用户。

可视化工具

用于生成图表：

导出工具

用于导出数据：

角色权限

不同端点提供不同的工具集：

权限矩阵

工具 Admin Analyst Business
dataset.list_models ✅ ✅ ❌
dataset.describe_model_internal ✅ ✅ ❌
dataset.query_model ✅ ✅ ❌
dataset.compose_script ✅ ✅ ❌
dataset.explain_query ✅ ✅ ❌
chart.generate ✅ ✅ ❌
dataset.export_with_xchart ✅ ✅ ❌
dataset.export_with_echarts ✅ ✅ ❌
dataset_nl.query ✅ ❌ ✅

端点说明

端点 角色 工具范围
/mcp/admin/rpc 管理员 全部工具
/mcp/analyst/rpc 分析师 元数据 + 查询 + 可视化
/mcp/business/rpc 业务用户 仅自然语言

典型工作流

分析师工作流

1. list_models            → 获取模型路由概览
2. describe_model_internal → 查看模型字段详情
3. query_model / compose_script → 执行单模型或组合查询
4. explain_query          → 查看重新编译证据（可选）
5. chart.generate / export → 生成图表或导出（可选）

业务用户工作流

1. dataset_nl.query      → 自然语言描述需求，一步完成

工具调用示例

MCP 协议调用

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "dataset.list_models",
    "arguments": {}
  }
}

以运行实例的 tools/list 为准；namespace、endpoint 或工具策略不同，实际可见工具可能不同。dataset.get_metadata 仅保留作兼容迁移，不应作为新客户端的首轮调用。

响应格式

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{...}"
      }
    ]
  }
}

错误处理

工具调用可能返回以下错误：

错误码 说明
-32600 无效请求
-32601 方法不存在
-32602 无效参数
-32603 内部错误

错误响应示例

{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32602,
    "message": "缺少必要参数: model"
  }
}

性能建议

  1. 先发现模型：查询前使用 list_models，需要字段详情时再使用 describe_model_internal
  2. 使用分页：大数据量查询时使用 start 和 limit 参数
  3. 添加过滤条件：避免全表扫描，使用 slice 过滤数据
  4. 选择必要字段：只查询需要的 columns，减少数据传输

下一步