OpenPets 标志OpenPets
← 返回集成
Cursor

集成指南

已支持

Cursor + OpenPets

通过全局或项目 MCP 设置、可选项目规则、宠物路由、托管安全机制和冲突处理，将 Cursor 连接到 OpenPets。

此集成的功能

Cursor 集成为 Cursor 提供 OpenPets MCP 工具，以及一个可选的简短项目规则，用来告诉 Cursor 何时使用这些工具。它包含一个 MCP 层和一个可选的规则层；你可以只安装其中一个，或两个都安装。

组成部分是否必需？为 Cursor 提供的功能
MCP server 是 通过 @open-pets/mcp 提供 openpets_status、openpets_react 和 openpets_say 工具。
项目规则 可选 一个简短的 .mdc 规则，告诉 Cursor 何时使用 OpenPets 工具，以及哪些内容绝不能出现在宠物消息中。
Hooks / 生命周期反应 暂未支持 环境感知的 Cursor hooks 是未来阶段，在验证完成之前有意暂不写入。

运行时控制在本地进行。Cursor 以 stdio MCP server 的形式启动 @open-pets/mcp，server 使用 @open-pets/client，客户端通过本地 IPC 与运行中的 OpenPets 桌面应用通信。如果 OpenPets 已关闭，Cursor 仍可正常工作；宠物更新属于尽力而为的反馈。

快速安装

在 OpenPets 桌面应用中，打开 Integrations，使用 Cursor 卡片。Install global setup 为当前用户写入全局 Cursor MCP 条目，Configure 打开详情面板，包含宠物路由、JSON 预览和移除操作。

  • Install global setup 将 openpets MCP server 添加到 ~/.cursor/mcp.json。
  • Configure 打开高级状态、宠物路由、项目规则预览和移除控制。
  • 如果 OpenPets 工具未立即出现，请重启 Cursor、重载窗口或开启一个新对话。

桌面设置是全局的，会影响该机器上的每个 Cursor 项目。若需要按仓库进行设置，或要添加项目规则，请使用下方的 CLI 命令。

MCP 连接

MCP 是 Cursor 与 OpenPets 之间的主要桥梁。OpenPets 只会写入一个名为 openpets 的 MCP 条目；Cursor 配置中无关的 MCP server 与顶层字段都会被保留。

工具用途Cursor 应在何时使用
openpets_status 检查 OpenPets 桌面应用是否可达，以及当前目标宠物是哪个。 在使用 OpenPets 之前，或在调试设置时。
openpets_react 在不显示文本的情况下更改宠物反应。 用于静默状态变化，如思考、编辑、测试、等待、成功或错误。
openpets_say 显示一条简短的可见对话气泡。 用于有意义的进度通知、阻塞提示、完成通知或审核交接。

全局 MCP 与项目 MCP 配置

Cursor 会合并全局和项目 MCP 配置。当两者都定义了 openpets server 时，项目条目在该工作区中优先生效。OpenPets 始终使用 openpets 这个 server 名称，因此你可以按仓库覆盖全局默认设置。

设置方式适用场景文件
全局桌面设置 个人机器上全局可用的 Cursor 设置。 ~/.cursor/mcp.json
项目本地 CLI 设置 需要显式携带 OpenPets 设置的仓库。 <project>/.cursor/mcp.json

预期的 MCP 条目

~/.cursor/mcp.json 或 <project>/.cursor/mcp.jsonjson
{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@open-pets/mcp@latest", "--pet", "<pet-id>"]
    }
  }
}

若未选择宠物，则会省略 --pet <pet-id>，OpenPets 会路由到桌面默认宠物。OpenPets 在写入条目时会固定具体的 @open-pets/mcp 版本；上面的 @latest 仅为手动配置时易读的等价写法。

使用 CLI 进行项目设置

仅项目 MCPbash
npx -y @open-pets/cli@latest configure --agent cursor --pet <pet-id>
从其他目录配置项目 MCPbash
npx -y @open-pets/cli@latest configure --agent cursor --cwd /path/to/project --pet <pet-id>

