<p align="center">
  <img src="logo.png" alt="Sybil MCP — Notion Risk Intelligence Server" width="400"/>
</p>

# 🧠 Sybil MCP — Notion Risk Intelligence Server

Sybil is an MCP (Model Context Protocol) server that monitors your Notion databases in real time and detects financial risks: when an Engineering task is delayed and overlaps with a Marketing campaign launch, Sybil automatically creates an alert in your Notion Alert Center.

---

## ⚡ Quick Start

**You don't need to run anything manually.** Claude Desktop manages the server automatically.

1. Make sure your `claude_desktop_config.json` is configured (see Configuration section)
2. Open Claude Desktop — the server starts on its own in the background
3. Ask Claude: *"What risks does Sybil detect?"*

> ⚠️ **Never run `node index.js` manually** while Claude Desktop is open. It would create two server instances running in parallel and duplicate alerts in Notion.

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      Claude Desktop                         │
│                                                             │
│   ┌─────────────┐   MCP Protocol   ┌────────────────────┐  │
│   │  Claude AI  │ ◄──────────────► │  Sybil MCP Server  │  │
│   │  (chat)     │   (stdin/stdout)  │  (node index.js)   │  │
│   └─────────────┘                  └────────┬───────────┘  │
│                                             │               │
└─────────────────────────────────────────────┼───────────────┘
                                              │ HTTPS
                                    ┌─────────▼──────────┐
                                    │    Notion API       │
                                    │  ┌──────────────┐  │
                                    │  │ Engineering  │  │
                                    │  │   Database   │  │
                                    │  ├──────────────┤  │
                                    │  │  Marketing   │  │
                                    │  │   Database   │  │
                                    │  ├──────────────┤  │
                                    │  │ Alert Center │  │
                                    │  │   Database   │  │
                                    │  └──────────────┘  │
                                    └────────────────────┘
```

### Components

| Component | Description |
|---|---|
| **Claude Desktop** | Manages the MCP server lifecycle automatically |
| **Sybil MCP Server** | Node.js process running in the background. Monitors Notion every 10 seconds |
| **Notion API** | Data source and destination for alerts. All via HTTPS |
| **`.sybil-alerts.json`** | Local file that remembers which alerts have already been created (persists across restarts) |
| **`.sybil-lock`** | Lock file that prevents two server instances from running simultaneously |

---

## 🔄 How It Works Internally

### 1. Automatic startup
When you open Claude Desktop, it reads `claude_desktop_config.json` and launches `node index.js` automatically. The server:
- Loads the alert history from `.sybil-alerts.json` (if it exists)
- Connects to Claude via MCP (stdin/stdout)
- Starts background monitoring immediately

### 2. Background monitoring every 10 seconds (no token usage)
The server runs a watch cycle every 10 seconds, completely independent from Claude:

```
Every 10s:
  1. Read Engineering DB → look for tasks with status "Delayed"
  2. Read Marketing DB   → (in parallel with step 1)
  3. For each delayed task × campaign:
       - Is Launch Date <= Due Date? → risk detected
       - Already in .sybil-alerts.json? → skip (no duplicates)
       - Already exists in Notion (filter query)? → skip
       - If not found: create comment + row in Alert Center
```

> 🔑 **This cycle does NOT consume Claude tokens.** It makes direct HTTP calls to the Notion API.

### 3. Tool call from Claude (tokens ARE used here)
When you ask Claude about risks, Claude calls the `check_sybil_risk` tool. This:
- Runs the same analysis cycle immediately on demand
- Returns a text summary to Claude
- Claude uses that text to respond to you

**Only this step uses tokens** (the processing of Claude's response in your conversation).

### 4. Anti-duplicate protection (3 layers)
To prevent duplicate alerts from being created in Notion:

| Layer | Mechanism | Purpose |
|---|---|---|
| **Layer 1** | `isProcessing` flag | Prevents two cycles from running concurrently |
| **Layer 2** | `.sybil-alerts.json` (disk) | Remembers alerts across server restarts |
| **Layer 3** | Notion filter query | Confirms against Notion if the file doesn't have it |

---

## ⚙️ Configuration

The Claude Desktop config file is located at:
```
C:\Users\[YOUR_USER]\AppData\Roaming\Claude\claude_desktop_config.json
```

```json
{
  "mcpServers": {
    "sybil": {
      "command": "node",
      "args": ["C:/Users/USUARIO/Desktop/sybil-mcp/index.js"],
      "env": {
        "NOTION_TOKEN": "your_token_here",
        "ID_ENGINEERING": "your_engineering_database_id",
        "ID_MARKETING": "your_marketing_database_id",
        "ID_ALERTAS": "your_alert_center_database_id",
        "ID_SALES": "your_sales_database_id"
      }
    }
  }
}
```

> Environment variables can also be defined in a `.env` file in the project folder.

---

## 🔧 How to Update the Code

After making changes to `index.js`:

1. Save the file
2. **Fully quit Claude Desktop**
   - Right-click the system tray icon → **Quit**
   - (Do not just close the window)
3. Reopen Claude Desktop
4. Claude will automatically start the server with the new code

> ✅ To confirm the new code is active, ask Claude: *"Check risks with Sybil"*. You'll see no new duplicates appear in the Notion Alert Center.

---

## 📁 Project Files

```
sybil-mcp/
├── index.js              ← Main MCP server
├── .env                  ← Environment variables (do not commit to git)
├── .sybil-alerts.json    ← Alert history (auto-generated)
├── .sybil-lock           ← Active process lock (auto-generated)
├── .gitignore
└── README.md
```

### Auto-generated files

| File | Description | Can I delete it? |
|---|---|---|
| `.sybil-alerts.json` | History of already-created alerts | Yes, but the server will recreate alerts on next run |
| `.sybil-lock` | Indicates an active server instance | Only if the server crashed and left it behind |

---

## 🩺 Troubleshooting

**Duplicate alerts still appearing in Notion?**
- Make sure only ONE instance of Claude Desktop is open
- Fully restart Claude Desktop (Quit, don't just close the window)
- Delete `.sybil-alerts.json` if it contains stale data from previous buggy sessions

**No alerts appearing in Notion?**
- Verify your `NOTION_TOKEN` has access to all 3 databases
- Confirm Engineering tasks have exactly the status `"Delayed"`
- Confirm Marketing campaigns have a `Launch Date` set

**Claude says it can't find the `check_sybil_risk` tool?**
- Restart Claude Desktop to reload the MCP server
- Verify the path in `claude_desktop_config.json` is correct

---

## 💡 Does background monitoring consume tokens?

**No.** The `setInterval` running every 10 seconds makes direct HTTP calls to the Notion API. Claude is not involved in that process.

Tokens are only consumed when:
- You send a message to Claude in the chat
- Claude decides to call the `check_sybil_risk` tool to answer you

Background monitoring is completely free in terms of Claude tokens.