Foggy Data MCPAI-Native Semantic Layer Framework

Let AI assistants query business data through governed semantic models, structured DSL, and MCP tools

Governance First

DSL-based queries, parameter binding, and field-level permissions reduce direct SQL exposure and make query evidence easier to review.

Access Control

🎯

Model-as-Code

Define semantic layer using FSScript (JavaScript-like syntax). Functions, imports, and dynamic logic.

TM/QM Syntax

🌐

Multi-Database

MySQL, PostgreSQL, SQL Server, SQLite, MongoDB - same DSL query works everywhere.

Database Support

🤖

AI-Native MCP

Native MCP protocol support. Out-of-box integration with Claude Desktop & Cursor.

MCP Integration

📊

Technical Whitepaper

The v1.0 public whitepaper is currently published in Chinese while the English version is being prepared.

Read v1.0

🚀

Deployment Oriented

Spring Boot based runtime, Docker deployment path, bilingual manuals, and extensible integration modules.

Quick Deploy

Why This Project?

❌ The Problem: Letting AI Write SQL Directly is Dangerous

Problem	Impact
Governance Risks	AI-generated SQL can drift away from permission and audit boundaries
Schema Exposure	Must share complete database schema with AI
No Business Semantics	What does `order_status=3` mean? AI doesn't know
Complex JOINs	Multi-table relationships and aggregations are fragile

✅ Our Solution: Semantic Layer with DSL Query Language

AI → JSON DSL Query → Semantic Layer → Governed SQL → Database
                            ↓
                    • Uses structured query payloads
                    • Applies access control
                    • Handles multi-table JOINs
                    • Abstracts database dialects

Example: AI only needs to know semantic meaning, not database internals

json

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

🎯 Use Cases

📊 Business Intelligence

Ad-Hoc Queries - Business users ask questions in natural language
Multi-Dimensional Analysis - Group by dimensions, aggregate measures
KPI Dashboards - Track metrics with calculated fields

🔍 Data Analysis Platform

Self-Service Analytics - Non-technical users query data without SQL
Dynamic Filtering - Flexible conditions without schema knowledge
Data Exploration - AI helps discover insights

🏢 Enterprise Data Gateway

Unified Data Access - Single semantic layer across multiple databases
Access Control - Role-based field-level permissions
Audit Logging - Track all data access

🚀 Quick Start

Docker One-Click Start:

bash

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

Claude Desktop Configuration:

json

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

Then query data using natural language:

"Show me sales by brand for the last week"
"Which products had the highest return rate last month?"
"Compare revenue by region and explain the query evidence"

📦 Core Modules

Module	Description	Docs
foggy-dataset-model	Semantic layer engine - TM/QM modeling, DSL query execution	Guide
foggy-dataset	Database abstraction - Multi-database dialect support	Query Layer
foggy-fsscript	Script engine - JavaScript-like syntax for TM/QM files	FSScript Guide
foggy-dataset-mcp	MCP server - AI assistant integration	MCP Service

📘 TM/QM Modeling

TM Syntax Manual - Table model definition
QM Syntax Manual - Query model definition
Query DSL API - JSON query reference
Calculated Fields - Derived metrics

📗 FSScript Engine

Why FSScript - Design philosophy
Syntax Guide - Language reference
Spring Boot Integration - Java integration

Foggy Data MCPAI-Native Semantic Layer Framework

Governance First

Model-as-Code

Multi-Database

AI-Native MCP

Technical Whitepaper

Deployment Oriented

Why This Project? ​

❌ The Problem: Letting AI Write SQL Directly is Dangerous ​

✅ Our Solution: Semantic Layer with DSL Query Language ​

🎯 Use Cases ​

📊 Business Intelligence ​

🔍 Data Analysis Platform ​

🏢 Enterprise Data Gateway ​

🚀 Quick Start ​

📦 Core Modules ​

📘 TM/QM Modeling ​

📗 FSScript Engine ​