@gonzih/screen-time-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maksim Soltan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,343 @@
+# screen-time-mcp
+
+An MCP (Model Context Protocol) server that enforces AI usage limits for children. Set daily time caps, quiet hours, weekly budgets, cool-down periods between sessions, gamified streaks, and receive weekly parent reports via Telegram — all without modifying the AI assistant itself.
+
+## Features
+
+- **Daily time caps** — hard stop when the child's daily AI minutes are used up
+- **Per-session limits** — cap individual sessions to encourage breaks between focused work
+- **Weekly budget** — soft warning when the weekly total is reached
+- **Quiet hours** — block AI access at night and in the morning (fully configurable, supports ranges that cross midnight)
+- **Cool-down periods** — require a break between sessions so children step away from the screen
+- **Parent PIN overrides** — grant temporary extra time without changing permanent settings
+- **Gamified streaks** — track consecutive days within limit and celebrate milestones
+- **Banked minutes** — optionally carry unused daily minutes forward as a bonus
+- **Weekly reports** — auto-generate and send a parent summary via Telegram
+- **Daily summaries** — optional end-of-day Telegram digest for parents
+- **Child-friendly messages** — warm, encouraging block messages (never punitive)
+- **Multi-profile support** — run separate profiles for multiple children
+- **SQLite storage** — lightweight, local, no external database required
+
+## Installation
+
+### From npm
+
+```bash
+npm install -g @gonzih/screen-time-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/gonzih/screen-time-mcp
+cd screen-time-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and edit to match your family's needs:
+
+```bash
+cp .env.example .env
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `SCREEN_TIME_PROFILE_ID` | `default` | Child profile identifier (use separate IDs per child) |
+| `SCREEN_TIME_CHILD_NAME` | `Child` | Child's name, used in reports and messages |
+| `SCREEN_TIME_DB` | `~/.screen-time-mcp/usage.sqlite` | Path to the SQLite database file |
+| `DAILY_LIMIT_MINS` | `45` | Daily AI time cap in minutes |
+| `SESSION_LIMIT_MINS` | `30` | Per-session cap in minutes |
+| `WEEKLY_BUDGET_MINS` | `240` | Weekly total budget in minutes (4 hours) |
+| `COOL_DOWN_MINS` | `30` | Required break between sessions in minutes |
+| `PARENT_OVERRIDE_PIN` | `1234` | PIN required to grant temporary extra time |
+| `QUIET_HOURS` | `21:00-07:00` | Comma-separated time ranges; ranges crossing midnight supported |
+| `TELEGRAM_BOT_TOKEN` | _(none)_ | Telegram bot token for parent reports |
+| `TELEGRAM_PARENT_CHAT_ID` | _(none)_ | Parent's Telegram chat ID |
+| `REPORT_DAY` | `sunday` | Day of week to send the weekly report |
+| `DAILY_REPORT` | `false` | Set to `true` to send a Telegram summary after each day |
+| `BANK_UNUSED_TIME` | `false` | Set to `true` to carry unused daily minutes forward |
+
+### Quiet Hours format
+
+Quiet hours are comma-separated `HH:MM-HH:MM` ranges. Ranges that cross midnight are fully supported:
+
+```
+# Night + morning blocks
+QUIET_HOURS=21:00-07:00,07:00-08:00
+
+# Night block only
+QUIET_HOURS=22:00-07:00
+
+# Multiple blocks
+QUIET_HOURS=21:00-07:00,12:00-13:00
+```
+
+### Setting up Telegram reports
+
+1. Message [@BotFather](https://t.me/botfather) on Telegram and create a new bot. Copy the bot token.
+2. Start a conversation with your new bot, then visit `https://api.telegram.org/bot<TOKEN>/getUpdates` to find your chat ID.
+3. Set `TELEGRAM_BOT_TOKEN` and `TELEGRAM_PARENT_CHAT_ID` in your `.env`.
+
+## Claude Desktop Integration
+
+Add the server to your Claude Desktop configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "screen-time-mcp": {
+      "command": "screen-time-mcp",
+      "env": {
+        "SCREEN_TIME_PROFILE_ID": "alex",
+        "SCREEN_TIME_CHILD_NAME": "Alex",
+        "DAILY_LIMIT_MINS": "45",
+        "SESSION_LIMIT_MINS": "30",
+        "WEEKLY_BUDGET_MINS": "240",
+        "COOL_DOWN_MINS": "30",
+        "PARENT_OVERRIDE_PIN": "9876",
+        "QUIET_HOURS": "21:00-07:00,07:00-08:00",
+        "TELEGRAM_BOT_TOKEN": "your-bot-token",
+        "TELEGRAM_PARENT_CHAT_ID": "your-chat-id",
+        "DAILY_REPORT": "true",
+        "BANK_UNUSED_TIME": "true"
+      }
+    }
+  }
+}
+```
+
+If running from source, use the full path instead:
+
+```json
+{
+  "mcpServers": {
+    "screen-time-mcp": {
+      "command": "node",
+      "args": ["/path/to/screen-time-mcp/dist/index.js"],
+      "env": {
+        "SCREEN_TIME_PROFILE_ID": "alex"
+      }
+    }
+  }
+}
+```
+
+### Multi-child setup
+
+Run one server instance per child, each with a distinct profile ID:
+
+```json
+{
+  "mcpServers": {
+    "screen-time-alex": {
+      "command": "screen-time-mcp",
+      "env": {
+        "SCREEN_TIME_PROFILE_ID": "alex",
+        "SCREEN_TIME_CHILD_NAME": "Alex",
+        "DAILY_LIMIT_MINS": "45"
+      }
+    },
+    "screen-time-jamie": {
+      "command": "screen-time-mcp",
+      "env": {
+        "SCREEN_TIME_PROFILE_ID": "jamie",
+        "SCREEN_TIME_CHILD_NAME": "Jamie",
+        "DAILY_LIMIT_MINS": "60"
+      }
+    }
+  }
+}
+```
+
+## MCP Tools Reference
+
+The AI assistant is expected to call these tools automatically according to the session flow described in `SKILL.md`.
+
+### Child-facing tools
+
+| Tool | Parameters | Description |
+|---|---|---|
+| `start_session` | `profileId: string` | Call at conversation start. Returns `allowed`, `sessionId`, and time remaining. If `allowed` is false, show the block message and stop. |
+| `check_limits` | `profileId: string`, `sessionId: string` | Call every message. Returns `withinLimits`, current usage, and any `warning` to relay to the child. |
+| `end_session` | `profileId: string`, `sessionId: string`, `messageCount?: number` | Call at conversation end. Updates daily usage, returns streak info and a closing message for the child. |
+
+### Parent-facing tools (require PIN where noted)
+
+| Tool | Parameters | Description |
+|---|---|---|
+| `get_usage` | `profileId: string`, `days?: number` | View daily usage history, totals, and streak data. |
+| `update_limits` | `profileId: string`, `settings: object` | Update `dailyLimitMins`, `sessionLimitMins`, `weeklyBudgetMins`, or `coolDownMins` at runtime. Changes are in-memory only. |
+| `override_limits` | `profileId: string`, `pin: string`, `extraMinutes: number` | Grant a temporary extension to today's daily limit. Requires parent PIN. |
+| `send_report` | `profileId: string` | Generate the weekly report and send it via Telegram if configured. |
+
+### Session flow
+
+```
+Conversation starts
+      │
+      ▼
+start_session(profileId)
+      │
+      ├── allowed: false → show block message, end conversation
+      │
+      └── allowed: true → store sessionId
+            │
+            ▼ (every message)
+      check_limits(profileId, sessionId)
+            │
+            ├── withinLimits: false → relay warning, wrap up gracefully
+            ├── warning present → mention naturally in reply
+            └── all good → continue
+            │
+            ▼ (conversation ends)
+      end_session(profileId, sessionId, messageCount)
+            │
+            └── share streakMessage with child if present
+```
+
+## How It Works
+
+### Block evaluation order
+
+Limits are checked in this priority order:
+
+1. **Quiet hours** — if the current time falls in a configured quiet range, block immediately with a tailored morning or night message
+2. **Daily cap** — if today's accumulated minutes (including the current session) meet or exceed the daily limit, block
+3. **Weekly budget** — if the weekly total is reached, allow but show a soft warning
+4. **Cool-down period** — at session start only, check if enough time has passed since the last session ended
+5. **5/10-minute warnings** — if the daily remaining time is under 10 minutes, emit a countdown warning
+
+### Gamification
+
+- A streak increments each day the child stays within the daily limit
+- Streaks reset to 0 if the limit is exceeded
+- Milestone messages trigger at day 1 (new streak), day 3, and day 7+
+- If `BANK_UNUSED_TIME=true`, unused daily minutes accumulate as banked minutes that a parent can manually grant as a bonus session
+
+### Parent reports
+
+When `TELEGRAM_BOT_TOKEN` and `TELEGRAM_PARENT_CHAT_ID` are set:
+
+- **Weekly report** — generated on the configured `REPORT_DAY` (or on demand via `send_report`). Includes total time, days within limit, session count, average session length, most active day, and a qualitative insight.
+- **Daily summary** — if `DAILY_REPORT=true`, a brief digest is sent via Telegram after each session ends.
+
+## Healthy Screen Time Guidelines (AAP)
+
+The American Academy of Pediatrics recommends the following for digital media use:
+
+**Ages 6–12**
+- Set consistent daily limits on screen time, including AI tools
+- Prioritize sleep (9–12 hours/night for ages 6–12) — AI time should end well before bedtime
+- Ensure physical activity (60 minutes/day) is not displaced by screen time
+- Use media together when possible; ask children what they're doing with AI
+
+**Teens (13–17)**
+- Negotiate consistent limits collaboratively — teens are more likely to follow rules they helped set
+- Encourage awareness of how much time is spent, not just enforcement
+- Keep devices and AI assistants out of the bedroom at night
+
+**For parents**
+- Model healthy use yourself — children notice how adults interact with technology
+- Treat AI assistants as a tool to be used intentionally, not a constant companion
+- Review weekly reports together with your child as a conversation starter, not a punishment
+
+The default settings in this server (45 min/day, 30 min cool-down, 21:00 quiet hours) are calibrated for the 6–12 age range. Adjust for older children as appropriate.
+
+## Suite Integration
+
+`screen-time-mcp` is designed to work alongside a family of child-safety MCP servers:
+
+### parental-control-mcp
+
+Filters content and topics the AI is allowed to discuss. While `screen-time-mcp` controls *when* and *how long* a child can use AI, `parental-control-mcp` controls *what* they can discuss. Use both together for comprehensive guardrails.
+
+```json
+{
+  "mcpServers": {
+    "screen-time-mcp": { "command": "screen-time-mcp", "env": { ... } },
+    "parental-control-mcp": { "command": "parental-control-mcp", "env": { ... } }
+  }
+}
+```
+
+### attachment-guard-mcp
+
+Monitors for signs of unhealthy emotional attachment to the AI assistant — excessive dependency, replacing human relationships, or distress when access is limited. Complements `screen-time-mcp` by addressing the quality of AI use alongside the quantity.
+
+### ai-mood-journal-mcp
+
+Lets children optionally log how they're feeling after an AI session. Pairs well with `end_session` — after the streak message, invite the child to record a quick mood check-in. Parents can review mood trends alongside usage data from `get_usage`.
+
+### Recommended combined configuration
+
+```json
+{
+  "mcpServers": {
+    "screen-time-mcp": {
+      "command": "screen-time-mcp",
+      "env": {
+        "SCREEN_TIME_PROFILE_ID": "alex",
+        "DAILY_LIMIT_MINS": "45",
+        "BANK_UNUSED_TIME": "true",
+        "TELEGRAM_BOT_TOKEN": "...",
+        "TELEGRAM_PARENT_CHAT_ID": "..."
+      }
+    },
+    "parental-control-mcp": {
+      "command": "parental-control-mcp",
+      "env": { "PROFILE_ID": "alex" }
+    },
+    "attachment-guard-mcp": {
+      "command": "attachment-guard-mcp",
+      "env": { "PROFILE_ID": "alex" }
+    },
+    "ai-mood-journal-mcp": {
+      "command": "ai-mood-journal-mcp",
+      "env": { "PROFILE_ID": "alex" }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+# Run in development mode (no build step)
+npm run dev
+
+# Build TypeScript
+npm run build
+
+# Run the built server
+npm start
+```
+
+The SQLite database is created automatically at the configured path on first run. No migrations are needed — the schema is applied idempotently via `CREATE TABLE IF NOT EXISTS`.
+
+## Publishing to npm
+
+```bash
+# Build first
+npm run build
+
+# Verify the dist/ output looks correct
+ls dist/
+
+# Dry-run to see what will be published
+npm publish --dry-run
+
+# Publish (requires npm login)
+npm login
+npm publish --access public
+```
+
+The `files` field in `package.json` ensures only `dist/` is included in the published package. The `bin` entry makes `screen-time-mcp` available as a global CLI command after install.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details. Author: Maksim Soltan.

package/dist/config.js

@@ -0,0 +1,31 @@
+import { homedir } from 'os';
+import { join } from 'path';
+function parseQuietHours(raw) {
+    if (!raw)
+        return [];
+    return raw.split(',').map(range => {
+        const [start, end] = range.trim().split('-');
+        return { start, end };
+    });
+}
+export function loadConfig() {
+    const dbPath = process.env.SCREEN_TIME_DB
+        ? process.env.SCREEN_TIME_DB.replace(/^~/, homedir())
+        : join(homedir(), '.screen-time-mcp', 'usage.sqlite');
+    return {
+        profileId: process.env.SCREEN_TIME_PROFILE_ID || 'default',
+        childName: process.env.SCREEN_TIME_CHILD_NAME || 'Child',
+        dbPath,
+        dailyLimitMins: Number(process.env.DAILY_LIMIT_MINS || 45),
+        sessionLimitMins: Number(process.env.SESSION_LIMIT_MINS || 30),
+        weeklyBudgetMins: Number(process.env.WEEKLY_BUDGET_MINS || 240),
+        coolDownMins: Number(process.env.COOL_DOWN_MINS || 30),
+        parentOverridePin: process.env.PARENT_OVERRIDE_PIN || '1234',
+        quietHours: parseQuietHours(process.env.QUIET_HOURS || '21:00-07:00'),
+        telegramBotToken: process.env.TELEGRAM_BOT_TOKEN || null,
+        telegramParentChatId: process.env.TELEGRAM_PARENT_CHAT_ID || null,
+        reportDay: (process.env.REPORT_DAY || 'sunday').toLowerCase(),
+        dailyReport: process.env.DAILY_REPORT === 'true',
+        bankUnusedTime: process.env.BANK_UNUSED_TIME === 'true',
+    };
+}

package/dist/db.js

@@ -0,0 +1,148 @@
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'fs';
+import { dirname } from 'path';
+let _db = null;
+export function getDb(dbPath) {
+    if (_db)
+        return _db;
+    mkdirSync(dirname(dbPath), { recursive: true });
+    _db = new Database(dbPath);
+    _db.pragma('journal_mode = WAL');
+    initSchema(_db);
+    return _db;
+}
+function initSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      profile_id TEXT NOT NULL,
+      started_at TEXT NOT NULL,
+      ended_at TEXT,
+      duration_mins REAL,
+      messages_exchanged INTEGER DEFAULT 0
+    );
+
+    CREATE TABLE IF NOT EXISTS daily_usage (
+      profile_id TEXT,
+      date TEXT,
+      total_mins REAL DEFAULT 0,
+      session_count INTEGER DEFAULT 0,
+      PRIMARY KEY (profile_id, date)
+    );
+
+    CREATE TABLE IF NOT EXISTS weekly_reports (
+      profile_id TEXT,
+      week_start TEXT,
+      total_mins REAL,
+      days_active INTEGER,
+      avg_session_mins REAL,
+      longest_session_mins REAL,
+      report_text TEXT,
+      sent_at TEXT,
+      PRIMARY KEY (profile_id, week_start)
+    );
+
+    CREATE TABLE IF NOT EXISTS overrides (
+      id TEXT PRIMARY KEY,
+      profile_id TEXT NOT NULL,
+      granted_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL,
+      extra_minutes REAL NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS streaks (
+      profile_id TEXT PRIMARY KEY,
+      current_streak INTEGER DEFAULT 0,
+      last_streak_date TEXT,
+      longest_streak INTEGER DEFAULT 0,
+      banked_mins REAL DEFAULT 0
+    );
+  `);
+}
+export function insertSession(db, session) {
+    db.prepare(`
+    INSERT INTO sessions (id, profile_id, started_at, messages_exchanged)
+    VALUES (?, ?, ?, 0)
+  `).run(session.id, session.profile_id, session.started_at);
+}
+export function getSession(db, sessionId) {
+    return db.prepare('SELECT * FROM sessions WHERE id = ?').get(sessionId);
+}
+export function endSession(db, sessionId, endedAt, durationMins, messageCount) {
+    db.prepare(`
+    UPDATE sessions SET ended_at = ?, duration_mins = ?, messages_exchanged = ? WHERE id = ?
+  `).run(endedAt, durationMins, messageCount, sessionId);
+}
+export function getLastEndedSession(db, profileId) {
+    return db.prepare(`
+    SELECT * FROM sessions WHERE profile_id = ? AND ended_at IS NOT NULL ORDER BY ended_at DESC LIMIT 1
+  `).get(profileId);
+}
+export function getActiveSession(db, profileId) {
+    return db.prepare(`
+    SELECT * FROM sessions WHERE profile_id = ? AND ended_at IS NULL ORDER BY started_at DESC LIMIT 1
+  `).get(profileId);
+}
+export function getDailyUsage(db, profileId, date) {
+    const row = db.prepare('SELECT * FROM daily_usage WHERE profile_id = ? AND date = ?').get(profileId, date);
+    return row || { profile_id: profileId, date, total_mins: 0, session_count: 0 };
+}
+export function upsertDailyUsage(db, profileId, date, addMins, addSessions) {
+    db.prepare(`
+    INSERT INTO daily_usage (profile_id, date, total_mins, session_count)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(profile_id, date) DO UPDATE SET
+      total_mins = total_mins + excluded.total_mins,
+      session_count = session_count + excluded.session_count
+  `).run(profileId, date, addMins, addSessions);
+}
+export function getUsageRange(db, profileId, fromDate, toDate) {
+    return db.prepare(`
+    SELECT * FROM daily_usage WHERE profile_id = ? AND date >= ? AND date <= ? ORDER BY date ASC
+  `).all(profileId, fromDate, toDate);
+}
+export function getWeeklyTotal(db, profileId, weekStart, weekEnd) {
+    const row = db.prepare(`
+    SELECT COALESCE(SUM(total_mins), 0) as total FROM daily_usage
+    WHERE profile_id = ? AND date >= ? AND date <= ?
+  `).get(profileId, weekStart, weekEnd);
+    return row.total;
+}
+export function insertOverride(db, override) {
+    db.prepare(`
+    INSERT INTO overrides (id, profile_id, granted_at, expires_at, extra_minutes)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(override.id, override.profile_id, override.granted_at, override.expires_at, override.extra_minutes);
+}
+export function getActiveOverride(db, profileId, now) {
+    return db.prepare(`
+    SELECT * FROM overrides WHERE profile_id = ? AND expires_at > ? ORDER BY expires_at DESC LIMIT 1
+  `).get(profileId, now);
+}
+export function getStreak(db, profileId) {
+    const row = db.prepare('SELECT * FROM streaks WHERE profile_id = ?').get(profileId);
+    return row || { profile_id: profileId, current_streak: 0, last_streak_date: null, longest_streak: 0, banked_mins: 0 };
+}
+export function upsertStreak(db, streak) {
+    db.prepare(`
+    INSERT INTO streaks (profile_id, current_streak, last_streak_date, longest_streak, banked_mins)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(profile_id) DO UPDATE SET
+      current_streak = excluded.current_streak,
+      last_streak_date = excluded.last_streak_date,
+      longest_streak = excluded.longest_streak,
+      banked_mins = excluded.banked_mins
+  `).run(streak.profile_id, streak.current_streak, streak.last_streak_date, streak.longest_streak, streak.banked_mins);
+}
+export function insertWeeklyReport(db, report) {
+    db.prepare(`
+    INSERT OR REPLACE INTO weekly_reports
+      (profile_id, week_start, total_mins, days_active, avg_session_mins, longest_session_mins, report_text, sent_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(report.profile_id, report.week_start, report.total_mins, report.days_active, report.avg_session_mins, report.longest_session_mins, report.report_text, report.sent_at);
+}
+export function getSessionsForWeek(db, profileId, weekStart, weekEnd) {
+    return db.prepare(`
+    SELECT * FROM sessions WHERE profile_id = ? AND started_at >= ? AND started_at <= ? AND ended_at IS NOT NULL
+  `).all(profileId, weekStart, weekEnd);
+}

package/dist/gamification.js

@@ -0,0 +1,80 @@
+import { getStreak, upsertStreak } from './db.js';
+function yesterday(dateStr) {
+    const d = new Date(dateStr);
+    d.setDate(d.getDate() - 1);
+    return d.toISOString().split('T')[0];
+}
+export function updateStreak(db, config, profileId, today, dailyMinsUsed, dailyLimit) {
+    const streak = getStreak(db, profileId);
+    const withinLimit = dailyMinsUsed <= dailyLimit;
+    let newStreak = streak.current_streak;
+    let bankedMins = streak.banked_mins;
+    if (withinLimit && streak.last_streak_date) {
+        const expectedYesterday = yesterday(today);
+        if (streak.last_streak_date === expectedYesterday) {
+            // Continuing streak
+            newStreak = streak.current_streak + 1;
+        }
+        else if (streak.last_streak_date === today) {
+            // Already updated today
+            newStreak = streak.current_streak;
+        }
+        else {
+            // Broke streak
+            newStreak = 1;
+        }
+    }
+    else if (withinLimit) {
+        newStreak = 1;
+    }
+    else {
+        // Over limit, reset streak
+        newStreak = 0;
+    }
+    // Bank unused time if configured
+    if (config.bankUnusedTime && withinLimit) {
+        const saved = dailyLimit - dailyMinsUsed;
+        if (saved > 0) {
+            bankedMins = streak.banked_mins + saved;
+        }
+    }
+    const longestStreak = Math.max(streak.longest_streak, newStreak);
+    const updated = {
+        profile_id: profileId,
+        current_streak: newStreak,
+        last_streak_date: today,
+        longest_streak: longestStreak,
+        banked_mins: bankedMins,
+    };
+    upsertStreak(db, updated);
+    let streakMessage;
+    if (newStreak >= 7) {
+        streakMessage = `🔥 ${newStreak} days in a row of staying within your limit! You're absolutely crushing it!`;
+    }
+    else if (newStreak >= 3) {
+        streakMessage = `🔥 Day ${newStreak} in a row of staying within your limit! Keep it up!`;
+    }
+    else if (newStreak === 1 && streak.current_streak === 0) {
+        streakMessage = `✨ Great job staying within your limit today! That's how streaks start!`;
+    }
+    return { currentStreak: newStreak, longestStreak, streakMessage, bankedMins };
+}
+export function getChildWeeklySummary(totalMins, streak, dailyLimit) {
+    const hours = Math.floor(totalMins / 60);
+    const mins = Math.round(totalMins % 60);
+    const timeStr = hours > 0 ? `${hours}h ${mins}min` : `${mins}min`;
+    let summary = `📊 This week you used AI for ${timeStr}.`;
+    if (streak.current_streak >= 5) {
+        summary += ` You're on a ${streak.current_streak}-day streak of staying within your limit — that's amazing self-regulation! 🏆`;
+    }
+    else if (streak.current_streak >= 3) {
+        summary += ` You're on a ${streak.current_streak}-day streak! 🔥 You're getting really good at wrapping up on time.`;
+    }
+    else {
+        summary += ` You're getting the hang of managing your AI time!`;
+    }
+    if (streak.banked_mins > 0) {
+        summary += ` You've banked ${Math.round(streak.banked_mins)} saved minutes for a future bonus day! 🌟`;
+    }
+    return summary;
+}

package/dist/index.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { randomUUID } from 'crypto';
+import { loadConfig } from './config.js';
+import { getDb, insertSession, endSession, getDailyUsage, getUsageRange, upsertDailyUsage, insertOverride, getStreak } from './db.js';
+import { checkLimits, checkSessionCap } from './limits.js';
+import { updateStreak } from './gamification.js';
+import { sendWeeklyReport, buildDailySummary, sendTelegram } from './reports.js';
+const config = loadConfig();
+const db = getDb(config.dbPath);
+const server = new McpServer({
+    name: 'screen-time-mcp',
+    version: '0.1.0',
+});
+// ─── start_session ───────────────────────────────────────────────────────────
+server.tool('start_session', 'Call at the start of every AI session. Checks if the session is allowed based on configured limits.', {
+    profileId: z.string().describe('Child profile ID'),
+}, async ({ profileId }) => {
+    const limitCheck = checkLimits(db, config, profileId);
+    if (!limitCheck.allowed) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        allowed: false,
+                        reason: limitCheck.reason,
+                        message: limitCheck.message,
+                        minutesUsedToday: limitCheck.minutesUsedToday,
+                        minutesRemainingToday: limitCheck.minutesRemainingToday,
+                    }),
+                }],
+        };
+    }
+    const sessionId = randomUUID();
+    const now = new Date().toISOString();
+    insertSession(db, { id: sessionId, profile_id: profileId, started_at: now });
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    allowed: true,
+                    sessionId,
+                    minutesRemainingToday: limitCheck.minutesRemainingToday,
+                    minutesUsedToday: limitCheck.minutesUsedToday,
+                    weeklyMinsRemaining: limitCheck.weeklyMinsRemaining,
+                    warningMessage: limitCheck.warning,
+                }),
+            }],
+    };
+});
+// ─── check_limits ─────────────────────────────────────────────────────────────
+server.tool('check_limits', 'Call periodically (every message) and at session end to check if limits are still within bounds.', {
+    profileId: z.string().describe('Child profile ID'),
+    sessionId: z.string().describe('Active session ID from start_session'),
+}, async ({ profileId, sessionId }) => {
+    const limitCheck = checkLimits(db, config, profileId, sessionId);
+    const sessionCheck = checkSessionCap(db, config, sessionId);
+    const withinLimits = limitCheck.allowed && !sessionCheck.overCap;
+    let warning = limitCheck.warning;
+    if (sessionCheck.overCap) {
+        warning = sessionCheck.message;
+    }
+    if (!limitCheck.allowed) {
+        warning = limitCheck.message;
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    withinLimits,
+                    minutesUsedToday: limitCheck.minutesUsedToday,
+                    minutesRemaining: limitCheck.minutesRemainingToday,
+                    weeklyMinsUsed: limitCheck.weeklyMinsUsed,
+                    weeklyMinsRemaining: limitCheck.weeklyMinsRemaining,
+                    sessionDurationMins: sessionCheck.durationMins,
+                    warning,
+                }),
+            }],
+    };
+});
+// ─── end_session ──────────────────────────────────────────────────────────────
+server.tool('end_session', 'Call when the session ends. Records duration, updates daily usage, and returns streak info.', {
+    profileId: z.string().describe('Child profile ID'),
+    sessionId: z.string().describe('Session ID from start_session'),
+    messageCount: z.number().optional().describe('Number of messages exchanged'),
+}, async ({ profileId, sessionId, messageCount }) => {
+    const now = new Date().toISOString();
+    const today = new Date().toISOString().split('T')[0];
+    const sessionCheck = checkSessionCap(db, config, sessionId);
+    const durationMins = sessionCheck.durationMins;
+    endSession(db, sessionId, now, durationMins, messageCount || 0);
+    upsertDailyUsage(db, profileId, today, durationMins, 1);
+    const dailyUsage = getDailyUsage(db, profileId, today);
+    const streakResult = updateStreak(db, config, profileId, today, dailyUsage.total_mins, config.dailyLimitMins);
+    // Optional daily Telegram summary
+    if (config.dailyReport && config.telegramBotToken && config.telegramParentChatId) {
+        const summary = buildDailySummary(config, config.childName, dailyUsage.total_mins, dailyUsage.session_count);
+        sendTelegram(config.telegramBotToken, config.telegramParentChatId, summary).catch(() => { });
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    sessionDuration_mins: Math.round(durationMins * 10) / 10,
+                    totalToday_mins: Math.round(dailyUsage.total_mins * 10) / 10,
+                    streak: streakResult.currentStreak,
+                    streakMessage: streakResult.streakMessage,
+                    bankedMins: streakResult.bankedMins,
+                    childSummary: streakResult.streakMessage || `Session done! ${Math.round(durationMins)} minutes today.`,
+                }),
+            }],
+    };
+});
+// ─── get_usage ────────────────────────────────────────────────────────────────
+server.tool('get_usage', 'Parent tool: get usage stats for a profile over recent days.', {
+    profileId: z.string().describe('Child profile ID'),
+    days: z.number().optional().describe('Number of days to look back (default: 7)'),
+}, async ({ profileId, days = 7 }) => {
+    const today = new Date();
+    const from = new Date(today);
+    from.setDate(today.getDate() - days + 1);
+    const fromDate = from.toISOString().split('T')[0];
+    const toDate = today.toISOString().split('T')[0];
+    const entries = getUsageRange(db, profileId, fromDate, toDate);
+    const totalMins = entries.reduce((sum, e) => sum + e.total_mins, 0);
+    const avgDailyMins = entries.length > 0 ? totalMins / days : 0;
+    const streak = getStreak(db, profileId);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    entries,
+                    totalMins: Math.round(totalMins * 10) / 10,
+                    avgDailyMins: Math.round(avgDailyMins * 10) / 10,
+                    currentStreak: streak.current_streak,
+                    longestStreak: streak.longest_streak,
+                    bankedMins: streak.banked_mins,
+                }),
+            }],
+    };
+});
+// ─── update_limits ────────────────────────────────────────────────────────────
+server.tool('update_limits', 'Parent tool: update limit settings for a profile at runtime.', {
+    profileId: z.string().describe('Child profile ID'),
+    settings: z.object({
+        dailyLimitMins: z.number().optional(),
+        sessionLimitMins: z.number().optional(),
+        weeklyBudgetMins: z.number().optional(),
+        coolDownMins: z.number().optional(),
+    }).describe('Settings to update (only provided fields are updated)'),
+}, async ({ profileId, settings }) => {
+    // Runtime config mutation (persists for current process)
+    if (settings.dailyLimitMins !== undefined)
+        config.dailyLimitMins = settings.dailyLimitMins;
+    if (settings.sessionLimitMins !== undefined)
+        config.sessionLimitMins = settings.sessionLimitMins;
+    if (settings.weeklyBudgetMins !== undefined)
+        config.weeklyBudgetMins = settings.weeklyBudgetMins;
+    if (settings.coolDownMins !== undefined)
+        config.coolDownMins = settings.coolDownMins;
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    updated: true,
+                    profileId,
+                    currentLimits: {
+                        dailyLimitMins: config.dailyLimitMins,
+                        sessionLimitMins: config.sessionLimitMins,
+                        weeklyBudgetMins: config.weeklyBudgetMins,
+                        coolDownMins: config.coolDownMins,
+                    },
+                    note: 'Changes are in-memory only. Update your .env file to persist across restarts.',
+                }),
+            }],
+    };
+});
+// ─── override_limits ──────────────────────────────────────────────────────────
+server.tool('override_limits', 'Parent tool: temporarily extend daily limit with a PIN.', {
+    profileId: z.string().describe('Child profile ID'),
+    pin: z.string().describe('Parent PIN'),
+    extraMinutes: z.number().describe('How many extra minutes to grant'),
+}, async ({ profileId, pin, extraMinutes }) => {
+    if (pin !== config.parentOverridePin) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ granted: false, reason: 'Invalid PIN' }),
+                }],
+        };
+    }
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + extraMinutes * 60 * 1000).toISOString();
+    insertOverride(db, {
+        id: randomUUID(),
+        profile_id: profileId,
+        granted_at: now.toISOString(),
+        expires_at: expiresAt,
+        extra_minutes: extraMinutes,
+    });
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    granted: true,
+                    extraMinutes,
+                    expiresAt,
+                    message: `Override granted! ${extraMinutes} extra minutes until ${new Date(expiresAt).toLocaleTimeString()}.`,
+                }),
+            }],
+    };
+});
+// ─── send_report ──────────────────────────────────────────────────────────────
+server.tool('send_report', 'Parent tool: generate and send the weekly usage report via Telegram.', {
+    profileId: z.string().describe('Child profile ID'),
+}, async ({ profileId }) => {
+    const { reportText, sent } = await sendWeeklyReport(db, config, profileId);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    sent,
+                    reportText,
+                    telegramConfigured: !!(config.telegramBotToken && config.telegramParentChatId),
+                }),
+            }],
+    };
+});
+// ─── Start server ─────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('screen-time-mcp running on stdio');
+}
+main().catch(console.error);

