libero-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 amosyuan
+
+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,21 @@
+# libero 2.0
+
+AI 辅助人类精力管理：观察实绩 → 发现问题 → 对齐方案 → AI 辅助达成，PDCA 闭环。
+
+2.0 = 一组 Skills（脑）+ 一层 MCP 工具（手）+ 一个数据后端（记忆），骑 Openclaw，本地优先。
+
+## 快速开始
+
+> MV-0 排雷中，runbook 待补充。
+
+## 仓库结构
+
+- `skills/` — 脑（prompt + markdown）
+- `mcp/` — 手（确定性 MCP 工具）
+- `data/` — 本地 DB schema + migrations
+- `eval/` — Skill 评估与压力测试
+- `docs/` — spec / plan / 决策记录
+
+## 协作宪法
+
+见 [AGENTS.md](AGENTS.md)

package/data/migrations/001_initial_schema.sql

@@ -0,0 +1,43 @@
+-- 001_initial_schema: libero 2.0 核心表
+-- K1 合规：所有业务表带 UUID PK + created_at + updated_at + deleted_at（软删除）
+
+CREATE TABLE IF NOT EXISTS user_profile (
+  id TEXT PRIMARY KEY,
+  display_name TEXT NOT NULL DEFAULT '',
+  expectations TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS time_blocks (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  category_id TEXT,
+  start_time TEXT NOT NULL,
+  end_time TEXT NOT NULL,
+  duration_minutes INTEGER,
+  notes TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT,
+  FOREIGN KEY (user_id) REFERENCES user_profile(id)
+);
+
+CREATE TABLE IF NOT EXISTS categories (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  emoji TEXT DEFAULT '',
+  color TEXT DEFAULT '',
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT,
+  UNIQUE(name)
+);
+
+CREATE TABLE IF NOT EXISTS _migrations (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+);

package/data/migrations/002_seed_categories.sql

@@ -0,0 +1,18 @@
+-- 002_seed_categories: libero 2.0 默认 15 分类
+
+INSERT INTO categories (id, name, emoji, color) VALUES
+  ('cat-work',     '工作', '💼', '#4A90D9'),
+  ('cat-study',    '学习', '📚', '#7B68EE'),
+  ('cat-create',   '创作', '✍️', '#E67E22'),
+  ('cat-sleep',    '睡眠', '😴', '#34495E'),
+  ('cat-eat',      '餐饮', '🍽️', '#E74C3C'),
+  ('cat-chore',    '内务', '🏠', '#95A5A6'),
+  ('cat-commute',  '通勤', '🚗', '#1ABC9C'),
+  ('cat-exercise', '运动', '🏃', '#2ECC71'),
+  ('cat-meditate', '冥想', '🧘', '#9B59B6'),
+  ('cat-medical',  '医疗', '🏥', '#E91E63'),
+  ('cat-social',   '社交', '👥', '#FF6F00'),
+  ('cat-family',   '陪伴', '👨‍👩‍👧', '#00BCD4'),
+  ('cat-play',     '娱乐', '🎮', '#F39C12'),
+  ('cat-idle',     '闲散', '☕', '#BDC3C7'),
+  ('cat-other',    '其他', '❓', '#7F8C8D');

package/data/migrations/003_add_rating.sql

@@ -0,0 +1,4 @@
+-- 003_add_rating: time_blocks 增加评分字段
+
+ALTER TABLE time_blocks ADD COLUMN rating INTEGER;
+ALTER TABLE time_blocks ADD COLUMN rating_reason TEXT;

package/data/migrations/004_timer_sessions.sql

@@ -0,0 +1,21 @@
+-- 004_timer_sessions: multi-user persistent timer state
+-- Eliminates module-level global `let state` (architecture pitfall A2).
+-- Stores started_at + accumulated_ms invariants; elapsed is always recomputed.
+
+CREATE TABLE IF NOT EXISTS timer_sessions (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  event TEXT NOT NULL,
+  category_id TEXT,
+  status TEXT NOT NULL DEFAULT 'running',
+  started_at TEXT NOT NULL,
+  accumulated_ms INTEGER NOT NULL DEFAULT 0,
+  ended_at TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (user_id) REFERENCES user_profile(id)
+);
+
+-- Speed up "find active session for user" (at most one running/paused per user)
+CREATE INDEX IF NOT EXISTS idx_timer_active
+  ON timer_sessions (user_id, status);

package/data/migrations/005_profile_settings.sql

@@ -0,0 +1,5 @@
+-- 005_profile_settings: 结构化约定存为 JSON 列 (Q-14 决策)
+-- 为 onboarding 和 coach 提供结构化约定的存储字段
+ALTER TABLE user_profile ADD COLUMN settings TEXT;
+-- settings 存 JSON 字符串，形如：
+-- {"focus_areas":["工作","学习"],"goals":"每天专注 4h","rhythm":"番茄钟","review_time":"每周日 20:00"}

package/data/migrations/006_add_timeblock_status.sql

@@ -0,0 +1 @@
+ALTER TABLE time_blocks ADD COLUMN status TEXT NOT NULL DEFAULT 'completed';

package/data/schema.sql

@@ -0,0 +1,43 @@
+-- 001_initial_schema: libero 2.0 核心表
+-- K1 合规：所有业务表带 UUID PK + created_at + updated_at + deleted_at（软删除）
+
+CREATE TABLE IF NOT EXISTS user_profile (
+  id TEXT PRIMARY KEY,
+  display_name TEXT NOT NULL DEFAULT '',
+  expectations TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS time_blocks (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  category_id TEXT,
+  start_time TEXT NOT NULL,
+  end_time TEXT NOT NULL,
+  duration_minutes INTEGER,
+  notes TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT,
+  FOREIGN KEY (user_id) REFERENCES user_profile(id)
+);
+
+CREATE TABLE IF NOT EXISTS categories (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  emoji TEXT DEFAULT '',
+  color TEXT DEFAULT '',
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT,
+  UNIQUE(name)
+);
+
+CREATE TABLE IF NOT EXISTS _migrations (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+);

package/dist/data/db.js

@@ -0,0 +1,61 @@
+import Database from "better-sqlite3";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+let instance = null;
+function runMigrations(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS _migrations (
+      version INTEGER PRIMARY KEY,
+      name TEXT NOT NULL,
+      applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+    const migrationsDir = join(import.meta.dirname, "migrations");
+    const files = readdirSync(migrationsDir)
+        .filter((f) => f.endsWith(".sql"))
+        .sort();
+    const applied = new Set(db.prepare("SELECT version FROM _migrations").all().map((r) => r.version));
+    for (const file of files) {
+        const match = file.match(/^(\d+)_/);
+        if (!match)
+            continue;
+        const version = parseInt(match[1], 10);
+        if (applied.has(version))
+            continue;
+        const sql = readFileSync(join(migrationsDir, file), "utf-8");
+        db.exec(sql);
+        db.prepare("INSERT INTO _migrations (version, name) VALUES (?, ?)").run(version, file);
+    }
+}
+export function initDb(dbPath) {
+    if (instance) {
+        instance.close();
+        instance = null;
+    }
+    const db = new Database(dbPath);
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    runMigrations(db);
+    instance = db;
+    return db;
+}
+export function getDb() {
+    if (!instance) {
+        throw new Error("Database not initialized. Call initDb() first.");
+    }
+    return instance;
+}
+export function closeDb() {
+    if (instance) {
+        instance.close();
+        instance = null;
+    }
+}
+const entry = process.argv[1];
+if (entry && fileURLToPath(import.meta.url) === entry) {
+    const dbPath = process.env.DB_PATH ?? join(import.meta.dirname, "libero.db");
+    initDb(dbPath);
+    console.log(`DB initialized at ${dbPath}`);
+    closeDb();
+}

package/dist/data/migrations/001_initial_schema.sql

@@ -0,0 +1,43 @@
+-- 001_initial_schema: libero 2.0 核心表
+-- K1 合规：所有业务表带 UUID PK + created_at + updated_at + deleted_at（软删除）
+
+CREATE TABLE IF NOT EXISTS user_profile (
+  id TEXT PRIMARY KEY,
+  display_name TEXT NOT NULL DEFAULT '',
+  expectations TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS time_blocks (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  category_id TEXT,
+  start_time TEXT NOT NULL,
+  end_time TEXT NOT NULL,
+  duration_minutes INTEGER,
+  notes TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT,
+  FOREIGN KEY (user_id) REFERENCES user_profile(id)
+);
+
+CREATE TABLE IF NOT EXISTS categories (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  emoji TEXT DEFAULT '',
+  color TEXT DEFAULT '',
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT,
+  UNIQUE(name)
+);
+
+CREATE TABLE IF NOT EXISTS _migrations (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+);

package/dist/data/migrations/002_seed_categories.sql

@@ -0,0 +1,18 @@
+-- 002_seed_categories: libero 2.0 默认 15 分类
+
+INSERT INTO categories (id, name, emoji, color) VALUES
+  ('cat-work',     '工作', '💼', '#4A90D9'),
+  ('cat-study',    '学习', '📚', '#7B68EE'),
+  ('cat-create',   '创作', '✍️', '#E67E22'),
+  ('cat-sleep',    '睡眠', '😴', '#34495E'),
+  ('cat-eat',      '餐饮', '🍽️', '#E74C3C'),
+  ('cat-chore',    '内务', '🏠', '#95A5A6'),
+  ('cat-commute',  '通勤', '🚗', '#1ABC9C'),
+  ('cat-exercise', '运动', '🏃', '#2ECC71'),
+  ('cat-meditate', '冥想', '🧘', '#9B59B6'),
+  ('cat-medical',  '医疗', '🏥', '#E91E63'),
+  ('cat-social',   '社交', '👥', '#FF6F00'),
+  ('cat-family',   '陪伴', '👨‍👩‍👧', '#00BCD4'),
+  ('cat-play',     '娱乐', '🎮', '#F39C12'),
+  ('cat-idle',     '闲散', '☕', '#BDC3C7'),
+  ('cat-other',    '其他', '❓', '#7F8C8D');

package/dist/data/migrations/003_add_rating.sql

@@ -0,0 +1,4 @@
+-- 003_add_rating: time_blocks 增加评分字段
+
+ALTER TABLE time_blocks ADD COLUMN rating INTEGER;
+ALTER TABLE time_blocks ADD COLUMN rating_reason TEXT;

package/dist/data/migrations/004_timer_sessions.sql

@@ -0,0 +1,21 @@
+-- 004_timer_sessions: multi-user persistent timer state
+-- Eliminates module-level global `let state` (architecture pitfall A2).
+-- Stores started_at + accumulated_ms invariants; elapsed is always recomputed.
+
+CREATE TABLE IF NOT EXISTS timer_sessions (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  event TEXT NOT NULL,
+  category_id TEXT,
+  status TEXT NOT NULL DEFAULT 'running',
+  started_at TEXT NOT NULL,
+  accumulated_ms INTEGER NOT NULL DEFAULT 0,
+  ended_at TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (user_id) REFERENCES user_profile(id)
+);
+
+-- Speed up "find active session for user" (at most one running/paused per user)
+CREATE INDEX IF NOT EXISTS idx_timer_active
+  ON timer_sessions (user_id, status);

package/dist/data/migrations/005_profile_settings.sql

@@ -0,0 +1,5 @@
+-- 005_profile_settings: 结构化约定存为 JSON 列 (Q-14 决策)
+-- 为 onboarding 和 coach 提供结构化约定的存储字段
+ALTER TABLE user_profile ADD COLUMN settings TEXT;
+-- settings 存 JSON 字符串，形如：
+-- {"focus_areas":["工作","学习"],"goals":"每天专注 4h","rhythm":"番茄钟","review_time":"每周日 20:00"}

package/dist/data/migrations/006_add_timeblock_status.sql

@@ -0,0 +1 @@
+ALTER TABLE time_blocks ADD COLUMN status TEXT NOT NULL DEFAULT 'completed';

package/dist/data/schema.sql

@@ -0,0 +1,43 @@
+-- 001_initial_schema: libero 2.0 核心表
+-- K1 合规：所有业务表带 UUID PK + created_at + updated_at + deleted_at（软删除）
+
+CREATE TABLE IF NOT EXISTS user_profile (
+  id TEXT PRIMARY KEY,
+  display_name TEXT NOT NULL DEFAULT '',
+  expectations TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS time_blocks (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  category_id TEXT,
+  start_time TEXT NOT NULL,
+  end_time TEXT NOT NULL,
+  duration_minutes INTEGER,
+  notes TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT,
+  FOREIGN KEY (user_id) REFERENCES user_profile(id)
+);
+
+CREATE TABLE IF NOT EXISTS categories (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  emoji TEXT DEFAULT '',
+  color TEXT DEFAULT '',
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT,
+  UNIQUE(name)
+);
+
+CREATE TABLE IF NOT EXISTS _migrations (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+);

package/dist/mcp/server-core.js

@@ -0,0 +1,182 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { SqliteCategoryRepo, SqliteTimeBlockRepo, SqliteStatsRepo, SqliteTimerRepo, SqliteProfileRepo, } from "./src/repo/sqlite.js";
+import { createCategoryTools } from "./src/categories/index.js";
+import { createTimeBlockTools } from "./src/timeblock/index.js";
+import { createStatsTools } from "./src/stats/index.js";
+import { createMatrixTools } from "./src/matrix/index.js";
+import { createTimerTools } from "./src/timer/index.js";
+import { createProfileTools } from "./src/profile/index.js";
+import { nowLocal, formatTime, parseTime } from "./src/clock/index.js";
+/** Wrap any tool result as MCP text content (JSON). Void results become {ok:true}. */
+function asContent(result) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result !== undefined ? result : { ok: true }),
+            },
+        ],
+    };
+}
+/**
+ * Build the libero MCP server on a given DB connection.
+ * Tools throw Error on business violations; handlers let them propagate —
+ * the SDK turns thrown errors into MCP tool errors (isError) preserving the message.
+ */
+export function buildServer(db) {
+    // ── construct repos (S10 §3.3) ──
+    const categoryRepo = new SqliteCategoryRepo(db);
+    const timeblockRepo = new SqliteTimeBlockRepo(db);
+    const statsRepo = new SqliteStatsRepo(db);
+    const timerRepo = new SqliteTimerRepo(db);
+    const profileRepo = new SqliteProfileRepo(db);
+    // ── inject tool factories ──
+    const categories = createCategoryTools(categoryRepo);
+    const tb = createTimeBlockTools(timeblockRepo);
+    const stats = createStatsTools(statsRepo);
+    const matrix = createMatrixTools(statsRepo); // matrix reuses StatsRepo
+    const timer = createTimerTools(timerRepo);
+    const profile = createProfileTools(profileRepo);
+    const server = new McpServer({ name: "libero-mcp", version: "0.1.0" });
+    // ============================================================
+    // categories (2 tools)
+    // ============================================================
+    server.registerTool("categories.getAll", { description: "获取全部时间分类（15 类）", inputSchema: {} }, async () => asContent(await categories.getAllCategories()));
+    server.registerTool("categories.getById", { description: "按 id 获取单个分类", inputSchema: { id: z.string().min(1) } }, async ({ id }) => asContent(await categories.getCategoryById(id)));
+    // ============================================================
+    // timer (6 tools — positional userId args, R4 pattern)
+    // ============================================================
+    server.registerTool("timer.start", {
+        description: "开始一个计时会话",
+        inputSchema: {
+            user_id: z.string().min(1),
+            event: z.string().min(1),
+            categoryId: z.string().optional(),
+        },
+    }, async ({ user_id, event, categoryId }) => asContent(await timer.start(user_id, event, categoryId)));
+    server.registerTool("timer.pause", { description: "暂停当前计时", inputSchema: { user_id: z.string().min(1) } }, async ({ user_id }) => asContent(await timer.pause(user_id)));
+    server.registerTool("timer.resume", { description: "恢复已暂停的计时", inputSchema: { user_id: z.string().min(1) } }, async ({ user_id }) => asContent(await timer.resume(user_id)));
+    server.registerTool("timer.stop", { description: "停止计时并返回记录", inputSchema: { user_id: z.string().min(1) } }, async ({ user_id }) => asContent(await timer.stop(user_id)));
+    server.registerTool("timer.status", { description: "查询某用户当前计时状态", inputSchema: { user_id: z.string().min(1) } }, async ({ user_id }) => asContent(await timer.status(user_id)));
+    server.registerTool("timer.elapsed", { description: "查询当前计时已过毫秒数", inputSchema: { user_id: z.string().min(1) } }, async ({ user_id }) => asContent(await timer.elapsed(user_id)));
+    // ============================================================
+    // timeblock (5 tools — single-object args)
+    // ============================================================
+    server.registerTool("timeblock.create", {
+        description: "创建一条时间记录",
+        inputSchema: {
+            user_id: z.string().min(1),
+            title: z.string().min(1),
+            category_id: z.string().optional(),
+            start_time: z.string(),
+            end_time: z.string(),
+            duration_minutes: z.number().optional(),
+            rating: z.number().min(1).max(5).optional(),
+            rating_reason: z.string().optional(),
+            notes: z.string().optional(),
+        },
+    }, async (input) => asContent(await tb.create(input)));
+    server.registerTool("timeblock.getById", { description: "按 id 获取单条时间记录", inputSchema: { id: z.string().min(1) } }, async ({ id }) => asContent(await tb.getById(id)));
+    server.registerTool("timeblock.update", {
+        description: "更新一条时间记录",
+        inputSchema: {
+            id: z.string().min(1),
+            title: z.string().optional(),
+            category_id: z.string().optional(),
+            start_time: z.string().optional(),
+            end_time: z.string().optional(),
+            duration_minutes: z.number().optional(),
+            rating: z.number().min(1).max(5).optional(),
+            rating_reason: z.string().optional(),
+            notes: z.string().optional(),
+        },
+    }, async ({ id, ...rest }) => asContent(await tb.update(id, rest)));
+    server.registerTool("timeblock.remove", { description: "软删除一条时间记录", inputSchema: { id: z.string().min(1) } }, async ({ id }) => asContent(await tb.remove(id)));
+    server.registerTool("timeblock.restore", { description: "恢复一条已软删除的时间记录", inputSchema: { id: z.string().min(1) } }, async ({ id }) => asContent(await tb.restore(id)));
+    server.registerTool("timeblock.list", {
+        description: "按条件查询时间记录列表",
+        inputSchema: {
+            user_id: z.string().min(1),
+            date: z.string().optional(),
+            from: z.string().optional(),
+            to: z.string().optional(),
+            category_id: z.string().optional(),
+            include_deleted: z.boolean().optional(),
+            limit: z.number().optional(),
+            offset: z.number().optional(),
+        },
+    }, async (input) => asContent(await tb.list(input)));
+    // ============================================================
+    // stats (2 tools — single-object filters)
+    // ============================================================
+    server.registerTool("stats.summarize", {
+        description: "按分类汇总时间统计（占比/记录数）",
+        inputSchema: {
+            user_id: z.string().min(1),
+            from: z.string().optional(),
+            to: z.string().optional(),
+            category_id: z.string().optional(),
+        },
+    }, async (input) => asContent(await stats.summarize(input)));
+    server.registerTool("stats.dailyBreakdown", {
+        description: "按天×分类拆分时间明细",
+        inputSchema: {
+            user_id: z.string().min(1),
+            from: z.string().optional(),
+            to: z.string().optional(),
+            category_id: z.string().optional(),
+        },
+    }, async (input) => asContent(await stats.dailyBreakdown(input)));
+    // ============================================================
+    // matrix (1 tool — single-object filters, reuses StatsRepo)
+    // ============================================================
+    server.registerTool("matrix.renderMatrix", {
+        description: "时间×评分四象限矩阵（能耗黑洞/保持区/亮点区/可放弃）",
+        inputSchema: {
+            user_id: z.string().min(1),
+            from: z.string().optional(),
+            to: z.string().optional(),
+        },
+    }, async (input) => asContent(await matrix.renderMatrix(input)));
+    // ============================================================
+    // clock (3 tools — pure functions, no repo)
+    // ============================================================
+    server.registerTool("clock.now", {
+        description: "返回当前 ISO 时间字符串（可选时区偏移）",
+        inputSchema: {
+            offsetMinutes: z.number().optional(),
+        },
+    }, async ({ offsetMinutes }) => asContent(offsetMinutes !== undefined ? nowLocal(offsetMinutes) : nowLocal()));
+    server.registerTool("clock.formatTime", {
+        description: "按指定格式格式化 ISO 时间",
+        inputSchema: {
+            iso: z.string().min(1),
+            format: z.string().min(1),
+        },
+    }, async ({ iso, format }) => asContent(formatTime(iso, format)));
+    server.registerTool("clock.parseTime", {
+        description: "解析 ISO 时间字符串为结构化字段",
+        inputSchema: { iso: z.string().min(1) },
+    }, async ({ iso }) => asContent(parseTime(iso)));
+    // ============================================================
+    // profile (2 tools — get / upsert)
+    // ============================================================
+    server.registerTool("profile.get", {
+        description: "获取用户 profile（含结构化约定）",
+        inputSchema: { user_id: z.string().min(1) },
+    }, async ({ user_id }) => asContent(await profile.get(user_id)));
+    server.registerTool("profile.upsert", {
+        description: "创建或更新用户 profile（结构化约定存入 settings JSON 列）",
+        inputSchema: {
+            user_id: z.string().min(1),
+            display_name: z.string().optional(),
+            expectations: z.string().optional(),
+            settings: z
+                .object({})
+                .passthrough()
+                .optional(),
+        },
+    }, async (input) => asContent(await profile.upsert(input)));
+    return server;
+}

