strict-semantic-mcp
Ships a DuckDB connector that runs compiled semantic queries against DuckDB warehouses (including an in-memory demo warehouse), and evaluates golden-question test cases deterministically against DuckDB.
Parses Snowflake-style CREATE SEMANTIC VIEW DDL into the canonical semantic model and supports Snowflake as a target dialect/warehouse for compiling and executing deterministic semantic queries.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
strict-semantic-mcp
A CI linter for Snowflake-style semantic views, and a deterministic, FinOps-safe semantic compiler + MCP server for AI data agents on BigQuery, DuckDB, Snowflake and Postgres.
Data warehouses like BigQuery have no native, strictly-enforced semantic views. When text-to-SQL agents query them through loose YAML or flexible graph layers, the failure modes are always the same: non-deterministic SQL, fan-out double counting, ambiguous join paths, raw-row dumps, and runaway scan costs.
This project makes the semantic model a blueprint, never a materialization:
.sql DDL / .yaml spec ──parse──▶ canonical AST (Pydantic v2)
──lint (SV-R1..R10)──▶ valid blueprint
──compile(request)──▶ one deterministic SQL statement ──connector──▶ rowsDual input, one AST. Snowflake
CREATE SEMANTIC VIEWDDL (human-authored) and a native YAML contract (automation-friendly) build byte-identical models.Static ground rules (SV-R1..R10). Primary keys and grain comments, a directed many-to-one join DAG with exactly one path between any two tables, no numeric dimensions, no
CURRENT_DATE, snapshot metrics declaredNON ADDITIVE BY, globally unique field names and synonyms, a security deny-list, comment templates.strict-semantic lintblocks CI on ERRORs.Deterministic compilation. Same request, same SQL, byte for byte. Joins only walk child→parent (zero fan-out, enforced); metrics of different grains drill across via
UNION ALL; derived ratios divide NULL-safely; every expression is built as a sqlglot AST — no string concatenation anywhere.FinOps guardrails. At least one metric per query (no raw dumps), partition filters required and pushed into each table's subquery (the only placement BigQuery honors on joined tables),
LIMITinjected and capped, BigQuery dry-run byte ceiling.MCP server (mcp ≥ 2). Five tools:
list_semantic_views,inspect_semantic_view,get_dimension_values,compile_semantic_query,execute_semantic_query. The agent picks names from the catalog and never writes SQL; every refusal carries an error code and a repair hint.Golden Questions eval.
strict-semantic eval cases.yamlgrades answer/refuse/clarify cases against DuckDB deterministically — no LLM judge.Open-core plugin hooks.
on_model_loaded,before_compile(RBAC filter injection),after_compile(cache/lineage),on_query_executed(audit).
Quickstart
python -m venv .venv && .venv/bin/pip install -e '.[dev,mcp]'
.venv/bin/python -m pytest # 64 tests
.venv/bin/strict-semantic lint tests/fixtures/ecommerce.sql
.venv/bin/strict-semantic eval tests/fixtures/golden_questions.yaml
.venv/bin/strict-semantic compile tests/fixtures/ecommerce.yaml \
-m revenue -m aov -d region \
-f '{"field":"order_date","op":">=","value":"2026-01-01"}' \
-f '{"field":"order_date","op":"<","value":"2026-02-01"}' --dialect bigqueryRun the MCP server against the demo warehouse (in-memory DuckDB):
STRICT_SEMANTIC_CONFIG=$PWD/examples/config.duckdb.yml .venv/bin/strict-semantic-mcpor register it with Claude Code:
claude mcp add strict-semantic -e STRICT_SEMANTIC_CONFIG=$PWD/examples/config.duckdb.yml -- $PWD/.venv/bin/strict-semantic-mcpFor BigQuery, copy examples/config.bigquery.example.yml, point views: at
your private spec folder, and set max_bytes.
Related MCP server: sql-steward
Writing a semantic view
Snowflake DDL (.sql) and the native YAML (.yml) are equivalent; metadata the
DDL has no slot for travels in structured comment directives (enforced by the
linter as SV-R8.1 templates):
CREATE SEMANTIC VIEW ecommerce
TABLES (
orders AS shop.orders PRIMARY KEY (order_id)
COMMENT = 'One row per order. Primary date: order_date. Partition: order_date BY order_date. Source: shop.orders.',
customers AS shop.customers PRIMARY KEY (customer_id)
COMMENT = 'One row per customer. Primary date: signup_date. Source: shop.customers.'
)
RELATIONSHIPS ( orders_customers AS orders (customer_id) REFERENCES customers (customer_id) )
DIMENSIONS (
customers.region AS region WITH SYNONYMS ('market') COMMENT = 'Customer home region. Values: EU, US, APAC.',
orders.order_date AS order_date COMMENT = 'Date the order was placed. Grains: day, week, month.'
)
METRICS (
orders.order_count AS COUNT(order_id) COMMENT = 'Number of orders placed. Population: all orders. Additivity: additive.'
)
COMMENT = 'Retail sales.'Directives: One row per … (grain), Primary date: col.,
Point-in-time snapshot., Partition: col BY dimension (lookback Nd, lookahead Nd).,
Grains: day, month., Type: timestamp., Values: a, b, c.
See tests/fixtures/ecommerce.{sql,yaml} for the full twin fixtures.
Querying
{"metrics": ["revenue", "aov"], "dimensions": ["region", "order_date__month"],
"filters": [{"field": "order_date", "op": "between", "value": ["2026-01-01", "2026-03-31"]},
{"field": "aov", "op": ">", "value": 50}],
"order_by": ["-revenue"], "limit": 100}Time dimensions take a __grain suffix. Filters on dimensions apply before
aggregation, filters on metrics after. Dimension-only queries are refused
(ERR_METRIC_REQUIRED) — value discovery goes through get_dimension_values,
a bounded SELECT DISTINCT … LIMIT ≤ 50.
Layout
src/strict_semantic/
├── models/ # canonical AST, error codes, request/response contracts
├── parsers/ # Snowflake DDL (token-stream) + native YAML -> one builder
├── linter/ # SV-R1..R10 engine: structure / logic / governance rules
├── compiler/ # join-graph resolver, FinOps guardrails, sqlglot SQL builder
├── connectors/ # DuckDB, BigQuery (dry-run + byte cap), protocol
├── plugins/ # open-core lifecycle hooks
├── eval/ # Golden Questions runner (deterministic, no LLM)
└── mcp_server/ # the five MCP tools over stdioDesign departures from the original blueprint, with reasons, are in docs/REVISIONS.md.
Security & deployment responsibility
The server speaks stdio and is designed to run next to the agent, on your machine, with your credentials. If you expose it over a network (HTTP/SSE, a gateway, a shared host), authentication, transport security and tenant isolation are yours to provide — nothing here does that for you.
Expect defense in depth from the warehouse side too: run the connector with a least-privilege, read-only account scoped to the datasets the views name. The compiler never concatenates SQL strings — filter values become typed sqlglot literals, operators come from a fixed whitelist, and every identifier must resolve against the linted model — but the SQL that reaches your warehouse should still be gated by the warehouse's own permissions. Per the Apache 2.0 license, the software is provided as is, without warranty; securing the deployment is the deployer's responsibility.
Report vulnerabilities privately via GitHub Security Advisories, not public issues.
Contributing
Scope is deliberately strict and minimal — read CONTRIBUTING.md before proposing features. Short version: determinism is non-negotiable, escape hatches get declined, and extensions belong in plugins.
License
Apache 2.0 (see LICENSE and NOTICE). Fixtures and examples
are a generic e-commerce schema; keep your company's semantic views in a
private repository and point the server at them via STRICT_SEMANTIC_CONFIG.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
The grounded data layer for any LLM: governed SQL, metrics, lineage and catalog over your data.
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
AI-native data layer: sheets, databases and apps for every agent, with exact answers and audit.
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to understand and query your database safely by providing a semantic layer of metadata, with tools to search, explain, validate, and generate safe SQL.2MIT
- AlicenseAqualityFmaintenanceA governed SQL gateway that exposes typed tools to AI agents, compiling safe read-only queries from a semantic layer while blocking PII before execution, supporting SQL Server, Postgres, and SQLite.9MIT
- AlicenseAqualityBmaintenanceEnables AI agents to query Trino and Apache Pinot lakehouses under enforced governance, where every SQL statement is AST-validated, table-allowlisted, priced from the engine's own plan before it runs, and blocked or admitted against scan-byte and intermediate-row budgets. It also grounds agents with schema discovery tools, returns verified results with warnings instead of misleading answers, and records every tool call on an audit trail.31Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query Postgres, BigQuery and DuckDB read-only through policy-checked SQL, with AST-based guards that refuse writes and dangerous functions, column masking on the way out, and an audit log of every query. Also exposes schema browsing and query-planning tools so agents can see allowed tables, columns and costs before running anything.MIT