# MCP Data Catalog Server

An [MCP](https://modelcontextprotocol.io) server exposing tools over a synthetic
enterprise data catalog: asset search with a composable AND/OR filter DSL,
lineage, sample data, profiling, history, quality rules, and AI-driven
classification (CDE detection, PII tagging, business-term generation).

> Independent, from-scratch reimplementation of a system design I built in a
> professional context — synthetic catalog data, no proprietary business logic,
> for portfolio/demo purposes. Not affiliated with, and contains no code or data
> from, any employer or client.

## What it demonstrates

- **Composable AND/OR filter DSL** (`src/catalog/filter_dsl.py`) — asset search
  takes a nested `{"and": [...]}` / `{"or": [...]}` filter tree instead of a fixed
  set of query parameters, so callers can express arbitrary boolean combinations
  of field predicates without the tool schema growing per use case.
- **Heuristic-first classification with AI fallback**
  (`src/catalog/classification.py`) — Critical Data Element (CDE) detection runs
  cheap heuristics (name/type pattern matching) first and only calls the
  (stubbed) AI classifier when the heuristics are inconclusive; PII tagging is
  fully AI-driven from asset metadata.
- **Business-term generation validated against governance heuristics**
  (`src/catalog/business_terms.py`) — candidate terms are matched to catalog
  assets via cosine similarity over embeddings, then filtered through governance
  rules (naming convention, domain allowlist) before being surfaced for
  publishing.
- **MCP tool surface** (`src/tools/`) — search, lineage, sample data, profiling,
  history, quality rules, CDE classification, PII classification, and business
  term generation, registered on a real `mcp` SDK server in `src/server.py`.

## Running it

```bash
python -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
pip install -r requirements.txt
python -m src.main
```

The server runs over stdio, ready to be added to an MCP client (e.g. Claude
Desktop or Claude Code) config pointing at `python -m src.main` in this
directory. All catalog data is synthetic and generated in-process — no external
database required.

```bash
pytest
```

## Project layout

```
src/
  main.py               # entrypoint
  server.py              # MCP server + tool registration
  catalog/
    store.py              # in-memory synthetic catalog
    models.py              # Asset, LineageEdge, QualityRule
    filter_dsl.py            # AND/OR filter tree evaluator
    classification.py         # heuristic-first CDE + AI-driven PII
    business_terms.py          # embedding similarity + governance validation
  tools/
    search.py, lineage.py, sample_data.py, profiling.py,
    history.py, quality_rules.py, classification_tools.py,
    business_term_tool.py
tests/
```