OpenPets 标志OpenPets
← 返回集成

集成指南

已支持

通用 MCP 客户端 + OpenPets

通过已发布的 OpenPets MCP server、安全工具、宠物路由和本地桌面 IPC，将任何支持 stdio MCP 的助手连接到 OpenPets。

此集成的功能

通用 MCP 集成适用于任何能够启动 stdio MCP server 的助手或编辑器。无需使用专用的 OpenPets 设置流程，只需将 OpenPets MCP 命令添加到客户端的 MCP 配置中即可。

工具用途安全模型
openpets_status检查 OpenPets 是否可达及当前目标宠物。只读的设置与健康检查。
openpets_react在不显示文本的情况下更改宠物反应。用于静默状态，如思考、测试、等待、成功或错误。
openpets_say显示一条简短的可见对话气泡。拒绝过长、多行、类代码、含 URL/路径或看起来像密钥的消息。

运行时在本地进行。你的 MCP 客户端启动 @open-pets/mcp，MCP server 使用 @open-pets/client，客户端通过本地 IPC 与正在运行的 OpenPets 桌面应用通信。

使用要求

  • OpenPets 桌面应用必须正在运行，宠物更新才能生效。
  • 你的助手或编辑器必须支持 stdio MCP server。
  • 如果使用已发布的 npx 命令，必须有可用的 Node.js 和 npm。

通用 MCP 配置

MCP 客户端使用不同的根键，但命令和参数才是关键。请根据客户端的 MCP 格式调整包装结构。

通用 stdio MCP serverjson
{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@open-pets/mcp@latest"]
    }
  }
}

某些客户端使用 servers、mcp 或 context_servers 作为根键，而非 mcpServers。除非你的客户端需要不同的可执行文件格式，否则命令保持为 npx，参数保持为 ["-y", "@open-pets/mcp@latest"]。

宠物路由

默认情况下，MCP server 指向桌面应用的默认宠物。当你希望此 MCP 进程请求特定已安装宠物时，添加 --pet <pet-id>。

指向特定宠物json
{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@open-pets/mcp@latest", "--pet", "fixer"]
    }
  }
}
  • 如果请求的宠物可用，OpenPets 会将此 MCP 会话路由到该宠物。
  • 如果请求的宠物缺失或不可用，OpenPets 会安全回退，而不会中断助手。
  • 显式宠物路由使用短租约，代理宠物可以自动清理。

推荐的助手指令

MCP 为你的助手提供工具，而指令则教会它如何使用这些工具，同时避免将私有上下文泄露到可见的桌面气泡中。在你的 MCP 客户端存储助手指令的位置添加一个简短的规则块。

OpenPets 助手引导md
OpenPets MCP tools may be available.

  • Use openpets_status before using OpenPets or when debugging availability.
  • Use openpets_react for silent state changes like thinking, editing, testing, waiting, success, or error.
  • Use openpets_say only for short visible status messages.
  • Never send code, logs, command output, file paths, URLs, secrets, tokens, user prompts, or private data to openpets_say.
  • Do not spam every internal step.

测试连接

MCP 客户端加载 server 后，让它主动使用 OpenPets：

测试提示词text
Check OpenPets status. If it is available, send a short "connected" message and a waving reaction.

如果你的客户端在调试面板中显示 MCP 工具调用，你应该能看到 openpets_status、openpets_react 和 openpets_say。

安全性与行为

保护机制行为说明
简短语音openpets_say 接受最多 140 个字符的消息。
单行限制多行消息会被拒绝。
禁止代码或日志类代码文本、命令输出、URL、文件路径和看起来像密钥的文本会被拒绝。
尽力可用性如果桌面应用已关闭，工具会返回 MCP 错误，而不是导致你的助手崩溃。

故障排查

MCP 工具未出现

  • 更改配置后重启或重新加载你的 MCP 客户端。
  • 确认客户端支持 stdio MCP server。
  • 在终端运行 npx -y @open-pets/mcp@latest --help，确认 npm 能解析该包。
  • 检查你的配置是否使用了客户端对应的正确根键。

工具出现但 OpenPets 不可用

  • 先打开 OpenPets 桌面应用。
  • 让助手调用 openpets_status。
  • 如果使用了 --pet，请通过 OpenPets 桌面应用或 OpenPets CLI 确认该宠物 ID 已安装。

我应该使用通用 MCP 还是专用集成？

使用 Claude Code 或 OpenCode 时，请使用对应的专用页面，它们包含专属设置流程和托管指令。当你的工具支持 MCP 但 OpenPets 尚未为其提供专用设置页面时，使用通用 MCP。

Alvin 制作