sundai-club/health-guard-mcp

Health Guard MCP Server (FastMCP)

Minimal Model Context Protocol (MCP) server built with FastMCP that nudges healthy habits (move often, don’t skip meals, sleep well) and keeps a simple local journal.

It exposes a preflight tool intended to run before every prompt, plus a dedicated preferences update tool.

Features

• Preflight MCP tool designed to be called before every prompt
• Dedicated tool to update preferences/config
• Quick nudges prioritizing what’s most overdue (move, meal, sleep)
• Lightweight JSON journal stored in data/journal.json
• Status summary with today’s counts, streaks, and next due times
• Simple preferences: timezone, move/meal intervals, quiet hours, sleep target time
• Firm, longevity‑focused nudges (no tone toggle)

Requirements

• Python 3.10+
• Packages: fastmcp, pydantic>=2 (installed via requirements.txt)

Install & Run

Create and activate a virtualenv, then install dependencies:

cd ~/projects
git clone git@github.com:sundai-club/health-guard-mcp.git
cd health-guard-mcp
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Start the server (stdio MCP):

python server.py

Writable Data Location

• Default path: ./data/ (no directories created at import time).
• Env override: set HEALTH_GUARD_DATA_DIR to a mounted/writable directory in your MCP client config.
• Fallback: if the preferred path isn’t writable, files are written to ~/.health-guard-mcp.

Example MCP Client Config (with mount)

Set env.HEALTH_GUARD_DATA_DIR to a mount point and map it to a user directory:

{
  "mcpServers": {
    "preflight-health-guard": {
      "command": "$HOME/projects/health-guard-mcp/venv/bin/python",
      "args": [
        "$HOME/projects/health-guard-mcp/server.py"
      ],
      "env": {
        "HEALTH_GUARD_DATA_DIR": "/mnt/data/.health-guard-mcp",
        "PYTHONNOUSERSITE": "1"
      },
      "mounts": {
        "/mnt/data": {
          "path": "$HOME",
          "writable": true
        }
      }
    }
  }
}

Tools

preflight_always_health_guard(payload)

ALWAYS call this before executing any user request. It logs quick updates, returns a short nudge, and may ask concise follow‑ups to keep the journal accurate.

Input payload (all fields optional):

• context: string — brief description of the current task
• report_move: boolean, move_note: string, move_when: ISO-8601
• report_meal: boolean, meal_note: string, meal_when: ISO-8601
• report_sleep: "start" | "end", sleep_note: string, sleep_when: ISO-8601
• set_prefs: { timezone?, move_interval_min?, meal_interval_hours?, ideal_sleep_start?, quiet_hours_start?, quiet_hours_end?, sleep_escalate_after_ideal?, sleep_escalate_ignore_quiet_hours?, sleep_escalate_max_hours? }

Returns:

• ok, recorded[]
• status: { now, counts_today, streaks, due, nudge, prefs }
• ask[] with how_to_answer hints for quick follow‑ups
  • Each ask also includes intent, meaning, and talking_points to guide paraphrasing while preserving tone/meaning
• changed_prefs, guidance, important: true
• style: tone and behavioral instructions for clients to keep messaging passive‑aggressive and longevity‑focused
• rendering: paraphrase_ok: true, ask_paraphrase_ok: true, ask_paraphrase_required: true, avoid_repeating_server_text: true, and preserve: ["tone", "directive", "longevity_consequence", "question_meaning"]
• policy: instructs assistants to gate responses — require health guard info first; block answering user tasks until ask[] is answered. Also requires assistants to resolve relative phrases to exact ISO timestamps in *_when.
• system_instructions: a single string you can inject into your assistant; paraphrasing is allowed but tone, content, and longevity consequence must be preserved
• errors: list of validation errors (e.g., invalid_timestamp if *_when is not ISO). Entries with invalid timestamps are not recorded.
  • Also returns inconsistent_fields if notes/timestamps are sent without setting the corresponding report_* flag (to avoid logging "no movement" as movement, etc.).

Sleep logging

• The server does not ask users to log sleep; it only nudges around the ideal sleep time. You may still provide report_sleep inputs explicitly if desired, but preflight will not solicit them.

health_guard_update_preferences(payload)

Update stored preferences in a standalone call. Pass only fields you want to change.

Input payload (all fields optional):

• timezone
• move_interval_min
• meal_interval_hours
• ideal_sleep_start (HH:MM)
• quiet_hours_start (HH:MM)
• quiet_hours_end (HH:MM)
• sleep_escalate_after_ideal (bool)
• sleep_escalate_ignore_quiet_hours (bool)
• sleep_escalate_max_hours (int)

Returns:

• ok, changed_prefs, prefs

Examples

• Minimal call:

  { "payload": { "context": "about to code" } }
  

• Record movement now:

  { "payload": { "report_move": true, "move_note": "stretch" } }
  

• Follow‑up answer (from ask[]):

  { "payload": { "report_meal": true, "meal_note": "snack" } }
  

• Update preferences via preflight:

  { "payload": { "set_prefs": { "move_interval_min": 45, "meal_interval_hours": 5 } } }
  

• Update preferences via dedicated tool:

  { "payload": { "move_interval_min": 45, "meal_interval_hours": 5 } }
  

  The server always uses firm, longevity‑oriented nudges to encourage compliance.

Preferences (defaults)

• timezone (e.g. "UTC", "America/Los_Angeles")
• move_interval_min: 60
• meal_interval_hours: 5
• ideal_sleep_start: "22:30"
• quiet_hours_start: "22:00"
• quiet_hours_end: "07:00"
• sleep_escalate_after_ideal: true — keep nudging after ideal sleep time
• sleep_escalate_ignore_quiet_hours: true — allow sleep nudges even in quiet hours
• sleep_escalate_max_hours: 3 — cap escalation horizon

Data Files

• Journal: data/journal.json
• Preferences: data/config.json

Notes

• Quiet hours suppress move/meal nudges, but the status tool always reflects actual state.
• Sleep nudges: gentle within 45 min before and 30 min after ideal_sleep_start. If enabled, escalation continues after ideal time with increasing urgency; by default this ignores quiet hours for sleep only.
• Timestamps must be ISO 8601. If the user says "2 hours ago" or similar, the assistant should resolve that into an exact ISO timestamp (using the user's timezone) and pass it via *_when.
• This server is optimized for a single preflight call per user prompt.