--pet 是可选的。若未提供，CLI 可能会通过运行中的桌面应用从已安装的宠物中提示选择。

可选项目规则

Cursor 规则是提示词引导，而不是生命周期 hooks。OpenPets 的规则告诉 Cursor 何时以及如何安全地使用 MCP 工具。规则是可选的且仅在项目本地生效；OpenPets 不会修改 Cursor 的用户或全局规则设置。

仅安装或更新项目规则bash
npx -y @open-pets/cli@latest configure --agent cursor --rules-only
同时安装 MCP 和规则bash
npx -y @open-pets/cli@latest configure --agent cursor --pet <pet-id> --with-rules
仅移除托管规则bash
npx -y @open-pets/cli@latest configure --agent cursor --remove-rules

--rules-only 与 --remove-rules 不需要选择宠物，也不需要 OpenPets 桌面应用处于运行状态。规则文件会被写入：

规则路径text
<project>/.cursor/rules/openpets.mdc

规则内容

.cursor/rules/openpets.mdcmdc
---
description: Use OpenPets MCP tools for lightweight coding-status feedback.
---

<!-- OPENPETS:CURSOR_RULES:START -->
OpenPets status feedback
You may use the OpenPets MCP tools as a brief, safe status channel during meaningful coding work.
  • Use openpets_say sparingly for major milestones, blocking states, completion, or when review is needed.
  • Prefer openpets_react over speech for lightweight progress such as thinking, working, testing, success, or error.
  • Keep messages short, user-facing, and safe.
  • Do not send prompts, tool input/output, code, logs, stack traces, credentials, private file contents, URLs, file paths, or other sensitive content through OpenPets.
  • Do not spam every internal step; use OpenPets only for meaningful progress changes and continue normally if a status update is unnecessary.
  • If OpenPets is unavailable, continue the coding task without failing.
<!-- OPENPETS:CURSOR_RULES:END -->

OpenPets 有意不设置 alwaysApply: true，让规则默认不会出现在每个提示词中。当工作区打开时，Cursor 会包含该规则；规则变化后可能需要开启新对话才能被采纳。

强制覆盖、冲突与备份

OpenPets 默认不会覆盖未知的用户内容。当 MCP 条目或规则文件与 OpenPets 管理的内容不一致时，状态会显示为 custom 或 conflict，除非你明确选择覆盖，否则不会被改写。

强制替换，按范围执行bash
npx -y @open-pets/cli@latest configure --agent cursor --rules-only --force
npx -y @open-pets/cli@latest configure --agent cursor --pet <pet-id> --with-rules --force
  • MCP 替换仅影响 mcpServers.openpets。
  • 规则替换仅影响 .cursor/rules/openpets.mdc。
  • 任何替换或移除操作前都会创建备份。
  • --with-rules 会在写入任一文件前一起预检 MCP 与规则方案，避免出现半安装状态。

宠物路由

未选择宠物时，Cursor 会指向 OpenPets 桌面默认宠物。选择宠物后，OpenPets 会在 MCP 命令中添加 --pet <pet-id>，让 Cursor 指向该伴侣。

运行时路径text
Cursor
  -> OpenPets MCP server (@open-pets/mcp)
  -> @open-pets/client
  -> OpenPets desktop local IPC
  -> default pet or selected agent pet
  • 未选择宠物：MCP 指向桌面默认宠物。
  • 已选择宠物：MCP 参数中包含 --pet <pet-id>。
  • 显式宠物会话使用短租约，代理宠物可自动清理。
  • 如果请求的宠物缺失或不可用，OpenPets 会安全回退，而不会中断 Cursor。

Cursor 行为与注意事项

重启、重载或新对话

Cursor 加载 MCP 的方式会因版本和环境而异。如果安装后未出现 OpenPets 工具：

  1. 开启新的 Cursor 对话。
  2. 重载 Cursor 窗口。
  3. 完全重启 Cursor。
  4. 确认 Node 与 npm 能运行所配置的 npx 命令。

