┌─────────────────┐     MCP / REST      ┌───────────────────────┐
│  AI Assistant    │ ◄──────────────────► │  Foggy MCP Bridge     │
│  (Claude, etc.)  │   JSON-RPC 2.0      │  ┌─────────────────┐  │
└─────────────────┘                      │  │ Semantic Layer   │  │
                                         │  │ TM/QM Models     │  │
┌─────────────────┐     Async SQL        │  └────────┬────────┘  │
│  Database        │ ◄──────────────────► │           │           │
│  MySQL/PG/SQLite │   aiomysql/asyncpg   │  SQL Query Engine    │
└─────────────────┘                      └───────────────────────┘

# Clone the repository
git clone https://github.com/foggy-projects/foggy-data-mcp-bridge-python.git
cd foggy-data-mcp-bridge-python

# Install with development dependencies
pip install -e ".[dev]"

# Install database driver(s) you need
pip install aiomysql    # MySQL
pip install asyncpg     # PostgreSQL
pip install aiosqlite   # SQLite (included by default)

# Start with in-memory SQLite demo data
python -m foggy.demo.run_demo --port 8066

# Or connect to an existing database
python -m foggy.mcp.launcher.app \
  --db-host localhost --db-port 5432 \
  --db-user foggy --db-password secret \
  --db-name mydb

python -m pytest --tb=short -q
# 1322 passed, 76 skipped

foggy.mcp (MCP Server, FastAPI)
    │
    ├──► foggy.dataset_model (Semantic Query Engine)
    │        ├──► foggy.dataset (SQL Generation, DB Execution)
    │        │        └──► foggy.core (Utilities, Exceptions)
    │        └──► foggy.fsscript (Expression Engine)
    │
    └──► foggy.mcp_spi (SPI Types — shared interface layer)

src/foggy/
├── core/                # Utilities, exceptions, filters
├── bean_copy/           # Bean/Map conversion utilities
├── mcp_spi/             # SPI types (shared between all layers)
│   ├── semantic.py      # SemanticQueryRequest/Response (Java-aligned Pydantic models)
│   ├── accessor.py      # DatasetAccessor, LocalDatasetAccessor
│   ├── enums.py         # QueryMode, MetadataFormat, AccessMode
│   └── tool.py          # McpTool, ToolResult
├── dataset/             # Database abstraction layer
│   ├── dialects/        # MySQL, PostgreSQL, SQLite, SQL Server
│   ├── db/              # Async executor, connection management
│   └── resultset/       # Record, RecordList
├── dataset_model/       # Semantic layer engine
│   ├── semantic/        # SemanticQueryService (core query engine)
│   ├── engine/          # SQL query builder, formula engine, JOIN graph
│   ├── definitions/     # Model definitions (TM/QM)
│   └── impl/            # Model implementations
├── fsscript/            # FSScript expression engine (ported from Java)
├── mcp/                 # MCP server (FastAPI)
│   ├── launcher/        # Application factory, server startup
│   ├── routers/         # HTTP routes (admin, analyst, mcp_rpc, semantic_v3)
│   ├── schemas/         # MCP tool definitions (JSON schema + Markdown)
│   ├── tools/           # Tool implementations (query, metadata, chart)
│   ├── config/          # DataSource, Properties
│   └── audit/           # Tool audit logging
└── demo/                # Demo models and startup scripts

# List models
curl http://localhost:8066/api/v1/models

# Query a model
curl -X POST http://localhost:8066/api/v1/query/sales_model \
  -H "Content-Type: application/json" \
  -d '{
    "columns": ["product_name", "total_amount"],
    "slice": [{"field": "status", "op": "eq", "value": "confirmed"}],
    "groupBy": ["product_name"],
    "orderBy": [{"field": "total_amount", "direction": "DESC"}],
    "limit": 50
  }'

from foggy.mcp_spi import LocalDatasetAccessor
from foggy.dataset_model.semantic import SemanticQueryService

# Initialize the engine
service = SemanticQueryService(executor=my_db_executor, dialect=my_dialect)
service.register_model(my_table_model)

# Create accessor (accepts standard JSON dict)
accessor = LocalDatasetAccessor(service)

# Query with plain dict — no need to construct typed objects
result = accessor.query_model("sales_model", {
    "columns": ["product_name", "total_amount"],
    "groupBy": ["product_name"],
    "orderBy": [{"field": "total_amount", "direction": "DESC"}],
    "limit": 10,
})

# Result is a Pydantic model, serialize to Java-compatible JSON
print(result.model_dump(by_alias=True, exclude_none=True))

curl -X POST http://localhost:8066/mcp/analyst/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "dataset.query_model",
      "arguments": {
        "model": "sales_model",
        "payload": {
          "columns": ["product_name", "total_amount"],
          "limit": 10
        }
      }
    }
  }'

# Sync tool definitions from Java project
python scripts/sync_mcp_schemas.py

# Preview changes without applying
python scripts/sync_mcp_schemas.py --dry-run

# Show diff only
python scripts/sync_mcp_schemas.py --diff

# Tests
python -m pytest --tb=short -q

# Type checking
mypy src/foggy/

# Linting
ruff check src/ tests/

lib/foggy/
  ├── core/          ✅ Required
  ├── mcp_spi/       ✅ Required (SPI types + Accessor)
  ├── dataset/       ✅ Required (SQL engine)
  ├── dataset_model/ ✅ Required (Semantic engine)
  ├── fsscript/      ✅ Required (Expression engine)
  ├── bean_copy/     ✅ Required (Utilities)
  └── mcp/           ❌ Not needed (MCP Server, only for standalone deployment)