Foggy Data MCPAI-Native Semantic Layer Framework

Enable AI assistants to query business data safely and accurately through MCP protocol — without exposing database schemas

Get Started

JSON Query DSL

GitHub

🧠

Semantic Layer Engine

TM/QM models abstract database schemas. AI only understands business semantics. Auto-handles JOINs, dialect translation, and permission injection.

Learn More

🔍

JSON Query DSL

Declarative query language with 54+ built-in functions, 20+ operators, window functions, hierarchy queries, and pre-aggregation — one DSL for all databases.

DSL Reference

🤖

MCP Protocol Integration

Native MCP Server with out-of-box support for Claude Desktop, Cursor, and Trae CN. Natural language queries with auto chart generation.

MCP Tools

🔒

Security First

DSL queries eliminate SQL injection. Row / column / role-level access control with runtime permission injection and read-only design.

Access Control

🌐

Multi-Database Dialects

MySQL, PostgreSQL, SQL Server, SQLite, MongoDB — same DSL query, engine auto-translates to target dialect SQL.

Dialect Support

📝

Model-as-Code

Write TM/QM models in FSScript (JavaScript-like). Supports variables, functions, closures, module imports, and dynamic logic.

FSScript Engine

54+Built-in Functions

20+Query Operators

5Database Dialects

2Language SDKs

Why a Semantic Layer?

Letting AI write SQL directly against your database is risky and unreliable

❌ AI Writes SQL Directly

AI may generate DELETE / UPDATE statements
Must expose full database schema to AI
What does order_status=3 mean? AI doesn't know
Multi-table JOINs are fragile and error-prone
Different databases require different SQL dialects

✅ Semantic Layer + DSL Query

Read-only DSL design eliminates dangerous operations
AI only sees business semantics, not table structures
Semantic layer defines field meanings and relationships
Engine auto-handles JOINs and aggregations
One DSL works across all database dialects

            AI Assistant (Claude / Cursor / Trae)
                        │
                   MCP Protocol
                        │
                        ▼
┌─────────────────────────────────────────────┐
│            Foggy MCP Server                 │
│  ┌───────────┐  ┌──────────┐  ┌──────────┐ │
│  │  Metadata  │  │  Query   │  │  Chart   │ │
│  │   Tool     │  │  Tool    │  │  Tool    │ │
│  └───────────┘  └──────────┘  └──────────┘ │
└─────────────────────┬───────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────┐
│         Semantic Layer Engine                │
│                                             │
│  TM Model ──→ Dims/Measures ──→ QM Model    │
│                                             │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐ │
│  │DSL Parser │ │  Access  │ │ Dialect SQL │ │
│  │          │ │  Control │ │ Generator   │ │
│  └──────────┘ └──────────┘ └─────────────┘ │
└─────────────────────┬───────────────────────┘
                      │
         ┌────────────┼────────────┐
         ▼            ▼            ▼
      MySQL      PostgreSQL    SQL Server ...

Three Core Capabilities

SEMANTIC LAYER

🧠 Semantic Modeling

TM Table Model — Dimensions, measures, attributes
QM Query Model — Columns, ordering, permissions
Calculated Fields — Derived metrics & expressions
Parent-Child Dims — Hierarchies & closure tables
Pre-Aggregation — Accelerate large dataset queries

QUERY DSL

🔍 DSL Query

JSON Query DSL — Declarative query syntax
20+ operators (incl. NOT LIKE, hierarchy)
54+ built-in functions (math, date, string)
Window functions (ROW_NUMBER, LAG, etc.)
Multi-dialect SQL generation

MCP TOOLS

🤖 MCP Tools

Metadata Tool — Model discovery & schema
Query Tool — Execute DSL queries
NL Query — Natural language to DSL
Chart Render — Auto visualization
Extensions — Custom plugins

DSL Query Example

AI sends JSON DSL → Semantic layer translates to safe SQL

JSON DSL Input

json

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

Generated SQL (MySQL Dialect)

sql

SELECT
  c.name         AS `customer$name`,
  p.category_name AS `product$categoryName`,
  SUM(f.total_amount) AS `totalAmount`
FROM fact_sales f
  JOIN dim_customer c
    ON f.customer_id = c.id
  JOIN dim_product p
    ON f.product_id = p.id
WHERE f.order_date >= '2024-01-01'
  AND p.category_name IN
      ('Electronics', 'Books')
GROUP BY c.name, p.category_name
ORDER BY SUM(f.total_amount) DESC
LIMIT 10

Get Started in 3 Steps

Start the Server

docker compose up -d
One-click launch with MySQL + Foggy MCP Server + demo data

Configure AI Tool

Add MCP Server URL in Claude Desktop / Cursor:
http://localhost:7108/mcp/analyst/rpc

Start Querying

Ask in natural language:
"Show me sales trends by brand for last week"

Multi-Language Implementations

Java and Python dual engines, same semantic layer standard

☕ Java — Spring Boot 🐍 Python — FastAPI

Start Building AI Data Queries

Deploy a semantic layer in 5 minutes. Let AI query your business data safely.

Get Started →Read Docs GitHub