JinDaGe - pulsyn-mcp-server MCP Details

article

README

🚀 Pulsyn MCP Server

通过模型上下文协议，你可以直接在AI助手访问Pulsyn智能戒指的健康数据。

🚀 快速开始

1. 获取API令牌

打开Pulsyn移动应用。
导航至设置 → API访问。
点击**“创建新令牌”**。
选择read:health_data范围。
复制令牌（以psk_开头）。

2. 配置令牌

export PULSYN_API_TOKEN=psk_your_token_here

3. 添加到Claude桌面应用

将以下内容添加到你的Claude桌面应用配置文件中（macOS系统路径为~/Library/Application Support/Claude/claude_desktop_config.json，Windows系统路径为%APPDATA%/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "pulsyn": {
      "command": "bunx",
      "args": ["pulsyn-mcp-server"],
      "env": {
        "PULSYN_API_TOKEN": "psk_your_token_here"
      }
    }
  }
}

✨ 主要特性

睡眠追踪：包括睡眠时长、睡眠阶段（深度/浅度/快速眼动/清醒）、质量评分和效率。
心率变异性分析：测量心率变异性，以了解恢复情况和压力水平。
心率监测：持续监测心率并记录静息心率。
活动数据：记录步数、卡路里消耗、活跃分钟数和运动距离。
身体状态评分：结合睡眠、心率变异性和恢复情况给出每日身体状态评分。
健康摘要：提供全面的每日健康快照。

📦 安装指南

使用bunx（推荐）

无需安装，直接运行：

bunx pulsyn-mcp-server

使用npm

npm install -g pulsyn-mcp-server
pulsyn-mcp-server

从源代码安装

git clone https://github.com/getpulsyn/pulsyn-mcp-server.git
cd pulsyn-mcp-server
bun install
bun run build

📚 详细文档

环境变量

| 属性 | 详情 | |------|------| | PULSYN_API_TOKEN | 必需。你的Pulsyn API令牌（以psk_开头） | | PULSYN_API_URL | 可选。自定义API URL（默认值：https://www.getpulsyn.com/api/v1） | | PULSYN_DEBUG | 可选。启用调试日志记录（值为true/false） |

配置文件

你也可以创建~/.config/pulsyn-mcp-server/config.json文件：

{
  "apiToken": "psk_your_token_here",
  "baseUrl": "https://www.getpulsyn.com/api/v1",
  "debug": false
}

💻 使用示例

可用工具

get_sleep_data

获取睡眠记录，包括睡眠时长、睡眠阶段、质量评分和效率。参数：

days（数字）：要获取数据的天数（默认值：7，最大值：90）
limit（数字）：最大结果数（默认值：100，最大值：1000）

示例提示：

"显示我上周的睡眠数据"
"我昨晚的深度睡眠百分比是多少？"

get_hrv_data

获取心率变异性测量数据，这是恢复情况和压力水平的关键指标。参数：

days（数字）：要获取数据的天数（默认值：7，最大值：90）
limit（数字）：最大结果数（默认值：100，最大值：1000）

示例提示：

"我这个月的平均心率变异性是多少？"
"显示我过去一周的心率变异性趋势"

get_heart_rate_data

获取连续的心率测量数据，包括静息心率。参数：

days（数字）：要获取数据的天数（默认值：7，最大值：90）
limit（数字）：最大结果数（默认值：100，最大值：1000）

get_activity_data

获取每日活动指标，如步数、卡路里消耗、活跃时间和运动距离。参数：

days（数字）：要获取数据的天数（默认值：7，最大值：90）
limit（数字）：最大结果数（默认值：100，最大值：1000）

get_readiness_score

获取结合睡眠、心率变异性和恢复情况的每日身体状态评分。参数：

days（数字）：要获取数据的天数（默认值：7，最大值：90）
limit（数字）：最大结果数（默认值：100，最大值：1000）

get_health_summary

获取特定日期的全面健康摘要。参数：

date（字符串）：日期，格式为YYYY - MM - DD（默认值：今天）

🔧 技术细节

速率限制

Pulsyn API根据账户等级实施不同的速率限制： | 功能 | 免费用户 | 付费用户 | |---------|-----------|-----------| | 速率限制 | 每个端点每秒1个请求 | 每个密钥每小时1000个请求 | | 范围 | 每个账户、每个端点 | 每个API密钥 | | 多端点调用 | ✅ 可以同时调用不同的端点 | ✅ 无每个端点的限制 | | 突发请求 | ❌ 同一端点请求之间必须等待1秒 | ✅ 可以快速连续请求 | | API密钥 | 1个密钥 | 最多10个密钥 | | 最大吞吐量 | 约每秒6个端点请求 | 每小时10000个请求（使用10个密钥） |

错误处理：

超过限制时返回429 Too Many Requests错误。
自动重试，采用指数退避和抖动算法。
遵循Retry - After头信息进行速率限制恢复。

安全措施

仅本地存储：令牌仅存储在你的设备上。
只读访问：无法修改你的健康数据。
仅使用HTTPS：所有通信均加密。
令牌撤销：可随时在Pulsyn应用中撤销令牌。

故障排除

| 问题 | 解决方案 | |-------|----------| | "No API token configured" | 设置PULSYN_API_TOKEN或创建配置文件 | | "Invalid or expired token" | 在Pulsyn应用中生成新的令牌 | | "Rate limit exceeded" | 等待限制重置（最长1小时） | | 连接超时 | 检查互联网连接 |

开发

# 以开发模式运行
bun run dev

# 运行测试
bun test

# 类型检查
bun run typecheck

# 代码检查
bun run lint

# 生产构建
bun run build

pulsyn-mcp-server