# Student Founder Governor MCP Server

A Model Context Protocol (MCP) server designed to help student founders manage their time capacity, validate work plans, and track decision-making patterns. This server provides tools for capacity planning, constraint validation, historical analysis, and decision logging.

## Why a Custom MCP Server?

While Notion AI can generate plans and suggest tasks, it cannot:

- Enforce hard constraints before writing to Notion
- Learn from historical execution failures
- Block actions that violate capacity limits
- Require explicit tradeoffs when overloaded
- Maintain a long-term decision audit trail

This MCP server acts as a **governance layer**, not a suggestion engine.
It allows AI clients like Claude to reason *before* modifying Notion data,
ensuring plans remain realistic and sustainable.

## Demo Flow

This server is designed to support a live demo where:
1. AI checks remaining capacity
2. User attempts to add excessive work
3. The system blocks the action
4. Tradeoffs are negotiated
5. Decisions are logged for learning

See the Notion + Claude demo walkthrough for the full experience.

## Features

### Capacity Management
- Track weekly time capacity and utilization
- Monitor planned vs. available hours
- Real-time status indicators (safe, strained, critical)

### Plan Validation
- Validate plans against hard time constraints
- Enforce daily deep work limits
- Prevent overcommitment with pre-flight checks

### Historical Analytics
- Track 4-week completion rates
- Monitor task overrun patterns
- Identify slip patterns by weekday
- Surface risk flags automatically

### Decision Logging
- Record planning decisions and overrides
- Track predicted risks
- Build an audit trail for future analysis

## Installation

```bash
npm install
```

## Build

```bash
npm run build
# or
npx tsc
```

## Usage

This MCP server is designed to be used with MCP-compatible clients like Claude Desktop or other AI assistants that support the Model Context Protocol.

### Configuration

Add this server to your MCP client configuration:

```json
{
  "mcpServers": {
    "student-founder-governor": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"]
    }
  }
}
```

### State Management

The server maintains a sample state in `dist/store/state.json` with the following structure:

```json
{
  "capacity": {
    "week": "2024-W51",
    "maxHours": 40,
    "plannedHours": 0,
    "deepWorkCapPerDay": 4
  },
  "history": {
    "completionRate4w": 0.75,
    "avgOverrunRatio": 1.2,
    "slipByWeekday": {
      "Monday": 0.5,
      "Tuesday": 0.3
    }
  },
  "decisions": []
}
```

> Note: This file-based state store is used for demonstration purposes.
> In a production setup, this could be replaced with Notion-backed storage
> or an external database.

## Available Tools

### `get_capacity_status`

Returns current capacity metrics and utilization status.

**Input:** None

**Output:**
```json
{
  "week": "2024-W51",
  "max_hours": 40,
  "planned_hours": 28,
  "remaining_hours": 12,
  "utilization_ratio": 0.7,
  "status": "strained"
}
```

**Status Levels:**
- `safe`: < 70% utilization
- `strained`: 70-85% utilization
- `critical`: > 85% utilization

### `validate_plan`

Validates a proposed plan against hard constraints.

**Input:**
```json
{
  "planned_tasks": [
    {
      "id": "task-1",
      "hours": 5,
      "day": "Monday",
      "type": "deep"
    },
    {
      "id": "task-2",
      "hours": 3,
      "day": "Tuesday",
      "type": "shallow"
    }
  ]
}
```

**Output (Success):**
```json
{
  "ok": true
}
```

**Output (Violations):**
```json
{
  "ok": false,
  "violations": [
    {
      "type": "HARD_CAPACITY",
      "message": "Plan exceeds remaining capacity by 5 hours"
    },
    {
      "type": "DAILY_DEEP_WORK",
      "message": "Deep work exceeds daily cap on Monday"
    }
  ]
}
```

**Task Types:**
- `deep`: Deep work requiring focused attention
- `shallow`: Shallow work (admin, email, meetings)

### `get_historical_summary`

Returns historical execution patterns and risk analysis.

**Input:** None

**Output:**
```json
{
  "completion_rate_4w": 0.75,
  "avg_overrun_ratio": 1.2,
  "slip_by_weekday": {
    "Monday": 0.5,
    "Tuesday": 0.3,
    "Wednesday": 0.1
  },
  "risk_flags": [
    "LOW_COMPLETION_RATE",
    "CONSISTENT_UNDERESTIMATION"
  ]
}
```

**Risk Flags:**
- `LOW_COMPLETION_RATE`: Completion rate < 70%
- `CONSISTENT_UNDERESTIMATION`: Average overrun ratio > 1.3

### `log_decision`

Logs a planning or override decision for future analysis.

**Input:**
```json
{
  "decision_type": "OVERRIDE_CAPACITY",
  "reason": "Critical deadline for investor meeting",
  "predicted_risk": "HIGH"
}
```

**Output:**
```json
{
  "ok": true
}
```

The decision is logged with a unique ID and timestamp for future reference.

## Use Cases

### 1. Weekly Planning
```
AI: Let me check your capacity first...
→ get_capacity_status()

AI: You have 12 hours remaining. Let's validate this plan...
→ validate_plan({ planned_tasks: [...] })

AI: Plan looks good! Logging this decision...
→ log_decision({ decision_type: "WEEKLY_PLAN", reason: "..." })
```

### 2. Emergency Override
```
AI: I see you want to add a 10-hour task, but you only have 5 hours left.
→ validate_plan() → violations detected

User: I need to do this anyway, it's critical.

AI: Understood. Logging this override with high risk...
→ log_decision({
    decision_type: "OVERRIDE_CAPACITY",
    reason: "Critical investor deadline",
    predicted_risk: "HIGH"
  })
```

### 3. Historical Analysis
```
AI: Let me review your execution patterns...
→ get_historical_summary()

AI: I notice you have a 75% completion rate and tend to slip on Mondays.
    This suggests you might be overestimating Monday capacity.
```

## Development

### Project Structure

```
mcp-server/
├── src/
│   ├── index.ts              # Main MCP server setup
│   ├── store/
│   │   ├── state.ts          # Type definitions
│   │   └── persistence.ts    # State load/save
│   └── tools/
│       ├── capacity.ts       # Capacity status tool
│       ├── validation.ts     # Plan validation tool
│       ├── history.ts        # Historical analysis tool
│       └── decisions.ts      # Decision logging tool
├── dist/                     # Compiled JavaScript
├── package.json
└── tsconfig.json
```

### Tech Stack

- **Runtime:** Node.js
- **Language:** TypeScript
- **MCP SDK:** @modelcontextprotocol/sdk v1.25.1
- **Validation:** Zod v4.2.1