Nestling

nestling-ts

用于 Nestling baby tracking app 的 TypeScript 客户端、CLI 和 MCP 服务。读取并记录 Nestling 账户中的睡眠、喂养、换尿布和日记数据——可通过终端、TypeScript/Bun 库，或通过 Model Context Protocol 服务供 Claude、ChatGPT 和其他 AI 助手使用。

仅支持创建记录。 API 可以记录会同步到应用的新条目，但无法更新或删除已有条目——你的数据始终安全。

要求

• Bun 1.3+ — 此软件包直接提供 TypeScript 源码，无需构建步骤，因此必须在 Bun（而非 Node）上运行。
• Nestling 账户（使用 Google 或 Apple 登录）
• Nestling API 令牌（在应用中生成：Settings → Data → API Token）

安装

从 npm 安装：

bun add -g nestling-ts
# provides `nestling` and `nestling-mcp`

# or add it to a project as a library
bun add nestling-ts

从源代码检出目录安装：

cd nestling-ts
bun install
bun link          # makes `nestling` available globally

CLI

快速开始

nestling login
# API Token: (from Nestling app → Settings → Data → API Token)
# Timezone: Europe/London
# ✓ Authenticated as [email protected]! Found 1 child(ren).

nestling babies
# • Eloise (id: abc-123)  8 months old

如果你尚未运行 bun link，请改用软件包脚本：

bun run --cwd /path/to/nestling-ts nestling -- login
bun run --cwd /path/to/nestling-ts nestling -- babies

命令

# Sleep
nestling sleep history --days 3
nestling sleep log --start "yesterday 8pm" --end "today 6:30am"
nestling sleep log --start 2026-05-07T20:00:00Z --end 2026-05-08T06:30:00Z

# Feed
nestling feed history --days 2
nestling feed log --at "now" --type Bottle --amount 180
nestling feed log --at "30m ago" --type Breastfeeding --side Left

# Nappy
nestling nappy history --days 2
nestling nappy log --at "5 minutes ago" --type Wet

# Diary
nestling diary history --days 7
nestling diary log --at "today 3pm" --text "First time clapping!" --tags milestone,funny

# Multiple babies
nestling --baby "Eloise" sleep history

所有 history 命令都支持 --json，以输出机器可读的内容。--baby 标志用于按姓名或 ID 选择特定孩子（默认为第一个孩子）。

时间格式

所有时间参数都支持灵活、易读的格式：

格式	示例
ISO 8601	2026-05-07T20:00:00Z
日期 + 时间	2026-05-07 8pm、2026-05-07 20:00
相对日期	today 3pm、yesterday 8:30pm、tomorrow 7am
仅时间（今天）	3pm、3:30pm、15:30
相对时间	now、5 minutes ago、2 hours ago、30m ago

时间将根据你配置的时区解析（NESTLING_TIMEZONE 环境变量，或 ~/.config/nestling/config.json 中的 timezone）。

身份验证

配置存储在 ~/.config/nestling/config.json。

• 交互式登录：nestling login
• 环境变量（优先于配置文件）：
  • NESTLING_API_TOKEN
  • NESTLING_TIMEZONE（可选）

库的用法

import { Nestling } from "nestling-ts";

const client = new Nestling({
  apiToken: process.env.NESTLING_API_TOKEN!,
});

// Authenticate
await client.signIn();

// Account & babies
const user = await client.getUser();
const babies = await client.babies.list();
const baby = await client.babies.get(babies[0].id);

// History (all take a DateRange)
const range = {
  start: new Date("2026-05-01T00:00:00Z"),
  end: new Date("2026-05-08T00:00:00Z"),
};
await client.sleep.list(baby.id, range);
await client.feed.list(baby.id, range);     // breast | bottle | solids | expressing
await client.nappies.list(baby.id, range);  // wet | dirty | both
await client.diary.list(baby.id, range);    // journal entries & milestones

// Log new entries
await client.sleep.create(baby.id, {
  start: "2026-05-07T20:00:00Z",
  end: "2026-05-08T06:30:00Z",
});

await client.feed.create(baby.id, {
  timestamp: "2026-05-07T12:00:00Z",
  type: "Bottle",
  amountMl: 180,
});

await client.nappies.create(baby.id, {
  timestamp: "2026-05-07T14:00:00Z",
  type: "Wet",
});

await client.diary.create(baby.id, {
  timestamp: "2026-05-07T15:00:00Z",
  text: "First time clapping!",
  tags: ["milestone"],
});

await client.close();

云端兼容性

nestling-ts 在写入与 iOS 兼容的云端模型时，会使用便于调用的 API 名称。例如，client.feed.create() 接受 amountMl 和 durationSeconds，然后在 Supabase 中将其存储为喂养负载键 amount 和 duration。条目负载会以 JSON 字符串的形式写入 entries.data，以匹配当前的 iOS 同步实现。

添加新工具或直接写入 Supabase 时，请遵循根目录 README 中规定的规范条目传输格式。具体而言，喂养值应使用 Breastfeeding、Bottle、Solids、Expressing；尿布值应使用 Wet、Dirty、Both；睡眠 source 值应使用 manual 或 timer。

