# Enterprise Customer Success Dashboard: Notion MCP Integration

## Overview
This repository demonstrates a secure AI architecture that leverages a custom Model Context Protocol (MCP) framework to allow local developer agents to securely interact with a Notion-backed CRM database. 

Built as a proof-of-concept for enterprise deployment, the primary objective is to enable natural language querying of proprietary client health data directly within secure terminal environments, establishing Notion as the system of record for technical deployment tracking.

## Key Features & Notion Integration

### 1. Database Generation via Notion AI
The foundational schema for the Enterprise Customer Success Dashboard was rapidly prototyped and generated utilizing **Notion AI**. By prompting Notion AI with our core business requirements, it automatically structured a robust relational database tracking:
*   **Client Name**
*   **Annual Recurring Revenue (ARR)**
*   **Health Score** (Healthy, At Risk, Escalated, Onboarding)
*   **Target Product**
*   **Deployment Roadblocks**

**📍 View the Database Schema:** Because the live database requires authenticated API access, a full export of the Notion AI-generated structure and mock data is available in this repository under `data/mock_client_data.csv`. This provides a tangible look at the exact functional data structure produced by Notion AI.

### 2. Custom MCP Middleware
To securely expose this Notion data to local AI agents without hardcoding API requests into every prompt, I engineered a custom **Model Context Protocol (MCP)** library. 
*   **Working proof of concept:** This custom MCP library acts as middleware, enabling LLMs to fetch client health data and evaluate deployment bottlenecks from a Notion database. It runs end to end against the included mock dataset — see the Example below.
*   **Zero-Trust Security:** The architecture strictly separates local execution from external context. The Notion API keys remain locally vaulted, ensuring proprietary CRM data can be queried by the AI without leaking credentials to external or public environments.

## Architecture & Workflow
1. **System of Record:** Notion hosts the CRM database, maintaining the single source of truth for client deployment statuses and ARR metrics.
2. **The MCP Bridge:** The custom TypeScript/Node.js MCP server intercepts natural language queries from the local agent.
3. **Execution:** The agent securely reads the Notion database to instantly evaluate high-ARR client statuses and summarize technical deployment bottlenecks, streamlining client success workflows.

## Example

End-to-end run of the `get-client-health-dashboard` tool against the included mock dataset (`data/mock_client_data.csv`), driven through the headless harness in `packages/test-integration`: a real MCP handshake over stdio, a real `tools/call`, and a real fetch against a local Notion-shaped API serving the mock data. No stubs.

**Natural-language query:** "Which clients are At Risk right now, and what's blocking their deployments?"

**Agent action:** calls the `get-client-health-dashboard` tool (no arguments — it fetches the full board).

**Tool response** (6 records returned; 2 shown, roadblocks trimmed):

```json
[
  {
    "client": "NorthBridge Capital Markets",
    "status": "At Risk",
    "arr": 3250000,
    "product": "IBM Cloud Pak for Data",
    "roadblock": "Custom Spark-on-Kubernetes ETL jobs intermittently fail after executor reschedules…"
  },
  {
    "client": "Apex Manufacturing Group",
    "status": "Healthy",
    "arr": 5800000,
    "product": "Red Hat OpenShift",
    "roadblock": "RBAC provisioning on OpenShift is desynchronized from Active Directory…"
  }
]
```

**Agent summary** — the harness filters for At Risk clients and renders a triage report:

```markdown
# CSCE Triage Report — At Risk Clients

_Generated: 2026-10-06 22:35:53 UTC_

> ⚠️  **2 clients flagged At Risk** out of 6 total — review before your triage meeting.

---

## 1. NorthBridge Capital Markets

| Field                    | Value |
|--------------------------|-------|
| **Health Status**        | ⚠️ At Risk |
| **ARR**                  | $3.25M |
| **Target Product**       | IBM Cloud Pak for Data |
| **Deployment Roadblock** | Custom Spark-on-Kubernetes ETL jobs intermittently fail after executor reschedules due to a mismatch between the shaded Hadoop-aws JAR (S3A) and the cluster's IAM credential provider chain; failures cascade into Delta Lake checkpoint corruption (inconsistent _delta_log JSON) and leave orphaned staging objects, causing downstream CDC reconciliation to drift by ~2–4M rows per run. |

---

## 2. Redwood Government Services

| Field                    | Value |
|--------------------------|-------|
| **Health Status**        | ⚠️ At Risk |
| **ARR**                  | $2.90M |
| **Target Product**       | watsonx.data |
| **Deployment Roadblock** | Air-gapped deployment blocked by security controls: the enclave requires offline artifact promotion with signed SBOMs (CycloneDX) and FIPS-validated cryptography. |
```

The same code path queries a live Notion database when `NOTION_API_KEY` and `NOTION_DATABASE_ID` are set — see Setup below.

## Getting Started

### Prerequisites
* Node.js (v18+)
* A Notion Integration API Key
* A Notion Database ID

### Setup
1. Clone this repository.
2. Run `npm install` (or `pnpm install`) to install dependencies.
3. Copy the `.env.example` file and rename it to `.env`. 
4. Insert your secure Notion API credentials into the new `.env` file. (Note: `.env` is git-ignored to prevent credential leaks).

## Author
**Arnav Kharya**