# Semantic BI MCP

**Model Context Protocol (MCP) server** that gives AI assistants a safe, correct data-analyst capability over business metrics - without raw SQL improvisation.

> *Talk to your data in plain English. Get answers that are always correct and can never break anything.*

## What makes this different

Most data MCPs expose a raw SQL runner and let the model improvise. That miscounts, mis-joins, ignores soft-deletes, and can mutate or leak data.

**This project does the opposite:** a **semantic layer**. Every business metric is defined once as vetted SQL in `lib/metrics.ts` and exposed as an MCP tool. The model assembles answers from correct building blocks. Guardrails (read-only, caps, PII masking, audit log) are first-class features.

## Architecture

One Next.js app, four layers:

| Layer | Path | Purpose |
| --- | --- | --- |
| MCP server | `app/api/[transport]/route.ts` | Tools, resources, prompts at `/api/mcp` |
| Semantic layer | `lib/` | sql.js dataset, metrics, guards, audit, auth |
| LangChain agent | `app/api/chat/route.ts` | `gpt-4o-mini` -> MCP over HTTP |
| Chat UI | `app/page.tsx` + `components/` | Live tool-call visualization |

## Tech stack

- **Next.js 15** (App Router), TypeScript, Tailwind CSS 4
- **MCP:** `mcp-handler` + `@modelcontextprotocol/sdk@^1.26`
- **Data:** `sql.js` (WASM SQLite, serverless-safe)
- **Agent:** `@langchain/mcp-adapters`, `@langchain/langgraph`, `@langchain/openai`
- **Deploy:** Vercel Pro + Fluid compute

## Quick start

See **[INSTALLATION.md](./INSTALLATION.md)** for full setup including environment variables.

```bash
npm install
cp .env.example .env.local   # fill in keys
npm run dev
```

- **Chat UI:** http://localhost:3000
- **MCP endpoint:** http://localhost:3000/api/mcp
- **MCP Inspector:** `npx @modelcontextprotocol/inspector`

## MCP capabilities

### Tools (11)

| Tool | Description |
| --- | --- |
| `get_mrr` | Monthly Recurring Revenue |
| `get_arr` | Annual Recurring Revenue |
| `get_churn_rate` | Subscription churn % |
| `get_active_subscriptions` | Active/trialing count by tier |
| `get_new_customers` | New customer acquisitions |
| `get_revenue_by_plan` | Paid revenue by plan |
| `get_customer_count` | Active customer count |
| `get_net_revenue_retention` | NRR between two months |
| `safe_query` | Read-only SELECT on whitelisted views |
| `list_metrics` | Metric catalog |
| `get_audit_log` | Recent tool invocations |

### Resources (3)

- `dataset://schema` - table/view definitions
- `semantic-layer://catalog` - metric catalog JSON
- `dataset://stats` - dataset overview

### Prompts (3)

- `executive-summary` - monthly SaaS health summary
- `mrr-trend-analysis` - compare two months
- `churn-investigation` - structured churn analysis

## Security

See **[SECURITY.md](./SECURITY.md)** for the full security audit and status.

## Project docs

- **[INSTALLATION.md](./INSTALLATION.md)** - setup and env var guide
- **[SECURITY.md](./SECURITY.md)** - security posture and audit

## License

Neural LB - portfolio / demo use. Dataset is fictional (Northwind SaaS).