MCP 服务

nestling-ts 将 MCP 服务作为 nestling-mcp 可执行文件提供。它将库封装为一组 MCP 工具，供任何 AI Agent 调用，包括 Claude、ChatGPT，以及其他支持 MCP 的大模型接口。

该服务支持两种传输模式：

• stdio（默认）——用于 Claude Desktop、Claude Code、Cursor 等本地应用。
• HTTP（--http）——通过网络提供远程 Streamable HTTP 传输，适用于 Claude 自定义连接器、ChatGPT 自定义连接器，或任何兼容 MCP 的客户端。

Claude Desktop / Claude Code（stdio）

指向源代码检出目录：

{
  "mcpServers": {
    "nestling": {
      "command": "bun",
      "args": ["run", "nestling-mcp"],
      "cwd": "/absolute/path/to/nestling-ts",
      "env": {
        "NESTLING_API_TOKEN": "your-token-from-nestling-app",
        "NESTLING_TIMEZONE": "Europe/London"
      }
    }
  }
}

**注意：**命令必须是 bun/bunx，而不是 node/npx。此软件包以原始 TypeScript 形式发布，由 Bun 直接执行。

Claude 自定义连接器（远程 MCP / HTTP 模式）

托管版（最简单，无需设置）：

1. 在 Claude 中，前往 自定义 → 连接器 → 添加自定义连接器（Pro/Max），或请组织所有者添加（Team/Enterprise）。
2. 将 URL 设为 https://mcp.nestling-app.com/mcp，然后点击 添加。
3. Claude 会打开登录页面——粘贴你从 Nestling → 设置 → 数据 → API Token 获取的 API token。
4. 完成。Claude 现在可以读取并记录宝宝的数据。

无需 ngrok、端口或自托管。每位用户都通过 OAuth 使用自己的 token 进行身份验证。

自托管：

自行以 HTTP 模式运行 MCP 服务：

# Single-user (token from env)
export NESTLING_API_TOKEN="your-token"
bun run nestling-mcp -- --http
# Nestling MCP server (HTTP) listening on http://localhost:8787/mcp

# Multi-user (no env token; each request authenticates via Bearer header)
bun run nestling-mcp -- --http
# Users pass their own token as Authorization: Bearer <token>

使用 PORT=3000 bun run nestling-mcp -- --http 设置自定义端口。

如需公开访问，请将服务置于 HTTPS 后面（Cloudflare Tunnel、nginx 等）——Claude 从 Anthropic 的云端连接，因此 localhost 无法使用。

ChatGPT 自定义连接器

ChatGPT 支持在 GPT Builder 中将 MCP 工具服务用作自定义连接器。使用托管端点或自行运行：

1. 使用托管 URL，或在服务上运行 bun run nestling-mcp -- --http。
2. 在 ChatGPT GPT Builder → Actions →“Add action”。
3. 将服务 URL 设为你的 /mcp 端点。
4. 将身份验证设为 Bearer，并粘贴你的 Nestling API token。
5. ChatGPT 会通过 MCP 协议自动发现工具。

工具

工具	用途
get_capabilities	发现：有哪些数据源和工具可用
get_user	账户资料（邮箱、用户 ID）
list_babies	宝宝列表（id 会传递给其他每个工具）
get_baby	宝宝详情（昵称、出生日期等）
list_sleep	指定日期范围内宝宝的睡眠记录
list_feeds	指定日期范围内的喂养记录（母乳、奶瓶、辅食）
list_nappies	指定日期范围内的尿布记录
list_diary	指定日期范围内的日记记录
create_sleep	记录新的睡眠时段（开始时间 + 结束时间）
create_feed	记录新的喂养（母乳、奶瓶、辅食、吸奶）
create_nappy	记录新的换尿布记录
create_diary	记录新的日记条目

读取工具会返回数据；写入工具会创建新条目（不支持更新或删除）。

响应封装

{
  "data": [...],
  "totalResults": 12
}

错误封装

{
  "error": "BabyNotFoundError",
  "message": "Baby not found: abc",
  "category": "not_found",
  "retryable": false,
  "recovery": "Use client.babies.list() (or the list_babies MCP tool) to get valid baby IDs."
}

安全性

• 仅创建写入——API 可以添加新条目，但不能更新或删除已有条目。
• 用户范围限定——通过 Supabase Auth 以普通 Nestling 用户身份进行身份验证。行级安全确保你只能访问自己的宝宝和数据（以及与你共享的数据）。
• 不使用服务密钥——使用 Supabase anon 密钥，而非服务角色密钥。anon 密钥可以安全分发；它只允许受 RLS 保护的访问。
• 本地或自托管远程——在 stdio 模式下，凭据保留在你的设备上。在 HTTP 模式下，每位用户在每个会话中都使用自己的 Bearer token 进行身份验证。
• 按用户隔离——HTTP 服务会为每个 token 创建单独的已验证会话。用户只能通过 Supabase RLS 访问自己的数据。
• 短期会话——Supabase JWT 会在 1 小时后过期，并自动刷新。你的长期 API token 仅用于初始化会话。