package/dist/limits.js

@@ -0,0 +1,182 @@
+import { getDailyUsage, getWeeklyTotal, getLastEndedSession, getActiveOverride, getSession } from './db.js';
+function toMinutes(timeStr) {
+    const [h, m] = timeStr.split(':').map(Number);
+    return h * 60 + m;
+}
+function nowMinutes() {
+    const now = new Date();
+    return now.getHours() * 60 + now.getMinutes();
+}
+function isInQuietHour(qh) {
+    const nowMins = nowMinutes();
+    const start = toMinutes(qh.start);
+    const end = toMinutes(qh.end);
+    if (start > end) {
+        // crosses midnight: e.g. 21:00 - 07:00
+        return nowMins >= start || nowMins < end;
+    }
+    else {
+        return nowMins >= start && nowMins < end;
+    }
+}
+function isMorningQuietHour(qh) {
+    // Morning quiet hours don't cross midnight
+    const start = toMinutes(qh.start);
+    const end = toMinutes(qh.end);
+    return start < end && start < 12 * 60;
+}
+function getActiveQuietHour(quietHours) {
+    for (const qh of quietHours) {
+        if (isInQuietHour(qh))
+            return qh;
+    }
+    return null;
+}
+function getTodayDate() {
+    return new Date().toISOString().split('T')[0];
+}
+function getWeekBounds() {
+    const now = new Date();
+    const day = now.getDay(); // 0=Sun
+    const diffToMonday = (day + 6) % 7;
+    const monday = new Date(now);
+    monday.setDate(now.getDate() - diffToMonday);
+    const sunday = new Date(monday);
+    sunday.setDate(monday.getDate() + 6);
+    return {
+        weekStart: monday.toISOString().split('T')[0],
+        weekEnd: sunday.toISOString().split('T')[0],
+    };
+}
+export function checkLimits(db, config, profileId, sessionId) {
+    const now = new Date().toISOString();
+    const today = getTodayDate();
+    const { weekStart, weekEnd } = getWeekBounds();
+    const dailyUsage = getDailyUsage(db, profileId, today);
+    const weeklyUsed = getWeeklyTotal(db, profileId, weekStart, weekEnd);
+    // Add current session time if checking mid-session
+    let currentSessionMins = 0;
+    if (sessionId) {
+        const session = getSession(db, sessionId);
+        if (session && !session.ended_at) {
+            const startedAt = new Date(session.started_at);
+            currentSessionMins = (Date.now() - startedAt.getTime()) / 60000;
+        }
+    }
+    const totalTodayMins = dailyUsage.total_mins + currentSessionMins;
+    const totalWeeklyMins = weeklyUsed + currentSessionMins;
+    // Check for active override
+    const override = getActiveOverride(db, profileId, now);
+    const overrideBonus = override ? override.extra_minutes : 0;
+    const effectiveDailyLimit = config.dailyLimitMins + overrideBonus;
+    const minutesUsedToday = totalTodayMins;
+    const minutesRemainingToday = Math.max(0, effectiveDailyLimit - totalTodayMins);
+    const weeklyMinsUsed = totalWeeklyMins;
+    const weeklyMinsRemaining = Math.max(0, config.weeklyBudgetMins - totalWeeklyMins);
+    // 1. Quiet hours check
+    const activeQH = getActiveQuietHour(config.quietHours);
+    if (activeQH) {
+        const isMorning = isMorningQuietHour(activeQH);
+        if (isMorning) {
+            return {
+                allowed: false,
+                reason: 'quiet_hours_morning',
+                message: `Good morning! AI time starts at ${activeQH.end} today. Go have breakfast 🥞`,
+                minutesUsedToday,
+                minutesRemainingToday,
+                weeklyMinsUsed,
+                weeklyMinsRemaining,
+            };
+        }
+        else {
+            return {
+                allowed: false,
+                reason: 'quiet_hours_night',
+                message: `It's getting late! AI time is done for tonight. Sleep is when your brain locks in everything you learned today 🧠`,
+                minutesUsedToday,
+                minutesRemainingToday,
+                weeklyMinsUsed,
+                weeklyMinsRemaining,
+            };
+        }
+    }
+    // 2. Daily cap check
+    if (totalTodayMins >= effectiveDailyLimit) {
+        return {
+            allowed: false,
+            reason: 'daily_cap',
+            message: `We've hit your daily AI time for today! 🌙 Your brain has done a lot today — rest is how it grows. See you tomorrow!`,
+            minutesUsedToday,
+            minutesRemainingToday: 0,
+            weeklyMinsUsed,
+            weeklyMinsRemaining,
+        };
+    }
+    // 3. Weekly budget check (soft block — still allowed but warn)
+    if (totalWeeklyMins >= config.weeklyBudgetMins) {
+        return {
+            allowed: true, // soft block: allowed but warned
+            warning: `You've used your full weekly AI budget (${config.weeklyBudgetMins} min). Try to keep it brief — maybe just one quick question? 🌟`,
+            minutesUsedToday,
+            minutesRemainingToday,
+            weeklyMinsUsed,
+            weeklyMinsRemaining: 0,
+        };
+    }
+    // 4. Cool-down check (only at session start, not mid-session)
+    if (!sessionId) {
+        const lastSession = getLastEndedSession(db, profileId);
+        if (lastSession && lastSession.ended_at) {
+            const lastEndMs = new Date(lastSession.ended_at).getTime();
+            const minsAgo = (Date.now() - lastEndMs) / 60000;
+            if (minsAgo < config.coolDownMins) {
+                const minsLeft = Math.ceil(config.coolDownMins - minsAgo);
+                return {
+                    allowed: false,
+                    reason: 'cool_down',
+                    message: `Your brain needs a short break! ☕ AI time resumes in ${minsLeft} minute${minsLeft !== 1 ? 's' : ''}. Go stretch, grab a snack, or look out the window for a bit.`,
+                    minutesUsedToday,
+                    minutesRemainingToday,
+                    weeklyMinsUsed,
+                    weeklyMinsRemaining,
+                };
+            }
+        }
+    }
+    // 5. 5-minute warning before daily cutoff
+    let warning;
+    if (minutesRemainingToday <= 5 && minutesRemainingToday > 0) {
+        warning = `Just so you know — we have about ${Math.ceil(minutesRemainingToday)} minute${minutesRemainingToday <= 1 ? '' : 's'} left for today. Anything important you want to wrap up? ⏰`;
+    }
+    else if (minutesRemainingToday <= 10) {
+        warning = `About ${Math.ceil(minutesRemainingToday)} minutes of AI time left today. Start wrapping up! 🕐`;
+    }
+    // Session cap warning (if mid-session)
+    if (sessionId && currentSessionMins >= config.sessionLimitMins - 5 && currentSessionMins < config.sessionLimitMins) {
+        const sessionMinsLeft = config.sessionLimitMins - currentSessionMins;
+        warning = warning || `This session is running long — about ${Math.ceil(sessionMinsLeft)} minute${sessionMinsLeft <= 1 ? '' : 's'} left in this session. Let's start wrapping up! 🎯`;
+    }
+    return {
+        allowed: true,
+        minutesUsedToday,
+        minutesRemainingToday,
+        weeklyMinsUsed,
+        weeklyMinsRemaining,
+        warning,
+    };
+}
+export function checkSessionCap(db, config, sessionId) {
+    const session = getSession(db, sessionId);
+    if (!session)
+        return { overCap: false, durationMins: 0 };
+    const startedAt = new Date(session.started_at);
+    const durationMins = (Date.now() - startedAt.getTime()) / 60000;
+    if (durationMins >= config.sessionLimitMins) {
+        return {
+            overCap: true,
+            durationMins,
+            message: `This session has reached the ${config.sessionLimitMins}-minute limit! 🌟 You've done great work. Time to take a break and let it sink in. Come back in ${config.coolDownMins} minutes!`,
+        };
+    }
+    return { overCap: false, durationMins };
+}

