Foggy Data MCP Bridge

雾数据MCP桥

使AI助手能够通过语义层和MCP查询业务数据，而不是直接编写原始SQL。

   

为什么存在

让LLM直接针对生产数据生成SQL通常是错误的抽象：

• 您必须向模型公开模式细节和数据库方言怪癖。
• 一旦模型自己编写SQL，权限就很难保留。
• 随着提示的增加，JOIN、聚合和业务含义会迅速漂移。
• 多数据库部署使问题成倍增加。

Foggy Data MCP在AI和数据库之间放置了一个语义层：

AI assistant -> MCP tools / JSON DSL -> semantic layer -> safe SQL -> database

该层为您提供：

• 业务语义而不是原始表公开
• 面向阅读的查询治理
• 执行前注入许可
• 可重复使用的TM/QM模型
• 跨多个数据库的一个查询接口

这是给谁的

• 构建内部AI数据助理的团队
• 通过MCP公开受控数据访问的产品
• 需要业务友好型查询界面的ERP/BI/报告项目
• 希望在不将SQL生成交给模型的情况下进行AI可访问分析的开发人员

如果您的直接用例是Odoo，请从这里开始：

• 雾蒙蒙的奥多大桥

所得

• 基于TM/QM模型的语义层引擎
• JSON查询DSL，而不是原始SQL提示
• AI客户端和工具的原生MCP端点
• 多数据库支持：MySQL、PostgreSQL、SQL Server、SQLite、MongoDB
• 使用FSScript进行类似JavaScript的建模
• 自动图表生成支持
• 服务器部署的Java实现
• 基于嵌入式和FastAPI场景的Python实现

查询流示例

AI只需要业务字段，不需要表结构：

{
  "model": "FactSalesQueryModel",
  "columns": ["customer$name", "sum(totalAmount)"],
  "filters": [{"field": "orderDate", "op": ">=", "value": "2024-01-01"}],
  "orderBy": [{"field": "totalAmount", "dir": "DESC"}],
  "limit": 10
}

Foggy将其转化为内置JOIN处理、聚合和方言转换的受管SQL。

快速开始

1.克隆并开始演示

git clone https://github.com/foggy-projects/foggy-data-mcp-bridge.git
cd foggy-data-mcp-bridge/docker/demo

# Optional: enable natural-language querying
cp .env.example .env
# Edit .env and set OPENAI_API_KEY if needed

docker compose up -d

2.验证服务

curl http://localhost:7108/actuator/health

3.连接AI客户端

克劳德桌面示例：

{
  "mcpServers": {
    "foggy-dataset": {
      "url": "http://localhost:7108/mcp/analyst/rpc"
    }
  }
}

光标设置：

• 光标集成指南

4.问一个问题

• “按品牌显示上周的销售额”
• “上个月哪些产品的退货率最高？”
• “生成按地区比较收入的图表”

为什么不使用原始SQL

关键能力

安全与治理

• 基于DSL的查询，而不是原始SQL生成
• 按设计的只读查询模型
• 现场级和角色级访问控制
• 执行前的运行时权限注入

建模

• TM/QM语义建模
• 计算字段和可重用的业务指标
• 用于函数、导入和动态逻辑的FSScript
• 父子维度和预聚合支持

整合

• 人工智能助手的MCP端点
• 自然语言到DSL工作流程
• 图表渲染支持
• 基于Docker的本地演示和部署

______________________________________________________________________

🎬 快速入门（Docker）

1.克隆并启动

git clone https://github.com/foggy-projects/foggy-data-mcp-bridge.git
cd foggy-data-mcp-bridge/docker/demo

# Optional: Set OpenAI API key for natural language queries
cp .env.example .env
# Edit .env to configure OPENAI_API_KEY (optional)

docker compose up -d

2.验证服务

curl http://localhost:7108/actuator/health

3.连接AI客户端

克劳德桌面版 -添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "foggy-dataset": {
      "url": "http://localhost:7108/mcp/analyst/rpc"
    }
  }
}

光标IDE - 请参阅集成指南

4.开始查询！

现在用自然语言问AI：

• *“按品牌显示上周的销售额”*
• *“上个月哪些产品的退货率最高？”*
• *“生成按地区比较收入的图表”*

______________________________________________________________________

📖 运作原理

1.️⃣ 定义数据模型（TM文件）

创建 FactSalesModel.tm 使用FSScript语法：

