# Shanc — semantic layer over MCP (agent reference)

**What it is:** Shanc is a self-maintaining semantic layer for a company's data — tables, fields, joins, filters, metrics, business definitions, lineage. It is exposed to LLM agents over **MCP**. The layer is kept current **two ways: automatically** (Shanc updates it as your code and data change) **and agentically** (agents author and correct entities over MCP). Agents also **read** it for query-ready context.

## Interface

- **Protocol:** MCP — connects to Claude and other MCP clients.
- **Two modes, one connection:** *consume* (pull context) and *maintain* (author / update the layer).

## Tools

### Read — consume context

| tool | purpose |
|---|---|
| `retrieve_context` | query-ready context for a question — the main entry point |
| `search_semantic` | semantic search across fields / filters / grain |
| `list_sections`, `get_section_tables` | browse business areas → their tables |
| `get_table`, `get_field` | entity detail |
| `get_joins` | join paths between tables |

### Write — maintain the layer

| tool | purpose |
|---|---|
| `create_table`, `update_table` | define / revise an entity |
| `create_field`, `update_field` | define / revise a column or metric (additivity, aggregations, data type, time-dimension — each carried with a confidence rung) |
| `create_section` | add a business area |
| `parse_sql_to_drafts` | turn real SQL into draft entities |
| `record_schema_introspection` | fold in introspected schema |
| `delete_*` / `restore_*` | soft-remove and undelete (table / field / filter / join) |

### Lifecycle — review & commit

| tool | purpose |
|---|---|
| `submit_drafts` | queue authored entities for validation |
| `knowledge_status` | what's pending |
| `knowledge_commit` | commit reviewed changes |

## How the layer is maintained

**1. Automatically — by Shanc.** Continuously ingests git history, warehouse query logs, schema introspection, and supplied docs, and updates the layer as the underlying code/data changes. No one has to touch it.

**2. Agentically — over MCP.** Agents author and correct entities directly: `create_table` / `update_table`, `create_field` / `update_field`, `parse_sql_to_drafts`, `record_schema_introspection` → `submit_drafts` → `knowledge_commit`.

Both channels share the same safeguards:

- **Confidence ladder** (declared → observed → profiled → confirmed) — uncertainty is named, not blocked on a question.
- **draft → validate → commit** lifecycle — governed, not a free-for-all.
- **soft-delete + restore** — every change is reversible.

## When to use (decision rule)

- **Read** for any task needing this company's data model — generate SQL, resolve a metric / term, find the right tables / joins / filters, check freshness / provenance. Prefer Shanc over raw schema.
- **Write** when you learn something authoritative — a new entity, a corrected definition, a measured cardinality — so the rest of the team and other agents inherit it.

## Positioning

- **vs data-warehouse semantic tools:** require a human to keep the layer current on every schema change. Shanc does it.

## Adoption

Used by data teams across fintech, retail, foodtech, e-commerce, online rental, and meta-search. Reported: a fintech (Philippines) saved 10+ hours/week per data worker and significantly improved search quality.