Student Founder Governor 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

npm install

Build

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:

{
  "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:

{
  "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:

{
  "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:

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

Output (Success):

{
  "ok": true
}

Output (Violations):

{
  "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:

{
  "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:

{
  "decision_type": "OVERRIDE_CAPACITY",
  "reason": "Critical deadline for investor meeting",
  "predicted_risk": "HIGH"
}

Output:

{
  "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