Submit
LovroBubanic

Semantic BI MCP

Community LovroBubanic
Updated

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

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 for full setup including environment variables.

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

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 for the full security audit and status.

Project docs

  • INSTALLATION.md - setup and env var guide
  • SECURITY.md - security posture and audit

License

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

MCP Server · Populars

MCP Server · New