返回正文目录

扩展工具

Foggy MCP 支持通过扩展模块添加额外工具。这些工具需要额外的依赖和配置才能启用。

Data Viewer

Data Viewer 是一个数据浏览器扩展，提供 dataset.open_in_viewer 工具，用于生成可分享的浏览器链接，支持交互式浏览大数据集。

启用条件

Data Viewer 需要以下依赖：

  1. MongoDB - 用于缓存查询上下文
  2. foggy-data-viewer 模块 - 包含在 foggy-mcp-launcher 中

配置

确保 MongoDB 已启动并配置：

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/foggy_test
      auto-index-creation: true

# 可选：禁用 Data Viewer
foggy:
  data-viewer:
    enabled: true  # 默认 true
    base-url: http://localhost:7108/data-viewer

启动 MongoDB（使用 demo docker）：

cd foggy-dataset-demo/docker
docker-compose up -d mongo

验证

启动服务后，调用 tools/list 检查工具是否可用：

curl -X POST http://localhost:7108/mcp/analyst/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

如果 dataset.open_in_viewer 出现在列表中，说明扩展已启用。

dataset.open_in_viewer

生成可分享的浏览器链接，用于交互式浏览大数据集。

使用场景

适用：

不适用（改用 dataset.query_model）：

参数

参数 类型 必需 说明
model string ✅ 查询模型名称
payload object ✅ 查询参数（与 query_model 格式一致）
payload.columns array ✅ 要显示的列列表
payload.slice array ✅ 过滤条件（至少一个）
payload.orderBy array ❌ 排序配置
payload.groupBy array ❌ 分组/聚合字段
title string ❌ 数据视图的标题

重要：payload.slice 必须提供至少一个过滤条件，防止无界查询。

调用示例

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "dataset.open_in_viewer",
    "arguments": {
      "model": "FactOrderQueryModel",
      "payload": {
        "columns": ["orderNo", "customer$caption", "orderDate$caption", "totalAmount"],
        "slice": [
          {"field": "orderDate$id", "op": "[)", "value": ["20250101", "20250131"]}
        ],
        "orderBy": [
          {"field": "orderDate$id", "dir": "DESC"}
        ]
      },
      "title": "2025年1月订单"
    }
  }
}

返回值

{
  "viewerUrl": "http://localhost:7108/data-viewer/view/abc123",
  "queryId": "abc123",
  "expiresAt": "2025-01-06T10:00:00",
  "estimatedRowCount": 1500,
  "message": "Data viewer link created. The link expires at 2025-01-06T10:00:00. Users can browse, filter, sort, and export the data interactively."
}
字段 说明
viewerUrl 浏览器访问链接
queryId 查询缓存 ID
expiresAt 链接过期时间
estimatedRowCount 预估行数（可选）

权限

端点 可用
/mcp/admin/rpc ✅
/mcp/analyst/rpc ✅
/mcp/business/rpc ❌

与 query_model 的区别

特性 query_model open_in_viewer
返回数据 直接返回查询结果 返回浏览器链接
适合数据量 小（≤100行） 大（500+行）
AI 分析 ✅ AI 可直接分析 ❌ 需用户在浏览器查看
交互能力 ❌ 静态结果 ✅ 过滤/排序/分页/导出
过滤条件 可选 必需（至少一个）

典型工作流

用户: "导出上个月的所有订单"

AI 判断:
1. "所有订单" → 数据量可能很大
2. 用户要求"导出" → 需要交互式浏览
3. 选择 open_in_viewer 而非 query_model

AI 调用 open_in_viewer:
→ 返回浏览器链接
→ 用户可在浏览器中查看、筛选、导出

开发自定义扩展

如需开发自定义 MCP 工具扩展，请参考 foggy-data-viewer 模块的实现：

1. 创建工具类

实现 McpTool 接口（来自 foggy-mcp-spi）：

public class MyCustomTool implements McpTool {

    @Override
    public String getName() {
        return "my.custom_tool";
    }

    @Override
    public Set<ToolCategory> getCategories() {
        return Set.of(ToolCategory.QUERY);
    }

    @Override
    public Object execute(Map<String, Object> arguments,
                          ToolExecutionContext context) {
        // 工具逻辑
        return Map.of("success", true);
    }
}

2. 创建自动配置类

使用 @AutoConfiguration 注册工具 Bean：

@AutoConfiguration
@ConditionalOnProperty(prefix = "my.extension", name = "enabled",
                       havingValue = "true", matchIfMissing = true)
public class MyExtensionAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MyCustomTool myCustomTool() {
        return new MyCustomTool();
    }
}

3. 注册自动配置

在 src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 中添加：

com.example.MyExtensionAutoConfiguration

4. 添加依赖

扩展模块需要依赖 foggy-mcp-spi：

<dependency>
    <groupId>com.foggysource</groupId>
    <artifactId>foggy-mcp-spi</artifactId>
    <version>${foggy.version}</version>
</dependency>

工具将被 McpToolDispatcher 自动发现并注册。

下一步