获取 API 令牌

1. 在手机上打开 Nestling 应用。
2. 前往 Settings → Data → API Token。
3. 点击 Copy Token。
4. 将令牌粘贴到 MCP 配置或环境变量中。

该令牌与你的账号绑定。你可以随时再次点击 API Token 撤销令牌并生成新令牌；生成新令牌后，旧令牌将失效。

API 参考

new Nestling(options)

Option	Type	Notes
apiToken	string	Nestling 应用中的 API 令牌

读取方法

• client.babies.list() → Baby[]
• client.babies.get(babyId) → Baby
• client.sleep.list(babyId, range) → SleepEntry[]
• client.feed.list(babyId, range) → FeedEntry[]
• client.nappies.list(babyId, range) → NappyEntry[]
• client.diary.list(babyId, range) → DiaryEntry[]

写入方法

• client.sleep.create(babyId, input) → string（新条目 ID）
• client.feed.create(babyId, input) → string
• client.nappies.create(babyId, input) → string
• client.diary.create(babyId, input) → string

错误类

• NestlingError — 基类，包含 category、retryable、recovery
• AuthenticationError — 凭据错误或会话已过期
• BabyNotFoundError — 未知的宝宝 ID
• InvalidDateRangeError — start >= end，或输入不是 Date

开发

bun install
bun link               # register `nestling` and `nestling-mcp` on your PATH
bun test               # run the test suite
bun run lint           # tsc --noEmit
bun run nestling       # run the CLI (e.g. bun run nestling -- babies)
bun run mcp            # start the MCP server locally

语音助手

Siri

内置于 iOS 应用中，无需设置。可以说：

• "Log nappy in Nestling"
• "Start sleep in Nestling"
• "Log breastfeed in Nestling"
• "Log bottle in Nestling"

适用于 iOS 16+ 的快捷指令应用。

Alexa

alexa/ 目录包含一个可自托管的 Alexa 技能，可通过语音追踪喂养、睡眠和换尿布。它作为 Lambda 函数运行在你自己的 AWS 账号中。

语音命令

要执行的操作	说
开始睡眠	"Alexa, tell Nestling to start sleep"
结束睡眠	"Alexa, tell Nestling to stop sleep"
暂停 / 恢复睡眠	"Alexa, tell Nestling to pause sleep"
记录尿湿尿布	"Alexa, tell Nestling to log a wee nappy"
记录脏尿布	"Alexa, tell Nestling to log a poo nappy"
记录尿湿且弄脏的尿布	"Alexa, tell Nestling to log a wet and dirty nappy"
开始母乳喂养	"Alexa, tell Nestling to start nursing"
换边	"Alexa, tell Nestling to switch sides"
结束母乳喂养	"Alexa, tell Nestling to stop nursing"
记录奶瓶喂养	"Alexa, tell Nestling to log a 120 ml bottle"
记录辅食	"Alexa, tell Nestling to log sweet potato"
上次睡眠	"Alexa, ask Nestling for the last sleep"
上次喂养	"Alexa, ask Nestling for the last feed"
上次换尿布	"Alexa, ask Nestling for the last nappy"

nappy/diaper 和 wee/pee 两种说法均可识别。

前提条件

• 具有部署 CloudFormation 堆栈和 Lambda 函数权限的 AWS 账号
• Alexa Developer account（免费）
• 已添加至少一个宝宝的 Nestling 账号
• Nestling 应用中的 API 令牌（Settings → Data → API Token for AI Access）
• Node.js 20+ 和 npm
• SAM CLI

部署

cd alexa
npm install
npm run build
sam build
sam deploy --guided

SAM 会提示输入：

Parameter	Description	Example
NestlingApiToken	应用中的 API 令牌	（base64 字符串）
Timezone	用于语音时间的 IANA 时区	Europe/London

堆栈部署完成后，从输出中复制 Lambda ARN。

连接到 Alexa

1. 打开 Alexa Developer Console
2. 创建新的 Custom 技能（选择“Provision your own”托管方式）
3. 前往 Build → Interaction Model → JSON Editor
4. 粘贴 alexa/skill/interactionModel.json 的内容
5. 在 Endpoint 下，选择 AWS Lambda ARN 并粘贴你的 Lambda ARN
6. 点击 Save Model，然后点击 Build Model
7. 在 Alexa 模拟器或你的设备上进行测试

更新

代码更改或 API 令牌更新后：

cd alexa && npm run build && sam build && sam deploy

安全性

• 你的 API 令牌以加密的 Lambda 环境变量形式存储（NoEcho）
• 它绝不会被记录到日志中，也不会包含在 Alexa 响应里
• 所有 Supabase 查询都通过行级安全策略执行 — 令牌只能访问你自己的数据

限制

• 仅支持创建。 不支持更新或删除。新条目会自动同步到应用。
• 仅支持 Bun。 CLI 和库需要 Bun。Alexa 技能使用 Node.js（部署为 Lambda）。

许可证

MIT