ContextKit

Tell your AI agent to build your semantic layer. It uses ContextKit to do it.

Documentation · Quick Start · CLI Reference · OSI Spec

---

The Problem

AI agents querying databases today see table and column names — but they don't understand what the data means. They don't know which filters are required, how metrics should be aggregated, or which joins are safe. Every query is a guess.

The Solution

Tell your AI agent to install @runcontext/cli and build your semantic layer. The agent runs the CLI, introspects your database, and goes back and forth with you — asking about your metrics, business rules, and use cases — while it curates the metadata. When it reaches Gold tier, it serves the semantic layer to other AI agents via MCP, so they generate correct SQL instead of guessing.

You: "Install @runcontext/cli and build a semantic layer for my database"
Agent: npm install @runcontext/cli
Agent: context setup → connects → introspects → scaffolds metadata
Agent: context enrich --target silver --apply → auto-fills descriptions, types, lineage
Agent: context tier → "Silver. 12 Gold checks remaining."
Agent: "I see a revenue column — should this be SUM'd or AVG'd?"
You: "Always SUM. And filter out refunded orders."
Agent: updates governance YAML, adds guardrail filter
Agent: context tier → "9 checks remaining. What team owns this data?"
You: "Analytics team, alice@company.com"
Agent: updates owner file
Agent: context tier → ... iterates until Gold
Agent: context blueprint → exports AI Blueprint (the complete semantic spec)
Agent: context serve --stdio → MCP server live, all agents get curated context

The outcome is an AI Blueprint — a single, portable YAML file per data product that captures the complete semantic spec: every field, metric, relationship, business rule, and golden query. It's the Gold-tier deliverable. Export it with context blueprint, serve it via MCP, or share it with any OSI-compliant tool.

The agent reads context/AGENT_INSTRUCTIONS.md (generated by setup) and knows exactly how to curate metadata, what questions to ask you, and which CLI commands to run. Built on the Open Semantic Interchange (OSI) specification.

---

Quick Start

Tell your AI agent to build it

In Claude Code, Cursor, Windsurf, or any agentic coding platform, just say:

"Install @runcontext/cli and build a semantic layer for my database."

The agent will:

1. Run npm install @runcontext/cli
2. Run context setup to connect to your database, introspect the schema, and scaffold metadata
3. Read the generated context/AGENT_INSTRUCTIONS.md — which tells it exactly how to curate
4. Go back and forth with you, asking about metrics, ownership, business rules, and use cases
5. Iterate with context tier until every Gold check passes
6. Serve the semantic layer via context serve --stdio

The setup wizard generates context/AGENT_INSTRUCTIONS.md — a comprehensive curation guide that tells any AI agent exactly how to work with your semantic layer. Works with Claude Code, Cursor, Windsurf, or any agentic coding platform. No platform-specific config files needed.

Or use it as an MCP server

If you want agents to query an existing semantic layer (rather than build one), add ContextKit as an MCP server:

{
  "mcpServers": {
    "contextkit": {
      "command": "npx",
      "args": ["@runcontext/cli", "serve", "--stdio"]
    }
  }
}

This gives agents access to context_search, context_explain, context_validate, context_tier, context_golden_queries, and context_guardrails.

Or do it yourself

npm install -g @runcontext/cli

# Interactive wizard: introspect → scaffold → enrich
context setup

# Or step by step:
context introspect --db duckdb://warehouse.duckdb
context enrich --target silver --apply --source default
context tier

Or edit visually

# Open the interactive metadata editor in your browser
context dev --studio

The visual editor lets you curate descriptions, semantic roles, golden queries, and business rules without touching YAML. Changes save back to disk and update the tier scorecard live.

---

How It Works

Database  →  context introspect  →  YAML metadata (Bronze)
                                        ↓
                              context enrich (Silver)
                                        ↓
                          Human/agent curation (Gold)
                                        ↓
                              context serve (MCP)
                                        ↓
                        AI agents get curated context

The Tier System

ContextKit scores metadata maturity on three tiers:

Bronze — Discoverable. Every model, dataset, and field has a description, an owner, and a security classification. The minimum for catalog entry.

Silver — Trusted. Adds trust status, glossary links, lineage, sample values, refresh cadence, and tags. Bridges raw tables to business concepts. context enrich gets you here automatically.

Gold — AI-Ready. Semantic roles on every field, aggregation rules for metrics, guardrail filters, golden queries, business rules, hierarchies, explicit relationships, and AI context. This is what makes agents generate correct SQL. It requires human curation — and that's where the real value is.

---

What Gold Metadata Gives an Agent

Without ContextKit, an agent guesses. With it, the agent knows:

• That revenue should be SUM'd, never AVG'd
• That queries on transactions must filter WHERE status = 'completed'
• That customer_id joins orders to customers as a many-to-one
• That "demand signal" means review keywords like wait, crowded, busy
• Exactly which SQL to use for "show me top customers by revenue last quarter"

---

CLI Reference

16 commands — one package, everything included:

