Syncky Health

Syncky：开放协议、参考 Agent 和参考服务

Syncky Health 是一款 iPhone 应用，可将 Apple Health 数据传输到用户自己的服务器或 AI Agent，并将记录写回 Health。客户端健康数据信封采用端到端加密（HPKE Auth + ChaCha20-Poly1305）：中继只能看到投递元数据并发送明文中心通知，但看不到健康数据值。应用也可以直接向用户运行的服务器发送数据，完全不经过中继。用户的 Agent 或服务器会收到明文，而所选模型可以看到 Agent 提供的内容。

为 MCP 客户端安装

需要 Node.js ≥22.15 和 npm。npm 包内嵌运行时所需的包，没有运行时依赖项。所有者发布 npm 包后，使用以下命令启动本地 stdio 服务：

npx -y @syncky/agent mcp

对于 JSON 配置使用 mcpServers 的客户端：

{"mcpServers":{"syncky":{"command":"npx","args":["-y","@syncky/agent","mcp"]}}}

请先使用 SKILL.md 或操作员指南完成配对。选择自定义主目录时，设置期间和 MCP 客户端环境中使用相同的 SYNCKY_AGENT_HOME。仅授予你希望共享的读取／写入类型。iOS 后台调度和已解锁的手机会影响数据投递；这不是实时数据流。

Cursor

添加到 Cursor

默认主目录为 ~/.syncky-agent；仅在使用自定义主目录时添加 env.SYNCKY_AGENT_HOME，并使用接收器所用的同一已初始化／已配对主目录的绝对路径。JSON 环境变量值不会展开 $HOME 或 ~；请使用实际路径，包括在 Windows 上。

手动配置时，将此服务合并到全局 ~/.cursor/mcp.json 或项目 .cursor/mcp.json 中，并保留其他服务：

{"mcpServers":{"syncky":{"command":"npx","args":["-y","@syncky/agent","mcp"]}}}

Cursor 默认启用 MCP 工具审批。不要自动允许 syncky_send 或 syncky_ack；仅审批你有意执行的写入、诊断请求和访问请求。Cursor 的 mcp.json 无法禁用单个工具，因此此配置会让两个修改数据的工具都保持可用，并非只读设置。你可以在 Customize 中切换整个服务。配对、所选类型、Agent 写入范围、允许写入 Health、iOS 权限以及操作员指南中的安全规则仍然适用。已排队的写入不等于已应用的写入。MCP 不会启动接收器，也不会完成配对；每个主目录仅运行一个接收器。

Claude Desktop

对于手动本地设置，官方 MCP 教程通过 Anthropic 的本地服务文档指定了 Settings → Developer → Edit Config。在 macOS 上，文件路径为 ~/Library/Application Support/Claude/claude_desktop_config.json；在 Windows 上，文件路径为 %APPDATA%\Claude\claude_desktop_config.json。合并此服务，同时保留其他条目：

{"mcpServers":{"syncky":{"command":"npx","args":["-y","@syncky/agent","mcp"]}}}

保存后，完全退出并重启 Desktop，以启动本地 stdio 服务。该服务以你的用户账户运行。通过 + → Connectors 或 Local MCP servers 设置查看工具；当前的 Anthropic 帮助文档介绍的是 Settings → Desktop app → Manage Extensions，较早的布局则是 Settings → Extensions。检查权限请求，并仅批准预期的操作。此注册不会禁用写入。使用同一配对主目录和单独的接收端；MCP 不会执行配对，也不会启动接收端。对于自定义主目录，可在手动服务条目中添加 env.SYNCKY_AGENT_HOME，并将其设为配对主目录的绝对路径。

Anthropic 说明了如何在 Extensions → Advanced settings → Install Extension 下导入自定义 .mcpb，并发布了清单规范，当前版本为 0.3。这说明了架构和导入机制；本地打包测试并不能证明 Claude Desktop 会接受 Syncky 的归档文件。请留意下文的 MCPB 兼容性说明。随附的捆绑包没有自定义主目录的 UI 字段；如需使用自定义主目录，请通过手动环境配置进行设置。

VS Code Copilot

对于本地项目，Microsoft 的配置参考指定在工作区的 .vscode/mcp.json 中使用 servers 和显式 stdio 类型：

{"servers":{"syncky":{"type":"stdio","command":"npx","args":["-y","@syncky/agent","mcp"]}}}

当前设置指南仍将其保留为兼容格式，但在引导式添加服务流程中已弃用。符合条件的条目会转发到 Copilot 会话；该运行框架不会直接读取此文件，并会排除需要交互式输入的配置。此示例不需要交互式输入。命令会在托管进程的计算机上运行；此方案使用配对数据库所在计算机上的本地项目。远程工作区和容器需要单独检查其运行时和存储。

