数据语义层MCP桥接器

Foggy Data MCP Bridge

A governed semantic layer that lets AI assistants query business data through MCP—without making raw database schemas the AI interface.

简体中文 · Documentation · Releases · Issues

Overview

Giving an LLM direct access to database schemas and asking it to generate SQL couples the AI to physical tables, dialect details, and fragile join logic. Foggy puts a semantic and governance layer in between:

AI client
   │  MCP / JSON Query DSL
   ▼
Foggy Runtime
   ├── TM/QM semantic models
   ├── namespace and field policies
   ├── query planning and dialect translation
   └── model lifecycle and Runtime API
   │
   ▼
MySQL · PostgreSQL · SQL Server · SQLite · optional MongoDB

AI clients work with business concepts such as revenue, customer, product, and order date. Foggy resolves those concepts into governed, read-oriented queries and handles joins, aggregation, and database dialects at runtime.

Highlights

• Semantic modeling — define reusable table models (TM) and query models (QM) with FSScript.
• MCP-native access — expose analyst, business, and administrative tool surfaces over JSON-RPC.
• Structured query DSL — keep generated queries inside a model-aware contract instead of accepting arbitrary AI-generated SQL.
• Runtime governance — namespace isolation, semantic field allowlists, physical-column deny rules, and auditable tool execution.
• Model lifecycle — register bundles, validate models, refresh atomically, and inspect runtime capabilities through REST APIs.
• Extensible backends — relational databases in the core repository, with optional MongoDB, cache, vector, pre-aggregation, GraphQL, viewer, and Odoo integrations.

Quick start

The published Runtime Launcher is the shortest path for local development and evaluation. It requires Java 17 or newer and uses a local SQLite database by default.

The launcher is a dev/test distribution. Add production authentication, network controls, datasource governance, and deployment hardening before exposing Foggy outside a trusted environment.

1. Download and start the Runtime

The commands below pin launcher 0.1.18. Check the releases page for a newer version.

mkdir foggy-runtime && cd foggy-runtime

curl -fLO https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/foggy-runtime-launcher-0.1.18.jar
curl -fLO https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/start-foggy-runtime.sh
curl -fLO https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/runtime-launcher-manifest.json
curl -fLO https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/SHA256SUMS

grep -E 'foggy-runtime-launcher-0.1.18.jar|start-foggy-runtime.sh|runtime-launcher-manifest.json' SHA256SUMS | sha256sum -c -
chmod +x start-foggy-runtime.sh
./start-foggy-runtime.sh

Windows users can download start-foggy-runtime.ps1 from the same release and run it from PowerShell. The default service URL is http://127.0.0.1:18066.

Launcher 0.1.18 embeds the Analytics Console and its Analytics Runtime API in the same JAR, so there is no separate Console installation. Both remain disabled by default. Verify features.analyticsConsole.embedded=true in runtime-launcher-manifest.json, then opt in with ANALYTICS_CONSOLE_ENABLED=true ./start-foggy-runtime.sh or .\start-foggy-runtime.ps1 -AnalyticsConsole. FAP integration remains disabled and host-managed.

2. Verify the service

curl http://127.0.0.1:18066/readyz
curl http://127.0.0.1:18066/api/v1/capabilities

The capabilities response reports the Runtime API version, enabled features, and securityMode. If a deployment reports auth-code, supply the configured auth code when using its Runtime API.

3. Connect an MCP client

Use the analyst JSON-RPC endpoint and select a namespace with X-NS:

{
  "mcpServers": {
    "foggy-ai-analysis": {
      "url": "http://127.0.0.1:18066/mcp/analyst/rpc",
      "headers": {
        "X-NS": "salesdrop"
      }
    }
  }
}

Some clients require an additional "type": "http" field. Keep runtime metadata and datasource credentials outside mcpServers.

You can probe the endpoint before configuring a client:

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

4. Add a datasource and semantic models

A useful query environment needs:

1. a namespace and datasource binding;
2. TM/QM model files in a model bundle;
3. successful model validation and refresh;
4. an MCP client connected with the matching X-NS header.

Follow the AI analysis onboarding guide for the bundled SQLite example or for connecting your own datasource. See the semantic-layer syntax reference and Query DSL reference when building models and queries.

Query example

The AI submits semantic fields rather than physical joins:

{
  "model": "FactSalesQueryModel",
  "payload": {
    "columns": [
      "product$brand",
      "sum(salesAmount) as totalSalesAmount"
    ],
    "slice": [
      {
        "field": "salesDate$caption",
        "op": "[)",
        "value": ["2026-01-01", "2027-01-01"]
      }
    ],
    "groupBy": ["product$brand"],
    "orderBy": ["-totalSalesAmount"],
    "limit": 10
  },
  "mode": "execute"
}

Foggy resolves the model relationships, applies configured access rules, plans the aggregation, translates the query for the selected backend, and returns a structured result.

Run the source Docker demo

The repository also contains an e-commerce demo backed by MySQL. This path builds the current source tree and requires an OpenAI-compatible API key.

git clone https://github.com/foggy-projects/foggy-data-mcp-bridge.git
cd foggy-data-mcp-bridge/docker/demo
cp .env.example .env
# Edit .env and set OPENAI_API_KEY and, if needed, OPENAI_BASE_URL.
docker compose up -d --build
curl http://localhost:7108/actuator/health

See the Docker demo guide for models, configuration, logs, and cleanup commands.

Repository layout

For the complete module boundaries and lifecycle, read the canonical architecture guide.

Development

Prerequisites:

• JDK 17+
• Maven 3.9+
• Docker Compose v2 for integration environments

Run the unit-test reactor:

mvn -B -ntp test -DskipITs

Run focused tests while developing a module:

mvn -B -ntp -pl foggy-runtime-api,foggy-dataset-mcp -am test -DskipITs

Integration tests are opt-in and may require external databases:

mvn -B -ntp verify -DskipITs=false

Please open an issue before a large architectural change and submit changes through a focused pull request. Never commit credentials, connection strings, or logs containing sensitive data.

Documentation and support

• User documentation
• Architecture
• Releases
• Bug reports and feature requests
• Discussions
• Foggy Odoo Bridge

License

Copyright © Foggy Data MCP Bridge contributors.

Licensed under the Apache License 2.0.