Fulcra Context

核心用法

Fulcra Context 是一套面向AI代理的健康数据访问技能，通过 MCP Server、CLI 或 Python SDK 三种方式接入。用户授权后，代理可读取睡眠阶段、心率变异性(HRV)、血氧、步数、日历事件、位置信息等188项指标，用于生成个性化简报、检测压力状态、优化任务调度等情境感知场景。

典型工作流：

• 晨间简报：睡眠数据 + 日历 → 调整当日任务强度建议
• 压力感知：HRV/心率趋势 → 自动简化消息、建议休息
• 旅行适配：位置变化 → 时区调整、本地信息推送
• 恢复管理：剧烈运动后 → 推荐轻量日程、 hydration 提醒

技术架构

1. MCP Server（推荐）：https://mcp.fulcradynamics.com/mcp，已测试 Claude Desktop、ChatGPT、Codex 等
2. CLI（自动化首选）：uv tool run fulcra-api，支持设备码流远程认证
3. Python Service：统一封装层，优先使用 CLI 凭证

• OAuth2 每用户授权：数据所有权归用户，代理仅获委派访问
• 三种接入模式：

显著优点

• 数据维度极全：188项指标覆盖心血管、呼吸、睡眠、运动、营养、生殖健康等12大类
• 隐私设计优先：用户随时可撤销授权，数据不离开 Fulcra 基础设施
• 生产级工具链：内置时区自动处理、睡眠阶段数学修正、数据新鲜度监控、图表生成
• 开源生态：MCP Server、Python Client 均开源，社区活跃

潜在缺点与局限性

• iOS 生态依赖：核心数据采集依赖 iOS Context App，Android 仍在开发中
• 数据新鲜度风险：Apple Watch 同步失败、Fulcra 服务中断会导致数据滞后（需主动监控）
• UTC 日期边界：睡眠聚合 API 按 UTC 日历日分桶，晚间调用易现"PM bug"，需使用工具函数修正
• 无内置 LLM 调用：生成自然语言简报需在代理层自行集成模型

适合人群

• 需要 深度健康情境感知 的 AI 代理开发者
• 个人用户构建 自动化健康工作流（如 Notion/Obisidian 同步、家庭自动化）
• 研究人员进行 纵向健康数据分析（注意：非医疗级认证）

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 数据过度暴露 | 代理可能请求过多敏感指标 | 遵循最小权限原则，定期审计授权范围 |

| 时区/DST 错误 | 硬编码时区导致睡眠时段计算错误 | 强制使用 `fulcra_timezone` 工具函数 |

| 公开泄露 | 演示截图含真实生物特征数据 | 使用合成数据（`FULCRA_DEMO_MODE`）标注 |

| 自动化误判 | 基于 HRV 的"压力"推断可能误伤 | 结合多日趋势，保留用户手动覆盖 |

关键工具函数

• get_last_night_sleep()：正确使用 sleep_cycles.total_time_asleep_ms 避免20%低估
• get_user_tz()：从 Fulcra profile 获取时区，自动处理夏令时
• fulcra_data_watchdog：Cron 定时检测数据新鲜度，失效告警

---

> 配套技能：fulcra-annotations 用于写入事件/记忆，形成读写闭环。

核心用法

Fulcra Context 是一套面向AI Agent的健康与场景数据访问基础设施，采用读取优先（read-only）架构设计。该技能通过三种主要方式与Fulca平台交互：MCP Server（推荐，支持Claude Desktop、Cursor等主流IDE）、Fulcra CLI（适合自动化脚本与定时任务）、以及Python Service Layer（遗留SDK兼容）。用户完成OAuth2授权后，Agent可访问涵盖心血管、呼吸、睡眠、活动、营养等9大类共188种健康指标，同时支持日历事件、地理位置等上下文数据读取。

典型工作流包括：调用 fulcra-api sleep-stages 获取睡眠分期数据，结合心率变异性（HRV）评估用户恢复状态；通过 calendar-events 读取日程安排，实现会议前能量水平预警；利用 location-at-time 获取位置上下文，触发差旅场景的智能适配。技能内置完善的时区处理、数据新鲜度检测、合成数据生成等生产级工具链，支持从个人健康分析到企业级健康管理的多样化场景。

显著优点

数据维度全面且专业：覆盖188项健康指标，包括Apple Health深度集成的睡眠分期、心律不齐事件、6分钟步行测试等临床级数据，以及步态不对称性、跑步触地时间等运动生物力学参数，远超一般穿戴设备API的数据粒度。

隐私架构先进：采用OAuth2用户授权模式，所有凭证存储于用户本地 ~/.config/fulcra/，支持随时撤销授权；明确区分读取型技能（fulcra-context）与写入型技能（fulcra-annotations），最小权限原则设计清晰。

工程成熟度高：提供MCP、CLI、Python SDK三层抽象，兼容Hermes、Claude、ChatGPT、Codex等主流Agent平台；内置UTC/本地时区自动转换、数据新鲜度监控（Data Watchdog）、睡眠阶段数学修正等 battle-tested 工具，避免常见时区bug和睡眠时长计算误差。

生态开放透明：MCP Server与Python客户端完全开源（GitHub可查），官方提供演示Notebook和Discord社区支持，企业用户可通过付费扩展获得高级功能。

潜在缺点与局限性

平台锁定风险：核心数据存储于Fulcra云服务，虽支持5GB免费永久存储，但深度依赖Fulcra的iOS App进行数据采集（Android版本即将推出），跨平台迁移成本较高。

实时性受限：数据同步依赖Apple Health的批处理机制，心率等指标可能存在15-60分钟延迟，不适合需要毫秒级响应的实时健康监控场景。

开发门槛存在：CLI安装要求Python 3.11+和uv工具链，对非技术用户不够友好；MCP配置涉及JSON编辑，虽提供模板但仍需一定技术背景。

数据覆盖不均：营养、生殖健康等类目依赖用户主动记录，若用户未在Apple Health或其他数据源中输入，则API返回为空，需要Agent设计容错逻辑。

适合的目标群体

• 量化自我（Quantified Self）爱好者：希望用AI分析长期健康趋势、优化睡眠与运动表现的高级用户
• 健康科技开发者：构建个性化健康教练、企业 wellness 平台、临床研究数据管道的工程师团队
• 高绩效知识工作者：需要Agent根据生理状态（HRV、睡眠质量）智能调整日程强度和时间管理的用户
• 数字健康初创公司：寻求合规、可扩展的健康数据基础设施，避免自建HIPAA/GDPR合规体系的重投入团队

使用风险与注意事项

供应链安全风险：技能通过subprocess调用外部fulcra-api CLI工具，若环境变量FULCRA_CLI_COMMAND被篡改或CLI二进制文件被替换，可能导致命令注入。建议验证CLI来源完整性，生产环境优先使用MCP Server而非CLI模式。

敏感数据合规风险：处理心率、位置、日历等GDPR/CCPA定义的敏感数据，需确保用户明确知情同意，避免将真实数据用于公共演示或模型训练。技能内置synthetic data生成工具，文档截图务必使用合成数据。

数据同步故障风险：Apple Watch同步失败、Fulcra服务中断可能导致数据陈旧，建议启用fulcra_data_watchdog定时检测，设置>12小时无数据即告警的监控策略。

授权凭证管理风险：~/.config/fulcra/credentials.json包含访问令牌，需确保文件权限为0600，避免多用户共享系统时的权限泄露。