# Build the semantic layer
context setup                    # Interactive wizard — database to metadata in one flow
context new <name>               # Scaffold a new data product inside your project
context introspect               # Scan a database → scaffold Bronze-level OSI metadata
context enrich --target silver   # Auto-enrich metadata toward a target tier
context lint                     # Run all lint rules against context files
context fix --write              # Auto-fix lint issues where possible
context build                    # Compile context files → emit manifest JSON
context tier [model]             # Show Bronze/Silver/Gold scorecard

# Explore and verify
context explain <name>           # Look up any model, term, or owner
context rules                    # List all 40 lint rules with tier, severity, fixability
context validate-osi <file>      # Validate a single OSI file against the spec
context verify                   # Check metadata accuracy against a live database

# Export and serve
context blueprint [model]        # Export AI Blueprints — portable Gold-tier data product specs
context serve --stdio            # Start MCP server over stdio (for Claude, Cursor, etc.)
context serve --http --port 3000 # Start MCP server over HTTP
context site                     # Generate a static documentation site
context dev                      # Watch mode — re-lint on file changes
context dev --studio             # Interactive visual editor in the browser
context init                     # Scaffold a new project structure

---

MCP Server

The MCP server is how AI agents consume your semantic layer. Start it, and any MCP-compatible agent gets full access to your curated metadata.

context serve --stdio            # for Claude Code, Cursor, Windsurf
context serve --http --port 3000 # for multi-agent or remote setups

Resources — context an agent can pull:

Resource	Description
context://manifest	Full compiled manifest with all models, governance, and rules
context://model/{name}	Single model with datasets, fields, relationships, metrics
context://glossary	All business term definitions and synonyms
context://tier/{name}	Tier scorecard for a model
context://data-product/{name}	AI Blueprint — full semantic spec for a data product as portable YAML

Tools — actions an agent can invoke:

Tool	Description
context_search	Full-text search across models, fields, terms, and owners
context_explain	Look up any entity by name and get full details
context_validate	Run lint rules and return diagnostics
context_tier	Get the current tier scorecard
context_golden_queries	Retrieve curated SQL templates for a model
context_guardrails	Get required filters and business rules for safe queries

---

File Structure

ContextKit metadata lives in YAML files, organized by concern. Each data product is a model with companion governance, rules, and lineage files:

context/
├── models/
│   ├── sales.osi.yaml              # OSI semantic model — datasets, fields, relationships, metrics
│   └── inventory.osi.yaml          # Another data product in the same project
├── governance/
│   ├── sales.governance.yaml       # Ownership, trust, security, grain, semantic roles, sample values
│   └── sales.rules.yaml            # Golden queries, business rules, guardrails, hierarchies
├── lineage/
│   └── sales.lineage.yaml          # Upstream sources, downstream dependencies
├── glossary/
│   ├── revenue.term.yaml           # Business term definitions and synonyms
│   └── churn-rate.term.yaml
├── owners/
│   └── analytics-team.owner.yaml   # Team ownership records
├── reference/                       # Drop existing docs here — data dictionaries, wiki exports, ERDs
│   └── README.md
└── AGENT_INSTRUCTIONS.md            # Generated curation guide for AI agents

blueprints/                           # Generated by 'context blueprint'
├── sales.data-product.osi.yaml      # AI Blueprint — the complete Gold-tier spec
└── inventory.data-product.osi.yaml

contextkit.config.yaml                # Project configuration and data source connections

The OSI model file defines the schema per the OSI specification. Governance, rules, lineage, and glossary are companion files that ContextKit merges at build time. Run context new <name> to scaffold a new data product, or context blueprint to export an AI Blueprint.

---

Database Support

9 database engines — install only the drivers you need:

Adapter	Connection
DuckDB	--db duckdb://path.duckdb
PostgreSQL	--db postgres://user:pass@host:5432/db
MySQL	--db mysql://user:pass@host:3306/db
SQL Server	--db mssql://user:pass@host:1433/db
SQLite	--db path/to/file.sqlite
Snowflake	--db snowflake://account/database/schema
BigQuery	--db bigquery://project/dataset
ClickHouse	--db clickhouse://host:8123
Databricks	Config file only

The setup wizard auto-detects databases from your MCP server configs and offers to install missing drivers automatically.

---

40 Lint Rules

Tier	Count	Examples
Bronze	12	Descriptions required, ownership required, grain, security classification, valid schema
Silver	3	Trust status set, refresh cadence, upstream lineage
Gold	14	Semantic roles, aggregation rules, golden queries, relationship coverage, description quality
Data	8	Source tables exist, fields exist, types match, golden queries execute, guardrails valid SQL
Composite	3	Bronze/Silver/Gold tier requirement checks

---

Installation

npm install @runcontext/cli

One package — compiler, linter, tier engine, MCP server, site generator, introspector, enricher, visual editor, and all 15 CLI commands.

Package	Description
@runcontext/cli	The full toolkit — install this
create-contextkit	Project scaffolder (npx create-contextkit my-project)

---

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT