使用说明
habit_tracker_mcp
用于跟踪个人习惯和待办事项的生产级模型上下文协议（MCP）服务器。它在大型语言模型（LLM）和持久的SQLite后端之间提供了一个强大的桥梁，使AI助手能够帮助您保持一致性并分析您的生产力模式。
🚀 主要特点
- 习惯追踪：通过灵活的频率目标管理反复出现的习惯。
- 待办事项管理：跟踪具有优先级和截止日期的一次性任务。
- 联动自动化：交叉链接允许待办事项在完成后自动记录习惯完成情况。
- 分类：统一组织的共享类别系统。
- AI驱动的分析：专业
sql-assistant用于深度数据自省的即时和实时模式资源。
🛠 设计决策
- 安全第一写突变仅限于特定的高级工具；原始SQL工具是严格只读的(
SELECT仅）。 - 默认保存：实施软删除（存档）而不是永久删除，以保护用户历史记录。
- 现代堆栈：使用Python 3.12、SQLAlchemy 2.0、Pydantic和
uv用于闪电般快速的依赖关系管理。 - 准备投产：包括完整的Docker集成、使用Alembic的自动迁移以及95%以上的覆盖率测试套件。
📂 项目结构
.
├── alembic/ # Database migration history
├── docker/ # Containerization (Dockerfile, Compose)
├── src/
│ └── habit_tracker_mcp/
│ ├── models/ # Data schemas and SQLAlchemy ORM
│ ├── tools/ # Logic for all MCP tools
│ ├── config.py # Pydantic Settings & Environment
│ ├── database.py # SQLAlchemy Engine & Session setup
│ ├── server.py # MCP App and Entrypoint
│ ├── resources.py # Live schema inspection logic
│ └── prompts.py # SQL assistant prompt templates
├── tests/ # Unit and integration tests
└── Makefile # Development lifecycle automation
先决条件
- Python 3.12+
- 紫外线
- Docker+Docker组合
- Node.js（用于MCP检查器）
本地设置
make install
cp .env.example .env
make migrate
make run
Docker设置
make docker-build
make docker-run
MCP检查员
make inspect
工具
| 工具 | 必需 | 可选 | 说明 |
|---|---|---|---|
run_query |
sql |
-- | 执行只读SELECT查询 |
add_category |
name |
color |
创建类别 |
list_categories |
-- | -- | 列出所有类别 |
add_habit |
name, frequency_type |
description, category_id, frequency_target |
养成一个习惯 |
list_habits |
— | category_id, include_archived |
列出习惯 |
complete_habit |
habit_id |
note, completed_at |
记录习惯完成情况 |
archive_habit |
habit_id |
archived_at |
软删除习惯 |
add_todo |
title |
notes, priority, due_date, category_id, habit_id |
创建待办事项 |
list_todos |
— | category_id, habit_id, completed 列出所有 |
|
complete_todo |
todo_id |
note, completed_at |
完成待办事项，如果链接，自动记录习惯完成情况 |
资源
| URI | 描述 |
|---|---|
db://schema |
实时数据库模式——表、列、外键、索引 |
提示
| 名称 | 参数 | 描述 |
|---|---|---|
sql-assistant |
focus （可选） |
在编写查询之前，为客户端提供完整的模式知识 |
工具访问策略
人工智能在设计上没有删除功能。破坏性行动 保留用于直接数据库访问或未来的前端。
要直接访问数据库，请执行以下操作：
make docker-shell
sqlite3 /app/data/habit_tracker.db
⚠️ 警告
docker-compose down -v永久销毁数据库和所有数据READ_ONLY_MODE=true阻止所有写入操作，包括专用写入工具- 从不使用
run_query对于写入操作，请使用专用的写入工具