package/dist/mcp/server.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * libero MCP server — stdio transport entry point (S10 §3.3).
+ *
+ * Usage:
+ *   DB_PATH=/path/to/libero.db node mcp/server.ts
+ *   DB_PATH=/path/to/libero.db npx tsx mcp/server.ts
+ *   libero-mcp                    (if package.json bin + tsx is configured)
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { initDb, closeDb } from "../data/db.js";
+import { buildServer } from "./server-core.js";
+const DB_PATH = process.env.DB_PATH ?? "./data/libero.db";
+if (!DB_PATH) {
+    console.error("FATAL: DB_PATH environment variable not set.");
+    process.exit(1);
+}
+const db = initDb(DB_PATH);
+console.error(`[libero-mcp] DB initialized at ${DB_PATH}`);
+const server = buildServer(db);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`[libero-mcp] Server connected via stdio`);
+function shutdown() {
+    console.error("[libero-mcp] Shutting down…");
+    closeDb();
+    process.exit(0);
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/dist/mcp/src/categories/index.js

@@ -0,0 +1,12 @@
+/** Create categories tools backed by the given repository.
+ *  ADR-0001: Dependency-injected — the caller provides the repo, not getDb(). */
+export function createCategoryTools(repo) {
+    return {
+        async getAllCategories() {
+            return repo.getAll();
+        },
+        async getCategoryById(id) {
+            return repo.getById(id);
+        },
+    };
+}