Introduction

Tell Your Agent to Build Your Semantic Layer

Tell your AI agent: “Install @runcontext/cli and build a semantic layer for my database.”

The agent installs ContextKit, connects to your data, and goes back and forth with you — asking about your metrics, business rules, and use cases — while it builds the semantic layer using CLI commands. When it reaches Gold tier, it serves the metadata to other AI agents via MCP.

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 (portable Gold-tier spec)
Agent: context serve --stdio → MCP server live

The setup wizard generates context/AGENT_INSTRUCTIONS.md — a comprehensive curation guide that tells any agent exactly what to do, what questions to ask, and which CLI commands to run. Works with Claude Code, Cursor, Windsurf, or any agentic coding platform.

Built on the Open Semantic Interchange (OSI) specification — an open standard for describing semantic models in a vendor-neutral format. Your metadata is portable across any OSI-compliant tool, not locked into ContextKit.

The Problem

AI agents querying databases 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

ContextKit creates a governance layer between your database and your AI tools:

Database  →  ContextKit  →  AI Agent
(schema)     (meaning)      (correct SQL)

With ContextKit, an 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 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”

Three Ways to Use It

1. Agent runs CLI commands (recommended)

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 uses the 16 CLI commands to build your semantic layer. The setup wizard generates instruction files that tell the agent exactly what to do:

• context/AGENT_INSTRUCTIONS.md — the complete agent operating manual with workflow, decision trees, curation recipes, and YAML format references

No MCP configuration needed. The agent just runs commands.

2. As an MCP server

For agents that need to query an existing semantic layer:

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

Exposes context_search, context_explain, context_validate, context_tier, context_golden_queries, and context_guardrails as MCP tools.

3. Visual editor for humans

context dev --studio

Browser UI for editing descriptions, semantic roles, golden queries, and business rules without touching YAML. Changes save to disk and the tier scorecard updates live.

What’s Included

One install, everything you need:

npm install @runcontext/cli

• 16 CLI commands — introspect, enrich, lint, fix, build, tier, blueprint, new, verify, serve, and more
• Data products — scaffold multiple data products in one project with context new <name>
• AI Blueprints — export the Gold-tier outcome as a portable OSI YAML file with context blueprint
• 40 lint rules — schema validation, governance, security, data accuracy
• Bronze/Silver/Gold tier system — automated metadata maturity scoring
• MCP server — expose your context graph and AI Blueprints to agents via stdio or HTTP
• Visual studio editor — browser-based metadata curation with live tier updates
• Static site generator — browsable documentation from your metadata
• 9 database adapters — DuckDB, PostgreSQL, MySQL, SQL Server, SQLite, Snowflake, BigQuery, ClickHouse, Databricks
• MCP config discovery — auto-detects databases from Claude Code, Cursor, VS Code, Windsurf, and Claude Desktop
• Smart driver detection — offers to install missing database drivers during setup
• Agent instruction generation — setup wizard creates context/AGENT_INSTRUCTIONS.md so any AI agent knows exactly how to build and curate your semantic layer