Introduction

Turn Your Database Into an AI-Ready Semantic Plane

RunContext builds a semantic plane between your database and your AI tools — a structured metadata layer that captures what your data means, not just what it’s named. AI agents use it to generate correct SQL on the first try.

The Problem

AI agents see table and column names, but they don’t understand what the data means. They don’t know:

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
Exactly which SQL to use for “show me top customers by revenue last quarter”

Every query is a guess. And guesses are wrong often enough to be dangerous.

The Solution

1. context setup          → 6-step wizard opens in your browser
2. Connect                → Choose your database
3. Define                 → Name, owner, sensitivity
4. Scaffold               → Introspect schema → Bronze metadata
5. Checkpoint             → Review what was generated
6. Curate                 → Enrich toward Silver
7. Serve                  → MCP server live — agents have full context

Step 1 — Connect. Run context setup and a 6-step wizard opens in your browser. Connect your database (auto-detected from environment or enter a connection URL).

Step 2 — Define. Name your semantic plane, set an owner, and choose a sensitivity level.

Step 3 — Scaffold. RunContext introspects your schema and scaffolds Bronze-tier metadata automatically.

Step 4 — Checkpoint. Review what was generated — tables, columns, types, and initial descriptions.

Step 5 — Curate. The wizard enriches toward Silver (sample values, tags, glossary links, lineage).

Step 6 — Serve. Run context serve and every AI tool in your stack gets full context.

Path to Gold — Agent-Driven Curation. Gold requires deep domain knowledge: semantic roles on every field, 3+ golden queries, guardrails, business rules, and hierarchies. The fastest path is agent-driven curation — copy the MCP config into your IDE (Claude Code, Cursor, or Copilot), paste the curation prompt, and your AI agent queries the actual database to curate your semantic plane to Gold.

Three Ways to Use It

1. Browser wizard (recommended for getting started)

context setup

Opens a 6-step wizard in your browser: Connect > Define > Scaffold > Checkpoint > Curate > Serve.

2. AI agent runs CLI commands

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

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

The agent uses CLI commands and reads AGENT_INSTRUCTIONS.md to build your semantic plane. It queries your actual database via MCP, going back and forth with you — asking about metrics, ownership, and business rules — to curate all the way to Gold.

3. Visual studio for humans

context dev --studio

Browser-based editor for descriptions, semantic roles, golden queries, and business rules. Changes save to disk and the tier scorecard updates live.

As an MCP Server

For agents that need to query an existing semantic plane:

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

Exposes 8 MCP tools: search, explain, validate, tier, golden-queries, guardrails, list-products, get-product.

What’s Included

One install, everything you need:

npm install @runcontext/cli

Browser setup wizard — 6-step wizard: Connect > Define > Scaffold > Checkpoint > Curate > Serve
Visual studio editor — curate metadata in the browser with live tier updates
16 CLI commands — introspect, enrich, lint, fix, build, tier, blueprint, serve, and more
MCP server with 8 tools — serve your semantic plane to AI agents via stdio or HTTP
40 lint rules — schema validation, governance, security, data accuracy
Bronze/Silver/Gold tier system — automated metadata maturity scoring
AI Blueprints — export Gold-tier metadata as portable OSI YAML
Static site generator — browsable documentation from your metadata
9 database adapters — DuckDB, PostgreSQL, MySQL, SQL Server, SQLite, Snowflake, BigQuery, ClickHouse, Databricks
Agent instruction generation — setup creates AGENT_INSTRUCTIONS.md so any AI agent knows how to curate

Built on the Open Semantic Interchange (OSI) specification — your metadata is portable, not locked in.