信任工作区之前，请先检查配置：受限模式会阻止工作区服务，而受信任的工作区可以在没有单独 MCP 信任提示的情况下启动服务。使用 MCP: List Servers → Start Server、更改后使用 Restart Server，或使用 Show Output 进行诊断；请参阅服务管理。在 Copilot Agent 会话中，Chat: Open Customizations → Tools 用于控制工具可用性；Local 运行框架使用 Configure Tools。如需只读操作，请勿选择 syncky_send 和 syncky_ack。选择 Manual permissions 并检查自动批准设置；工具选择和审批属于客户端策略，而非此 JSON 中的字段。此注册不会禁用写入，也不会启动接收端。可选的 env.SYNCKY_AGENT_HOME 接受与接收端所用的同一配对主目录的绝对路径。

Windsurf

供应商的 Windsurf Cascade MCP 配置说明了本地 stdio 和 mcpServers。在 Cascade 的 MCP 菜单中选择 打开 MCP 配置文件，然后将此服务合并到打开的文件中，并保留其他条目：

{"mcpServers":{"syncky":{"command":"npx","args":["-y","@syncky/agent","mcp"]}}}

当前默认路径为 macOS/Linux 上的 ~/.config/devin/mcp_config.json，或设置了 $XDG_CONFIG_HOME 时的 $XDG_CONFIG_HOME/devin/mcp_config.json；Windows 上为 %AppData%/devin/mcp_config.json。请使用你的安装所打开的文件，包括隔离构建版本。较旧的 ~/.codeium/windsurf/mcp_config.json 是单独的稳定版编辑器发现来源，不一定是 Cascade 当前使用的文件。

保存手动配置后，点击 MCP 面板中的刷新按钮。供应商的 + 添加服务 操作属于插件／模板流程。团队策略可能会限制 MCP 或服务配置。本配置不声称存在默认批准设置或按工具禁用字段；它不会禁用写入。除非有意为之，否则请在 iPhone 上关闭写入，并遵循操作员安全规则。本地 MCP 读取相同的配对主目录，并且需要单独的接收器。对于自定义主目录，env.SYNCKY_AGENT_HOME 使用其配对主目录的绝对路径。不表示远程会话存储与之等同。

其他 MCP 客户端

ChatGPT 桌面版（Mac 和 Windows）、Codex CLI 和 IDE 扩展使用通用只读配置。

Claude Code 可以安装市场插件及其 MCP／技能插件：

/plugin marketplace add syncky/syncky-open
/plugin install syncky@syncky

或者仅注册该服务：

claude mcp add --transport stdio syncky -- npx -y @syncky/agent mcp

Gemini CLI 的扩展参考说明了 GitHub 安装（需要 Git）、根目录中的 gemini-extension.json、启动时的 MCP 注册，以及通过 contextFileName 加载上下文。Syncky 的清单将 SKILL.md 指定为扩展上下文，并使用 command: "npx" 和 args: ["-y", "@syncky/agent", "mcp"] 注册本地 stdio。请在交互会话之外的终端中运行以下命令：

gemini extensions install https://github.com/syncky/syncky-open

查看安装确认信息，然后重启 Gemini CLI 会话；扩展管理变更会在重启后生效。在会话中使用 /extensions list 检查安装情况。此注册不会禁用写入或启动接收器：请使用相同的配对主目录和单独的接收器，先通过 syncky_status 检查范围，并遵循操作员安全规则，仅在明确需要时请求写入。工具批准取决于客户端策略；请参阅官方 MCP 参考。

其他支持技能的 Agent 可以使用根目录中的 SKILL.md。插件的 plugins/syncky/skills/syncky/SKILL.md 包含相同的说明。这些仓库技能使用 npm；它们不包含可执行文件。对于无法访问 npm 的宿主，发行版提供的四个技能归档包包含本地启动器和捆绑包。其中内置的 Claude Code MCP 注册使用本地捆绑包离线运行；仓库插件则使用 npm。

MCPB 是另一种选择：从匹配的 GitHub 发行版下载 syncky-health.mcpb、其 .sha256 校验文件和 SHA256SUMS，验证摘要并将捆绑包导入兼容的客户端。仍然需要 Node ≥22.15。校验和可检测损坏，但无法验证遭到篡改的发行版。同一发行版还提供独立捆绑包及其校验文件。

注册表与发布准备

根目录中的 server.json 是一份不可发布的源草稿，列出了 npm 和 MCPB。它有意省略了 MCPB 哈希。构建完成后，在构建目录之外生成发布资源，例如生成到一个全新的临时目录中：

