requirements.md•6.78 kB
# 每日工作记录 MCP 服务需求文档
## 背景与目标
- 为个人或小团队提供一个轻量级 MCP（Model Context Protocol）服务，用于追踪并回顾每日工作内容。
- 通过 MCP 与 AI 工具联动，便于查询最近的工作记录。
- 所有数据保存在本地数据库中，保障隐私与离线可用性。
## 功能需求
1. **新增工作内容**
- 接收详细描述、可选标签，无需填写日期或标题。
- 标签建议使用 `领域/项目` 形式（如 `infra/login`、`ops/report`），并可在后续查询中复用；常用标签需记录在 README 供参考。
- MCP Server 自动生成 `createdAt` 时间戳并写入数据库，同时生成唯一 ID。
2. **获取工作内容列表**
- 支持按日期范围查询：
- `daily`：指定日期的全部工作。
- `weekly`：指定周（以周一为起点的自然周）内的全部工作。
- 支持按标签进行筛选（可选）。
- 未提供 `date` 参数时：`daily` 默认查询当天，`weekly` 默认查询当前周（周一至周日）。
- 常见查询示例：`/entries?range=daily&tags=infra`（今日基础设施工作）、`/entries?range=weekly&date=2025-12-01`（2025-12-01 所在周）。
- 返回结果按时间倒序排列。
3. **本地数据库存储**
- 使用嵌入式数据库（推荐 SQLite）保存所有工作记录。
- 仅保留单一 `createdAt` 时间戳字段，记录插入时刻，不再维护 `updatedAt`。
- 数据写入后视为只读，不提供更新与删除能力。
- 需要定义数据迁移或初始化脚本，确保首次运行即可创建数据表。
4. **标签管理**
- 维护一份常用标签白名单列表，并提供 `GET /tags` 接口以便客户端渲染自动补全。
- 提供 `POST /tags` 接口，用于新增合法标签（包含唯一名称、可选描述与推荐使用场景），并写入白名单。
- 支持在 README 中记录标签约定，接口返回需包含标签描述与示例用途。
5. **数据导出与搜索**
- 提供 `GET /entries/export`（返回 CSV/JSON）以便备份或迁移，必要时可指定日期范围。
- 支持基于关键字的全文搜索（例如 `GET /entries/search?q=bug`），用于快速定位历史记录。
6. **提醒与摘要回顾**
- MCP Server 需暴露“今日是否已记录”工具，供客户端触发提醒。
- 提供“最近 N 天摘要”接口，自动以标签聚合形式输出，便于周报撰写。
## API 设计（初步）
| 功能 | 方法 | 路径 | 请求示例 | 响应示例 |
| --- | --- | --- | --- | --- |
| 新增工作内容 | `POST` | `/entries` | `{ "description": "排查...", "tags": ["infra"] }` | `{ "id": "uuid", "createdAt": "服务器时间", "summary": "2025-11-26 · infra/login" }` |
| 获取工作内容 | `GET` | `/entries?range=weekly` | `range`：`daily` 或 `weekly`，`date` 为 ISO 日期（可选，缺省按当前日/周；`weekly` 以周一为起点） | `[ { "description": "...", "createdAt": "...", "summary": "2025-11-26 · infra/login" } ]` |
| 新增标签 | `POST` | `/tags` | `{ "name": "ops/report", "description": "运维回顾" }` | `{ "name": "ops/report", "createdAt": "服务器时间" }` |
> **说明**：实际落地时可根据所选框架的 MCP 适配方式，将以上 REST 语义映射为 MCP 工具调用或流式响应。
## 客户端体验要求
- 列表视图需显示 `summary`、`createdAt`（本地化格式）与标签徽章，并支持按标签快速筛选。
- 详情视图展示完整描述及原始 JSON，提供“复制到剪贴板”“导出单条”操作。
- 在 MCP 客户端中预留“导出全部记录”入口，调用 `GET /entries/export`。
- 若当天尚未创建记录，客户端需以提示条或通知方式提醒用户补录。
## 数据模型
```
WorkEntry {
id: string (UUID)
description: string
tags?: string[]
createdAt: string (ISO 8601, 由服务器自动填充)
}
Tag {
name: string (唯一标识，建议使用 `领域/项目`)
description?: string
createdAt: string (ISO 8601, 由服务器自动填充)
}
```
> 返回接口需额外提供 `summary`（由服务端根据日期 + 标签拼接生成），以提升阅读体验；该字段可为派生值，无需入库；`Tag` 实体用于驱动自动补全与标签规范化管理。
## 非功能需求
- **可靠性**：写入操作需要返回明确的成功或失败状态。
- **可维护性**：需要提供数据库迁移/初始化脚本以及 README 说明。
- **可扩展性**：未来可扩展更多查询维度（如按标签统计）。
- **数据可移植性**：提供导出/备份指引（如 CSV 导出或 SQLite 文件备份），便于迁移至新设备。
- **可观测性**：记录关键 API/MCP 调用日志，便于快速排查失败原因。
- **容量假设**：面向单人使用，单进程 SQLite + MCP Server 即可满足性能需求。
## MCP 框架方案
### 首选方案：FastAPI + FastMCP（Python）
- **优点**：Python 生态丰富，FastAPI 本身对异步友好，FastMCP 官方模版完善。
- **适用场景**：需要快速原型、依赖 Python 数据处理库时。
- **说明**：本项目已确定采用该方案，以下运行环境规划默认基于此。
### 备选方案（当前不采纳）
1. **Node.js（TypeScript）+ 官方 `@modelcontextprotocol/server` SDK**
- **优点**：TypeScript 类型约束强、与前端生态一致，官方 SDK 提供指令生成工具。
- **适用场景**：已有 Node/TS 技术栈，期望与现有前端/服务整合。
2. **Go + `mcp-go`（或 gRPC/MCP 兼容库）**
- **优点**：单文件可执行、部署简单、性能高。
- **适用场景**：对性能、资源占用有要求，或希望零依赖部署。
## 技术选型与运行环境
- **框架栈**：FastAPI 负责 HTTP/MCP 适配层，FastMCP 提供协议封装，搭配 Pydantic 进行数据校验。
- **数据库**：继续使用本地 SQLite，配套 Alembic 或自定义脚本完成表结构初始化。
- **运行环境管理**：统一使用 Conda，确保依赖隔离、可重复。
### Conda 环境创建示例
1. `conda create -n daily-work-mcp python=3.11 -y`
2. `conda activate daily-work-mcp`
3. `pip install fastapi fastmcp uvicorn[standard] sqlite-utils`
4. （可选）`pip freeze > requirements.txt`，便于后续部署复现。
> 若需在不同机器部署，仅需安装 Conda 并按照上述步骤创建环境即可。
## 验收标准
- 可以通过 MCP 客户端成功调用“新增工作内容”工具并写入本地数据库。
- 可以通过 MCP 客户端查询指定日期或周的工作内容并获得正确结果。
- 数据库初始化脚本与 README 说明清晰，克隆仓库后可直接运行。