Heuresis

@heuresis/mcp

一个 Model Context Protocol (MCP) 服务，可将 Heuresis 工作区提供给任何支持 MCP 的客户端（Claude Desktop、Claude Code、Cursor、Windsurf、自定义 Agent）。该服务会登录用户的 Heuresis 账户，连接到与 Web 应用相同的 Supabase 项目，并遵循相同的 RLS。Web 应用和 MCP 是同一个云端工作区的两个前端。

当前版本：1.0.0-rc.13。

安装

npm install -g @heuresis/mcp
# or on demand without installing:
npx -y @heuresis/mcp

软件包名称与命令名称。 npm 软件包名为 @heuresis/mcp，安装的命令名为 heuresis-mcp。直接运行 npx -y @heuresis/mcp（不带子命令）可以正常启动 MCP 服务，但 npx @heuresis/mcp login 可能会因找不到 heuresis-mcp 而失败，因为 npx 会根据去掉作用域后的软件包名称（mcp）推导命令名称，两者不匹配。若要在所有 npm/OS 上可靠地运行子命令，请使用 -p 显式指定二进制文件：

npx -y -p @heuresis/mcp heuresis-mcp login

快速入门

1. 将此设备关联到你的 Heuresis 账户

npx -y -p @heuresis/mcp heuresis-mcp login

CLI 会显示设备代码以及一个单击即可打开的 URL，格式为 https://heuresis.app/device?code=XXXX-XXXX。在浏览器中打开该链接，如果尚未登录，请先登录，然后确认设备。CLI 会在后台轮询，并在你确认后立即将凭据写入 ~/.heuresis/credentials.json（在 POSIX 系统上执行 chmod 600）。之后运行 MCP 时不会显示提示。

登录流程会调用三个 Supabase Edge Functions： mcp-device-init、mcp-device-grant 和 mcp-device-poll。

若要取消关联设备：运行 npx -y -p @heuresis/mcp heuresis-mcp logout，或在 Web 应用中打开“设置”▸“已连接的设备”，远程撤销关联。

运行 npx -y -p @heuresis/mcp heuresis-mcp whoami，可确认设备当前关联的账户。

2. 将 MCP 客户端指向此服务

Claude Desktop。 在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，或在 Windows 上编辑 %APPDATA%/Claude/claude_desktop_config.json：

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

Claude Code / Cursor / Windsurf。 在工作区根目录中放置一个 .mcp.json：

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

重启客户端。Heuresis 工具会显示在工具菜单中。

3. CLI 子命令

npx -y -p @heuresis/mcp heuresis-mcp whoami   # show the linked account + device
npx -y -p @heuresis/mcp heuresis-mcp logout   # delete the credentials file
npx -y -p @heuresis/mcp heuresis-mcp --help   # all options
npx -y @heuresis/mcp --no-realtime            # boot the server with live sync off (persisted)
npx -y @heuresis/mcp --realtime               # re-enable live sync

无头模式（CI、云端 Agent、临时容器）

设备配对会将刷新令牌写入磁盘。这在个人设备上很好用，但无法在临时/短暂环境中持续生效（CI 运行器、云端 Agent 容器、“Claude Code on the web”）：每次运行后文件系统都会被清除，而且 Supabase 刷新令牌在轮换机制下只能使用一次，因此写入配置的令牌会在第一个会话后失效。

在这些环境中，跳过配对，让服务在每次启动时使用账户邮箱和密码重新登录（密码使用后不会被消耗，因此无需重新配对即可永久使用）。设置以下三个环境变量：

[email protected]          # your Heuresis account email
HEURESIS_PASSWORD=your-account-password # secret — store it in a secrets manager
HEURESIS_ANON_KEY=sb_publishable_...    # project anon/publishable key (public, not a secret)
# optional: HEURESIS_SUPABASE_URL=...   # defaults to the production project

设置了 HEURESIS_EMAIL 和 HEURESIS_PASSWORD 后，它们的优先级高于任何 credentials.json，MCP 服务会在每次启动时进行身份验证，无需关联设备。要求：

• 必须为 Supabase 项目启用邮箱和密码登录，并且账户已设置密码（仅支持无密码登录/魔法链接的账户需先添加密码）。
• 将 HEURESIS_PASSWORD 视为机密。如果你的环境只能公开用户可见的环境变量，建议使用专用账户。

实时同步

MCP 以云端模式启动时，会通过 Supabase Realtime 订阅工作区，并在 nodes、edges、projects 或 ideas 行发生变化时通知客户端。在 Web 应用中所做的编辑会自动显示在 Agent 的视图中，无需手动刷新；通过一个 MCP 客户端进行的写入也会以相同方式同步到其他已连接的客户端。传入 --no-realtime 可禁用订阅（适用于通知过于频繁或客户端会记录每条通知的情况）。此偏好会保存到 ~/.heuresis/config.json，因此只需传入一次该标记。

工具

共有 34 个工具：31 个用于云工作区的数据工具，以及 3 个用于驱动 Web 应用所用构思操作器的操作器工具。

读取（10 个）。 get_workspace_summary、list_projects、 get_project_graph、list_concepts、list_edges、get_subtree、 get_concept、search_concepts、find_concepts、 list_recent_decisions。大多数 Agent 会话从 get_workspace_summary 或 list_projects 开始。

写入（21 个）。 概念：add_concept、update_concept、 bulk_add_concepts、set_parent、validate_concept、set_standing、 archive_concept、unarchive_concept、star_concept、 remove_concept。边：link_concepts、add_kref。想法： create_idea、rename_idea、recolor_idea、set_idea_members、 add_to_idea、delete_idea。项目：create_project、 update_project、delete_project。每次写入都会在 public.provenance 中添加一行记录，并将 origin='mcp'，这样 Web 应用的会话日志 就能显示是哪个界面进行了更改。

操作器运行（3 个）。 run_operator（使用 Branch / Matrix / ASIT / TRIZ / Combine / Free / Contradiction 生成候选项）、run_operator_and_commit（相同功能，另加一次往返即可提交结果），以及 expand_concept（递归 Branch，深度 × 广度上限为 60）。

工具输入格式与 Web 应用中 src/agent/tools.ts 的对应项一致，因此同时使用两个界面的 Agent 会看到 统一的契约。

后续计划：find_in_files（浏览器内嵌入搜索）已在 Web 应用中提供，但 MCP 尚未支持。

传统快照模式（已弃用）

在用户迁移到云端身份验证期间，原有的只读快照读取器仍可作为后备方案使用。如果没有 ~/.heuresis/credentials.json 且设置了 HEURESIS_SNAPSHOT 环境变量，服务就会从磁盘读取 JSON 导出文件，并提供原有的只读工具集 （get_workspace_summary、list_projects、search_concepts、 get_concept、get_subtree、get_project_graph、 list_recent_decisions）。

export HEURESIS_SNAPSHOT="/absolute/path/to/your-export.json"
npx @heuresis/mcp

此路径已弃用，并将在后续版本中移除。保留此路径是为了让现有配置在迁移到云端身份验证期间继续正常工作。

许可证

AGPL-3.0-or-later。