ContextGuard SQL Agent

A metadata-guided, read-only SQL analysis MVP for DataHub.

Demo video (2:44): https://youtu.be/btmJJWMFe4g

The video shows a real local self-hosted DataHub MCP run with a Reader-only identity, seven read-only tools, a deterministic planner, local read-only synthetic SQLite, and zero mutation or proposal calls. All business data shown is synthetic.

ContextGuard answers a narrow analytical question without turning an agent into a database writer. It uses DataHub metadata through the official MCP server to find a synthetic asset, inspect schema and lineage, generate bounded SQL, and run that SQL only against a local synthetic SQLite database.

The problem

Analytical agents need more than table names. They need trustworthy schema, ownership, tags, lineage, and safe query boundaries. Without them, an agent can select an unsuitable asset, expose sensitive fields, scan too broadly, or issue write operations.

Related MCP server: sql-explorer-mcp

Architecture

flowchart LR
  DH[DataHub] --> MCP[Official MCP Server]
  MCP --> AD[Read-only Adapter]
  AD --> PL[Deterministic Planner]
  PL --> SL[SQL Safety Layer]
  SL --> DB[Local Synthetic SQLite]
  DB --> EA[Evidence-backed Analysis]
  EA --> RA[Redacted Audit]

The planner is deterministic. This MVP does not claim to use an external LLM.

What is real, and what is synthetic

The project was validated locally against a self-hosted DataHub instance and the official mcp-server-datahub. The DataHub reads, MCP protocol, client adapter, SQLite safeguards, and end-to-end execution are real.

All business-like values, names, markets, emails, assets, and results in this repository are fictional synthetic demo data. The project does not connect to company MySQL, production databases, or external network databases.

DataHub MCP integration

The client accepts only these Reader-safe tools:

• search

• get_entities

• list_schema_fields

• get_lineage

• get_lineage_paths_between when exposed by the server

• get_dataset_queries

• get_me

Mutation, proposal, administrator, and token-management tools are hard-blocked in the client before any server call. The local MCP process is additionally configured with mutations disabled.

SQLite read-only safeguards

• Opens the local fixture with mode=ro.

• Enables PRAGMA query_only and an SQLite authorizer.

• Rejects writes, DDL, ATTACH, DETACH, extension loading, writable PRAGMA, multiple statements, SELECT *, and alias.*.

• Requires explicit allowed fields, a numeric LIMIT, and date bounds for larger synthetic assets.

Installation

Python 3.11+ is recommended.

python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
python -m pip install -r requirements.txt

Local offline mode

pytest tests -q
python -m app.cli offline-demo

Offline mode uses a fixture strictly for local testing. It is not presented as a real DataHub integration.

Real DataHub mode

Real mode requires a locally running self-hosted DataHub and an official MCP executable. Put any Reader credential in a private, user-owned environment file outside this repository. Never place a token in a command line, Git, screenshots, or logs.

DATAHUB_GMS_URL=http://localhost:8080
DATAHUB_GMS_TOKEN=<reader-token>
CONTEXTGUARD_SQLITE_PATH=<path-to-synthetic-db>

Then provide the MCP command through the local private environment and run:

python -m app.cli real --question "Why did sales decline this period?" \
  --period-start 2026-07-13 --period-end 2026-07-20 --limit 20

Real mode fails closed if the MCP command is unavailable; it never falls back to an offline fixture.

Example result

For the synthetic weekly sales scenario, building sets explain most of the fictional decline: CNY 900 of the CNY 950 period-over-period decrease. See the example analysis.

Demo and tests

• Architecture

• Security model

• Demo walkthrough

• Three-minute script

• Final demo video (2:44)

• Submission draft

The project has 29 offline tests covering read-only policy enforcement, no-fallback behavior, token/error redaction, subprocess cleanup, and SQLite database-layer controls. The real MCP MVP was validated locally against a self-hosted DataHub instance; raw runtime logs are intentionally not public.

Known limitations

• Local MVP only; not a production authorization design.

• Deterministic planner for one synthetic sales-decline scenario.

• No public deployment or UI is included.

• get_dataset_queries may honestly return an empty set because the demo does not import query history.

No-mutation guarantee

This public MVP does not support metadata write-back. It does not call DataHub mutation or proposal tools.

Hackathon submission status

The local technical MVP has completed its real read-only acceptance. This repository is a publication candidate only: it has no remote configured, has not been pushed, and has not been submitted to Devpost.

License

Licensed under Apache License 2.0.