Metadata-Version: 2.5
Name: semantic-warehouse-mcp
Version: 0.2.0
Summary: A read-only MCP server for SQL databases with a semantic layer in an open format (Apache Ossie), metrics, your own context and skills — for any database and any MCP client.
Project-URL: Repository, https://github.com/alexeiveselov92/semantic-warehouse-mcp
Project-URL: Documentation, https://github.com/alexeiveselov92/semantic-warehouse-mcp/blob/main/docs/README.md
Project-URL: Changelog, https://github.com/alexeiveselov92/semantic-warehouse-mcp/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/alexeiveselov92/semantic-warehouse-mcp/issues
Author: Aleksei Veselov
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,mcp,metrics,model-context-protocol,ossie,semantic-layer,sql
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: duckdb>=1.3
Requires-Dist: httpx>=0.28
Requires-Dist: jsonschema>=4.23
Requires-Dist: mcp<3,>=2.3
Requires-Dist: pyyaml>=6
Requires-Dist: sqlglot>=27
Requires-Dist: starlette>=0.46
Requires-Dist: uvicorn>=0.34
Description-Content-Type: text/markdown

# semantic-warehouse-mcp

A read-only [MCP](https://modelcontextprotocol.io) server that lets any AI agent work with SQL databases
the way an analyst does: knowing what the data means. You give it your semantic model in an open format
([Apache Ossie](https://ossie.apache.org/), formerly OSI), your own metadata, context and documents — and
it lets agents find the right tables, read what they mean and query them, safely.

> **Status: pre-alpha** — working, and used on real warehouses; its interfaces may still change. Metrics, saved query
> sets and more databases are on their way ([the plan](https://github.com/alexeiveselov92/semantic-warehouse-mcp/blob/main/dev/PLAN.md)).

## What it does now

- **ClickHouse and DuckDB**, configured in one YAML file: the tables agents may read, the large tables a query must
  bound, limits per query; secrets by variable name, never written in it.
- **Read-only, checked twice**: one `SELECT` at a time, parsed for the database's own dialect by
  [sqlglot](https://github.com/tobymao/sqlglot) and by the database itself; only the tables you allow, wherever they
  are read; large tables bounded; rows and time capped, never cut without saying so — on top of a read-only database
  user. Every answer carries the SQL as it ran and when.
- **A semantic layer in Apache Ossie**: datasets, fields, relationships and metrics, with `ai_context` for agents and
  `custom_extensions` for anything of your own — categories, layers, links to code, owners — checked against a
  vocabulary you declare and served with what each value means.
- **An importer from dbt**: `semantic-warehouse-mcp import-dbt` writes your dbt project's tables, descriptions, `meta`
  and tags as an Ossie model — the mapping yours, in its configuration.
- **Your own context and skills**: instructions, documents and skills (the [Agent Skills](https://agentskills.io)
  format: a folder with a `SKILL.md` and the files it refers to) served to agents as written — from disk, or straight
  from a git repository, kept fresh.
- **Any MCP client**: stdio for one person's agent, Streamable HTTP for a server a team shares (a token on every
  request, `/health`, a container image).

## Install

```bash
uvx semantic-warehouse-mcp --config config.yaml --check     # check a configuration, reach every database
uvx semantic-warehouse-mcp --config config.yaml             # serve over stdio
pip install semantic-warehouse-mcp                          # or install it
```

Connect Claude Code (any client that runs stdio servers takes the same command):

```bash
claude mcp add warehouse -- uvx semantic-warehouse-mcp --config /path/to/config.yaml
```

## Documentation

**[swm.pipelab.dev](https://swm.pipelab.dev)** — the guide, built from
[docs/](https://github.com/alexeiveselov92/semantic-warehouse-mcp/blob/main/docs/README.md):

- [Getting started](https://github.com/alexeiveselov92/semantic-warehouse-mcp/blob/main/docs/getting-started.md) — from
  nothing to an agent answering about a made-up shop's data.
- [The guide](https://github.com/alexeiveselov92/semantic-warehouse-mcp/blob/main/docs/README.md): tools,
  configuration, semantic models and vocabularies, the dbt importer, the guard, engines, running it.

## Why

An agent with a bare SQL connection writes plausible queries over the wrong tables. What makes its answers
right is semantics: what a table holds, which column is the date, how a metric is defined, what not to mix.
That knowledge already exists in teams — in dbt projects, semantic layers, wikis — but every tool wants it in
its own shape. This server reads it in an open, vendor-neutral format and serves it beside the data.

## Development

Python 3.12, [uv](https://docs.astral.sh/uv/), the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).

```bash
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run python examples/data/make_shop.py    # the made-up shop the examples describe
uv run semantic-warehouse-mcp --config examples/config.example.yaml   # the server over stdio
```

## License

[Apache-2.0](https://github.com/alexeiveselov92/semantic-warehouse-mcp/blob/main/LICENSE).