规则会作为对话上下文被引入，因此规则变化后也可能需要新对话才能生效。

WSL、远程与 devcontainer

OpenPets 桌面应用运行在本地操作系统上，MCP server 通过本地 IPC 连接桌面。如果 Cursor 在 WSL、远程主机或 devcontainer 中执行 MCP 命令，命令可能运行在无法访问桌面应用的环境中。

  • Cursor 可能显示 MCP 连接失败。
  • openpets_status 可能报告桌面不可达。
  • 所配置的 npx 或 node 命令可能在一个环境中可用，但在 Cursor 实际使用的环境中不可用。

解决方法取决于具体环境。OpenPets 目前不会自动写入针对 WSL 或 devcontainer 的 MCP 条目。

安全性与行为

OpenPets 将 Cursor 配置视为用户拥有的内容。MCP 与规则编辑都是受限范围、可审计、可回退的。

保护机制行为说明
受限的 MCP 编辑仅读取、写入、替换或移除 mcpServers.openpets；无关 server 与字段被完整保留。
受限的规则编辑仅触碰 .cursor/rules/openpets.mdc。其他规则文件和 .cursor 目录本身保持不变。
严格 JSON以严格 JSON 读取 MCP 配置。无法解析的文件会被归类为 invalid，而不是被改写。
大小限制MCP 配置读取上限为 256 KiB。规则读取上限为 64 KiB。
安全写入使用临时文件加原子重命名进行写入，任何替换或移除前都会创建备份。
拒绝符号链接拒绝处理符号链接配置文件、非常规文件、不安全的父路径和悬挂的符号链接。
托管识别仅当存在 OpenPets 的 frontmatter 和恰好一对有序标记时，规则才被视为托管；用户自有内容会被识别为冲突而不是被覆盖。
预览脱敏桌面预览仅显示 OpenPets 的 MCP 条目；更大范围的预览会对疑似敏感字段进行脱敏。
不写入宽泛权限OpenPets 不会写入 ~/.cursor/permissions.json，也不会添加宽泛的 MCP / 工具白名单。

故障排查

Cursor 未显示 OpenPets 工具

  • 开启新对话、重载窗口或完全重启 Cursor。
  • 确认 OpenPets 桌面应用正在运行，并在 Cursor 详情面板点击 Refresh。
  • 在终端运行 npx -y @open-pets/mcp@latest --help，确认 npm 能解析到该包。
  • 如果 Cursor 运行在 WSL、远程或 devcontainer 中，请参考上面的注意事项。

OpenPets 提示 MCP 条目为自定义或冲突

自定义或冲突状态意味着现有的 openpets 条目、MCP 配置文件或规则文件与 OpenPets 所管理的内容不匹配。OpenPets 不会主动改写。仅当你希望 OpenPets 重新创建其托管条目或文件时，才在详情面板使用 Replace，或在 CLI 中加上 --force 标志。

出现错误的宠物

使用所需的宠物 ID 重新运行安装。如果该宠物未安装、无效或已损坏，桌面应用会回退到默认宠物。

刷新项目设置bash
npx -y @open-pets/cli@latest configure --agent cursor --pet <pet-id> --cwd . --force

移除或重置

通过桌面详情面板移除全局 MCP 条目。使用 npx -y @open-pets/cli@latest configure --agent cursor --remove-rules 移除项目规则。两种操作在改动托管内容前都会创建备份。

下一步计划

Cursor 的 MCP 与项目规则已完成。下一阶段是 Cursor hooks，用于环境感知的生命周期反应，类似 Claude hooks 或 OpenCode 插件事件映射。我们有意暂未写入 hooks——它们需要一次验证才能落地，验证内容包括 hook 配置路径、负载结构、stdout 行为、超时、fail-open 与 fail-closed 语义，以及在本地、WSL、远程和 devcontainer 中的执行位置。

Alvin 制作