package/dist/reports.js

@@ -0,0 +1,113 @@
+import { getUsageRange, getSessionsForWeek, insertWeeklyReport } from './db.js';
+function formatMins(mins) {
+    const h = Math.floor(mins / 60);
+    const m = Math.round(mins % 60);
+    return h > 0 ? `${h}h ${m}min` : `${m}min`;
+}
+function getWeekBounds(weekStart) {
+    if (weekStart) {
+        const end = new Date(weekStart);
+        end.setDate(end.getDate() + 6);
+        return { weekStart, weekEnd: end.toISOString().split('T')[0] };
+    }
+    const now = new Date();
+    const day = now.getDay();
+    const diffToMonday = (day + 6) % 7;
+    const monday = new Date(now);
+    monday.setDate(now.getDate() - diffToMonday);
+    const sunday = new Date(monday);
+    sunday.setDate(monday.getDate() + 6);
+    return {
+        weekStart: monday.toISOString().split('T')[0],
+        weekEnd: sunday.toISOString().split('T')[0],
+    };
+}
+export function buildWeeklyReport(db, config, profileId, childName) {
+    const { weekStart, weekEnd } = getWeekBounds();
+    const entries = getUsageRange(db, profileId, weekStart, weekEnd);
+    const sessions = getSessionsForWeek(db, profileId, weekStart + 'T00:00:00.000Z', weekEnd + 'T23:59:59.999Z');
+    const totalMins = entries.reduce((sum, e) => sum + e.total_mins, 0);
+    const daysActive = entries.filter(e => e.total_mins > 0).length;
+    const sessionCount = sessions.length;
+    const avgSessionMins = sessionCount > 0 ? totalMins / sessionCount : 0;
+    const longestSession = sessions.reduce((max, s) => Math.max(max, s.duration_mins || 0), 0);
+    const daysWithinLimit = entries.filter(e => e.total_mins <= config.dailyLimitMins).length;
+    // Find most active day
+    const mostActiveEntry = entries.reduce((max, e) => e.total_mins > (max?.total_mins || 0) ? e : max, entries[0]);
+    // Week range display
+    const start = new Date(weekStart);
+    const end = new Date(weekEnd);
+    const months = ['January', 'February', 'March', 'April', 'May', 'June',
+        'July', 'August', 'September', 'October', 'November', 'December'];
+    const weekRange = `${months[start.getMonth()]} ${start.getDate()}–${end.getDate()}`;
+    let report = `📅 ${childName}'s AI week — ${weekRange}\n\n`;
+    report += `Total time: ${formatMins(totalMins)} (daily avg: ${formatMins(totalMins / 7)})\n`;
+    report += `Daily limit: ${config.dailyLimitMins} min — stayed within limit ${daysWithinLimit}/7 days ${daysWithinLimit >= 6 ? '✅' : daysWithinLimit >= 4 ? '🆗' : '⚠️'}\n`;
+    report += `Sessions: ${sessionCount} total, avg ${formatMins(avgSessionMins)} each\n\n`;
+    if (mostActiveEntry) {
+        const overBy = mostActiveEntry.total_mins - config.dailyLimitMins;
+        const dayName = new Date(mostActiveEntry.date).toLocaleDateString('en-US', { weekday: 'long' });
+        if (overBy > 0) {
+            report += `Most active: ${dayName} (${formatMins(mostActiveEntry.total_mins)} — went over by ${formatMins(overBy)})\n`;
+        }
+        else {
+            report += `Most active: ${dayName} (${formatMins(mostActiveEntry.total_mins)})\n`;
+        }
+    }
+    report += `\nThis week's insight: ${childName} is averaging ${formatMins(avgSessionMins)} per session across ${sessionCount} sessions. `;
+    if (avgSessionMins > 20) {
+        report += `Longer sessions suggest focused work — great for deep learning! Consider short breaks between sessions.\n`;
+    }
+    else {
+        report += `Short sessions suggest good self-regulation habits!\n`;
+    }
+    const weeklyMinsDown = 0; // Would need prior week data for comparison
+    report += `\nWeekly budget: ${formatMins(totalMins)} of ${formatMins(config.weeklyBudgetMins)} used (${Math.round((totalMins / config.weeklyBudgetMins) * 100)}%)`;
+    return report;
+}
+export function buildDailySummary(config, childName, totalMins, sessionCount) {
+    const withinLimit = totalMins <= config.dailyLimitMins;
+    const status = withinLimit ? '✅ Within limit' : `⚠️ Over by ${formatMins(totalMins - config.dailyLimitMins)}`;
+    return `📊 ${childName}'s AI time today: ${formatMins(totalMins)}/${formatMins(config.dailyLimitMins)}. ${sessionCount} session${sessionCount !== 1 ? 's' : ''}. ${status}`;
+}
+export async function sendTelegram(botToken, chatId, text) {
+    try {
+        const url = `https://api.telegram.org/bot${botToken}/sendMessage`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ chat_id: chatId, text, parse_mode: 'HTML' }),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function sendWeeklyReport(db, config, profileId) {
+    const reportText = buildWeeklyReport(db, config, profileId, config.childName);
+    const now = new Date().toISOString();
+    let sent = false;
+    if (config.telegramBotToken && config.telegramParentChatId) {
+        sent = await sendTelegram(config.telegramBotToken, config.telegramParentChatId, reportText);
+    }
+    const { weekStart, weekEnd } = getWeekBounds();
+    const entries = getUsageRange(db, profileId, weekStart, weekEnd);
+    const sessions = getSessionsForWeek(db, profileId, weekStart + 'T00:00:00.000Z', weekEnd + 'T23:59:59.999Z');
+    const totalMins = entries.reduce((sum, e) => sum + e.total_mins, 0);
+    const daysActive = entries.filter(e => e.total_mins > 0).length;
+    const sessionCount = sessions.length;
+    const avgSessionMins = sessionCount > 0 ? totalMins / sessionCount : 0;
+    const longestSession = sessions.reduce((max, s) => Math.max(max, s.duration_mins || 0), 0);
+    insertWeeklyReport(db, {
+        profile_id: profileId,
+        week_start: weekStart,
+        total_mins: totalMins,
+        days_active: daysActive,
+        avg_session_mins: avgSessionMins,
+        longest_session_mins: longestSession,
+        report_text: reportText,
+        sent_at: sent ? now : null,
+    });
+    return { reportText, sent };
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@gonzih/screen-time-mcp",
+  "version": "0.1.0",
+  "description": "MCP server enforcing AI usage limits for children — daily caps, quiet hours, weekly budgets, cool-down periods, gamified streaks, parent override",
+  "license": "MIT",
+  "author": "Gonzih",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "screen-time-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^9.4.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.8",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  },
+  "files": ["dist"]
+}