export const model = {
    name: 'FactSalesModel',
    caption: 'Sales Data',
    tableName: 'fact_sales',

    dimensions: [{
        name: 'product',
        tableName: 'dim_product',
        foreignKey: 'product_key',
        caption: 'Product',
        properties: [
            { column: 'brand', caption: 'Brand' },
            { column: 'category', caption: 'Category' }
        ]
    }],

    measures: [
        { column: 'quantity', caption: 'Quantity', aggregation: 'sum' },
        { column: 'sales_amount', caption: 'Sales Amount', aggregation: 'sum' }
    ]
};

2.️⃣ AI发送语义查询

AI不需要知道表结构，只需要知道语义字段：

{
  "model": "FactSalesQueryModel",
  "columns": ["product$brand", "salesAmount"],
  "filters": [{ "field": "orderDate", "op": ">=", "value": "2024-01-01" }],
  "orderBy": [{ "field": "salesAmount", "dir": "DESC" }],
  "limit": 10
}

3.️⃣ 框架生成安全SQL

SELECT p.brand, SUM(f.sales_amount) as salesAmount
FROM fact_sales f
LEFT JOIN dim_product p ON f.product_key = p.product_key
WHERE f.order_date >= '2024-01-01'
GROUP BY p.brand
ORDER BY salesAmount DESC
LIMIT 10

没有SQL注入风险。禁止未经授权的访问。只是安全的语义查询。

______________________________________________________________________

🏗️ 项目结构

foggy-data-mcp-bridge/
├── foggy-core/                    # Core utilities
├── foggy-fsscript/                # FSScript scripting engine (JavaScript-like)
├── foggy-dataset/                 # Multi-database query layer (Dialects)
├── foggy-dataset-model/           # Semantic layer engine (TM/QM)
├── foggy-dataset-mcp/             # MCP server implementation
├── foggy-dataset-demo/            # Demo: E-commerce sample data
├── foggy-bean-copy/               # Bean mapping utilities
├── docs-site/                     # VitePress documentation (bilingual)
│
└── addons/                        # Extension modules
    ├── chart-render-service/      # Chart generation service
    ├── foggy-benchmark-spider2/   # Spider2 benchmark testing
    ├── foggy-dataset-client/      # Dataset client SDK
    ├── foggy-dataset-model-mongo/ # MongoDB model support
    ├── foggy-dataset-mongo/       # MongoDB query layer
    └── foggy-fsscript-client/     # FSScript client utilities

核心模块

扩展插件

______________________________________________________________________

📚 文档

📘 入门指南

• MCP简介 -什么是雾MCP
• 快速开始 -起来跑步
• 建筑 -系统架构概述

📗 核心概念

• TM/QM建模 -构建语义层
• TM语法手册 -表模型参考
• QM语法手册 -查询模型参考
• 查询DSL API -JSON查询引用

📙 FSScript引擎

• 为什么选择FSScript -使用案例
• 语法指南 -语言参考
• Spring Boot集成 -Java集成

📕 MCP集成

• Claude桌面设置
• 光标集成
• MCP工具参考
• API使用

🌐 完整文档网站

访问：

______________________________________________________________________

🎯 用例

📊 商业智能

• 特殊查询 -商业用户用自然语言提问
• 多维分析 -按维度分组，汇总度量
• KPI仪表盘 -使用计算字段跟踪指标

🔍 数据分析平台

• 自助服务分析 -非技术用户在没有SQL的情况下查询数据
• 动态过滤 -没有模式知识的灵活条件
• 数据探索 -人工智能有助于发现洞察力

🏢 企业数据网关

• 统一数据访问 -跨多个数据库的单个语义层
• 访问控制 -基于角色的字段级权限
• 审计日志 -跟踪所有数据访问

🤖 AI代理开发

• RAG系统 -检索业务数据以进行人工智能推理
• 聊天机器人 -回答数据库中的业务问题
• 工作流程自动化 -人工智能驱动的数据操作

______________________________________________________________________

🛠️ 发展

先决条件

• Java 17+
• Maven 3.6+
• 码头工人 （可选，用于演示）

本地建设

# Build all modules
mvn clean install

# Run MCP server
cd foggy-dataset-mcp
mvn spring-boot:run

IDE设置

看 IDE开发指南 用于IntelliJ IDEA/VS代码配置。

______________________________________________________________________

🤝 贡献

我们欢迎捐款！拜托：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

______________________________________________________________________

📄 许可证

Apache许可证2.0

______________________________________________________________________

🌟 星迹

如果你觉得这个项目有用，请给它一个⭐️ 在GitHub上！


______________________________________________________________________

📞 支持与社区

• GitHub问题: 报告错误或请求功能
• 文档: 完整文档网站
• 讨论: 加入对话

______________________________________________________________________

建于❤️ AI+数据社区