(cd agent && npm ci && npm run build)
release_dir=$(mktemp -d)
node prepare-registry.mjs server.json agent/package.json agent/dist "$release_dir/server.json"
node --test test/*.test.mjs

辅助脚本会计算实际的 MCPB SHA-256，并要求其与旁置文件和校验和列表一致。标签工作流会以只读仓库权限构建、测试并准备发布，然后将准备好的目录上传为构件。单独的发布作业使用 OIDC 和发布写入权限下载该构件，通过 release.mjs 重新检查版本、清单、包元数据、文件清单和哈希，使用 npm OIDC／来源证明发布经过测试的 tarball，并附上已验证的资源。只有构建作业会运行 Agent 依赖项和打包后的运行时自检；发布作业既不安装 Agent 依赖项，也不执行该包。npm 版本查询成功但结果为空，表示该版本尚未发布；查询失败仍视为错误。它不会发布到 MCP Registry。

Registry 架构 2025-12-11 和包字段在所有者通过 mcp-publisher init 核对之前，均属于草稿假设。MCPB 格式 0.3 是一项兼容性假设；本地 ZIP／清单／运行时测试不能证明 Claude Desktop 会接受它。只有经过架构核对后生成的发布版 server.json，才是所有者可提交到 Registry 发布的候选文件。在所有者开启此仓库并完成首次发布之前，不声称任何一种分发方式已经可用。

在配置 npm 信任或创建第一个标签之前，所有者必须检查 @syncky/agent 是否已存在，以及仅通过工作流的受信任发布能否完成首次发布。账户／2FA、对 syncky 组织的所有权、公共仓库的可用性，以及绑定到 syncky/syncky-open / release.yml 的信任，均为所有者必须满足的条件。如果创建包需要其他认证方式，该决定仍未解决：此处未授权进行令牌引导。实际的 Desktop 验证、Registry 发布以及扩展／插件客户端的接受情况，也需由所有者检查。

本仓库包含开发者构建另一端所需的一切：

文件夹	内容
protocol/	各实现用于自我验证的架构、类型目录 types.json、单位表 units.json 和测试向量；服务端集成指南；HealthKit 数据类型清单
agent/	syncky-agent，Syncky Agent（Node 22）：配对、端到端加密、保存 iPhone 发送内容的本地收件箱（保留 30 天）、向 iPhone 发送消息（Health 写入、诊断信息，以及所有者在手机上批准的访问请求），以及供本地客户端使用的 MCP 服务。使用任意语言集成你自己的 Agent，请参阅 agent/AGENTS.md；供运行该服务的 AI Agent 使用的操作指南，请参阅 agent/SETUP.md；所有错误代码和限制请参阅 agent/docs/REFERENCE.md
examples/minimal-agent/	一个 Node 文件，演示完整的中继流程，从注册到手机确认写入
examples/browser-demo/	仅在浏览器标签页中运行的演示 Agent，访问 https://demo.syncky.app：配对应用、查看收到的解密样本、发送写入；它不会存储任何内容
examples/minimal-server/	一个不依赖其他项的 Node 文件，可接收应用以各种格式直接发送的数据、检查身份验证和签名，并写回数据

本仓库不包含：iOS 应用、生成 types.json、units.json 和测试向量的 Syncky 核心，以及中继服务。此处不会手动编辑生成的文件；当测试向量与说明文字不一致时，以测试向量为准。

此仓库承诺与不承诺的内容

此处的代码和文档描述 Syncky 应用和中继服务当前的行为；它们按现状依据 Apache License 2.0 发布（参见 NOTICE），不保证任何安全、隐私或医疗方面的特性。中继服务无法读取密封信封，但由此仓库构建的 Agent 或服务会以明文接收健康数据；运行它的任何人都有责任依照适用法律处理这些数据；Syncky 的隐私政策（https://syncky.app/privacy）和条款（https://syncky.app/terms）仅适用于应用和中继服务。Syncky 是数据传输工具，不是医疗设备：它传输的任何内容都不是医疗建议。

测试

Node 22.15 或更高版本，且属于 22 系列。

(cd agent && npm ci && npm test)
(cd examples/minimal-agent && npm ci && npm test)    # its tests use agent/ helpers: install agent/ first
(cd examples/minimal-server && npm test)             # no dependencies
(cd examples/browser-demo && npm ci && npm test)

许可与安全

Apache License 2.0，参见 LICENSE。请按照 SECURITY.md 中的说明私下报告漏洞。

当前的精简运行时仅开放 syncky_status、syncky_inbox、syncky_send、syncky_ack 和 syncky_skill，以及经过验证的 syncky://skill 资源。状态、收件箱和技能可离线读取本地状态，不会联系中继服务或获取更新。只读客户端会同时禁用发送和确认。只有通用发送功能会在所有者明确批准后执行写入、诊断请求和访问请求；手机端同意、选择、Agent 范围、Health 写入权限以及 iOS 权限仍具有决定效力。请求审批与写入 Health 值的权限彼此独立。原始结果和每个版本对应的所有手机端结果都通过收件箱读取；已排队／已发送并不表示已应用。请在其他位置单独启动一个接收服务；MCP 不会启动接收器、心跳或后台重试。历史记录以原始 JSONL 格式保留 30 天，不包含本地策略、账本、摘要、单位转换或序列重组。请求生成报告时，必须明确批准目标位置。请参阅操作员安全规则。