Trail

usetrail

适用于 Trail 的 MCP 服务——它为你的编码 Agent 提供团队的任务跟踪器和项目持久记忆，并限定在你当前打开的文件夹范围内。

你的 Agent 不再盲目工作。它会读取当前打开的内容，记录完成的工作，并记下那些吃过亏才学到的经验——都写入团队查看的同一块看板，而不是只有本次会话能看到的临时文件。

这个软件包是客户端。它通过 REST API 与你的 Trail 账号通信；这里没有数据库。依赖项包括 @modelcontextprotocol/sdk、zod 和内置的 fetch。

快速开始

# 1. connect this machine to your Trail account (opens your browser; no token to copy)
npx -y usetrail@latest login

# 2. register it with your agent - this example is Claude Code
claude mcp add trail -s user -- npx -y usetrail@latest

还没有账号？请在 usetrail.dev 创建一个——免费方案支持三个项目和三位成员。

不绑定特定 Agent。 这是一个通过 stdio 通信的普通 MCP 服务，支持目前使用的三个协议版本。任何兼容 MCP 的客户端都可以运行它；不同之处仅在于注册命令，每个客户端都有自己的说明文档。

更喜欢本地检出？ 也可以克隆仓库，连接器会自行保持更新（参见更新）：

git clone https://github.com/arsprengel/trail-mcp.git ~/.trail-mcp
npm --prefix ~/.trail-mcp install --omit=dev
node ~/.trail-mcp/bin.js login
claude mcp add trail -s user -- node ~/.trail-mcp/bin.js

在 Windows 上，请填写实际路径，而不要使用 ~：注册时会原样保存参数，而 Node 不会展开它。

Agent 能获得什么

任务跟踪器——list_items、get_item、add_item、update_item、move_item、get_next、delete_item。团队看板上的真实任务，包含类型、状态、优先级、负责人和历史记录。Agent 接手的工作会显示为进行中，完成后会关闭，因此不必再由某个人讲述工作进展。

项目记忆——list_memory、get_memory、add_memory、update_memory、review_memory。项目的持久知识：有陷阱的部署方式、不应反复争论的决策、任何 README 都没写的命令。项目中的所有成员，无论是人还是 Agent，都可以共享。新会话会先读取这些内容，再开始行动，避免重复探索。

提醒——add_reminder、list_reminders、update_reminder、delete_reminder。带日期且绝不能悄悄错过的事项——日期到来后，Agent 会自行关闭或重新安排。

附件——add_attachment、get_attachment。属于某项任务的文件。

它会写入哪个项目

Trail 可以管理多个项目。连接器会使用你当前打开的文件夹作为项目依据——可以是文件夹名称、旁边 .trail 文件中的设置，或 TRAIL_PROJECT 变量。因此，Agent 无需额外说明就能写入正确的项目，两个代码仓库之间也不会相互混淆。如需访问其他项目，Agent 可以在工具调用中明确传入 project。

会话钩子（Claude Code、Gemini CLI、Antigravity）

在你登录时安装一次；对于通过连接器首次运行的情况也会安装，这涵盖了在注册时粘贴令牌，而不是通过浏览器登录的用户。每当在配置了跟踪器的项目中启动会话时，待处理事项和项目记忆都会从第一条消息起纳入上下文——Agent 一开始就了解情况，而不必指望有人记得去询问。采用故障静默设计：未登录或没有网络时，钩子会保持静默。

每种工具都有自己的配置位置，因此连接器会写入该工具实际读取的位置：

• Claude Code - 在 ~/.claude/settings.json 中配置会话启动钩子。
• Gemini CLI - 在 ~/.gemini/settings.json 中配置会话启动钩子。
• Antigravity - 工具会注册到它实际读取的文件 ~/.gemini/config/mcp_config.json 中：gemini mcp add 无法在 Antigravity 中连接 Trail，因为该命令会改写 ~/.gemini/settings.json。经 Antigravity 2.11（Windows）实测，在该配置文件夹中的三项内容里，只有工具注册会生效——启动摘要钩子不会运行，而放在其文档所述位置的插件文件夹也不会被读取。因此，在 Antigravity 中，Agent 可以使用这些工具和服务端的工作规则，并会在第一轮对话时自行获取项目摘要，而不是接收摘要。插件路径已构建并通过测试，目前由开关控制，等待情况改变。

usetrail status 会针对这台机器上检测到的每种工具，告知你其是否已启用——你无需再翻找设置文件。

它绝不会与你争抢控制权。机器上没有安装的工具不会创建任何配置；hooks install 也不会为你没有安装的程序伪造配置。如果你用 hooks uninstall 移除了它，它不会自行恢复——请用以下命令重新添加：

npx -y usetrail@latest hooks install

没有钩子机制的客户端也能正常使用：服务端自身的指令会告诉 Agent 在采取行动前自行获取摘要。

你自己的 Trail

设置一次服务器地址，之后就会一直使用该地址：

TRAIL_API_URL=https://your-trail npx -y usetrail@latest login

未设置该变量时，login 会连接托管服务。

命令

npx -y usetrail@latest            # start the MCP server over stdio - what your agent runs
npx -y usetrail@latest login      # connect this machine (browser confirmation, no token copying)
npx -y usetrail@latest status     # server address, current project, whether a token is present
npx -y usetrail@latest logout     # delete the saved token
npx -y usetrail@latest doctor     # find the install on this machine and unstick auto-updates

令牌存储在 ~/.config/trail/token.json 中（模式为 600）。你可以随时在应用的“AI token”面板中撤销它。

配置

变量	作用
TRAIL_API_URL	你自己的 Trail 地址。首次登录后保存。默认为托管服务。
TRAIL_PROJECT	强制指定项目名称（默认为当前打开的文件夹）。
TRAIL_API_TOKEN	直接提供令牌，跳过浏览器登录。适用于 CI。
TRAIL_LANG	连接器在屏幕上显示内容的语言：pt 或 en。未设置时，使用系统语言；如果系统未指定语言，则使用英语。不会改变 Agent 读取的内容。

旧名称（TETHER_*）仍可使用，且没有截止期限——该产品以前名为 Tether，任何人已经配置好的内容都无需更改。

更新

@latest 不是装饰。 注册为 npx -y usetrail@latest 后，连接器会在 Agent 每次启动会话时解析已发布的版本，因此新版本发布后会自动送达，无需任何人采取操作。若注册为裸命令 npx usetrail，npm 会重复使用首次缓存的副本——该机器将永远停留在那个版本。请使用 @latest。

使用 @latest 的代价是在会话启动时多花大约一秒，并进行一次网络调用。实际上这两点都无关紧要：连接器反正也要通过网络与 Trail 通信。

克隆安装会以不同方式自行更新：启动时，它会在后台静默执行快速前进拉取，间隔最长为六小时。当前运行的会话会继续使用已加载的版本；下次启动的会话则会使用更新后的版本。没有网络或遇到本地冲突时，则不会发生任何操作，且过程保持静默。

如果仍停留在旧版本？npx -y usetrail@latest doctor 会查找安装、报告版本并解除故障。

要求

Node 18 或更高版本。

许可证

MIT。此软件包是客户端，也就是你在自己的机器上运行的连接器。你可以使用、派生或改造它。它所连接的 Trail 服务是一个独立托管的产品。