Habit Tracker Server

一個在 ChatGPT 裡追蹤每日習慣的 App,用 ChatGPT Apps SDK / MCP 建構。 使用者可以用自然語言(「新增喝水習慣」「幫我打卡」),也可以在內嵌的視覺化 介面直接操作;兩種方式共用同一套後端邏輯。資料存在本機 SQLite。

功能

• 新增 / 更新 / 刪除習慣,可設定每天的目標次數(target_per_day)
• 打卡(check-in),自動計算**連續天數(streak)**與今日進度
• 「今日待完成」檢視:列出今天還沒達標的習慣
• 內嵌 React widget:清單、打卡按鈕、新增表單,操作即時同步

架構概觀

使用者 ─┬─ 對 ChatGPT 說話 ──► 模型呼叫工具
        └─ 點 widget 按鈕 ──► 介面呼叫工具
                                 │
                                 ▼
                    MCP server (server/app.py, /mcp)
                                 │
                     repository.py ──► SQLite
                                 │
                    回傳 structured_content
                                 ▼
                ChatGPT 渲染 React widget(iframe)

• MCP 工具分兩組:給模型用的(模型自己決定何時呼叫)與只給介面用的 widget_* 別名(對模型隱形,由 widget 按鈕觸發)。兩組指向同一批函式。
• 衍生狀態不落地:streak、今日進度都在讀取時即時算出(habits_with_status), 不存快取欄位,永遠是最新的。
• widget 執行期的細節(沙箱 iframe、CORS/CSP、postMessage 橋)見 docs/widget-architecture.md。

檔案結構

habittrack/
├── server/
│   ├── config.py       # 環境變數設定
│   ├── database.py      # SQLite engine + session + 建表
│   ├── models.py        # Habit / CheckIn 資料表
│   ├── repository.py    # 資料存取 + streak / 今日進度計算
│   └── app.py           # MCP server、工具、widget resource、HTTP 路由
├── web/src/
│   ├── types.ts         # 前後端共用型別
│   ├── bridge.ts        # 封裝與 ChatGPT host 的橋接
│   ├── App.tsx          # React widget
│   └── main.tsx         # 掛載 React
├── tests/               # repository 單元測試
└── docs/
    └── widget-architecture.md

本機開發

# 1. 後端
cp .env.example .env          # 預設用 SQLite,可直接跑
uv sync
uv run pytest                 # 跑測試

# 2. 前端(改動後要重新 build)
cd web && npm install && npm run build && cd ..

# 3. 啟動(MCP 端點 /mcp,健康檢查 /health、/ready)
uv run uvicorn server.app:app --host 0.0.0.0 --port 2100 --reload

ChatGPT 只接受 HTTPS,所以用 ngrok 對外暴露,再到 Developer Mode 註冊:

ngrok http 2100
# 把 .env 的 PUBLIC_BASE_URL 設成 ngrok 的 https 網址,重啟 server
# 在 ChatGPT 註冊 https://<ngrok-host>/mcp(No authentication)

PUBLIC_BASE_URL 同時是 widget 載入資產的網址與 CSP 白名單,務必設成對外的 HTTPS origin(無尾斜線);改動後要重啟 server。

環境變數

變數	說明	預設
DATABASE_URL	資料庫連線字串	sqlite:///habits.db
PUBLIC_BASE_URL	widget 資產與 CSP 的對外 origin	http://localhost:2100
ENVIRONMENT	環境名稱	development

說明

目前為單機、無驗證的私人 Developer Mode 版本。若要分享或上線,需另外加上 OAuth 與 per-user 資料隔離。