usetrail

用于 Trail 的 MCP 服务器——它为你的编程代理提供你团队的追踪器和项目的持久记忆，范围限定在你打开的文件夹。

你的代理不再盲目工作。它读取打开的内容，写入它所做的操作，并记录它通过艰难方式学到的经验——就在你的团队所看的同一块看板上，而不是在只有那个会话能看到的临时文件中。

这个包是客户端。它通过 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 创建一个——免费计划涵盖一个项目和三个人。

不绑定单一代理。 这是一个基于 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 不会展开它。

Related MCP server: Context Sync MCP

你的代理获得什么

追踪器 - list_items、get_item、add_item、update_item、move_item、get_next、delete_item。你团队看板上的真实条目，包含类型、状态、优先级、负责人和历史记录。代理接手的工作会显示为进行中，完成后关闭，因此看板不需要有人再去复述。

项目记忆 - list_memory、get_memory、add_memory、update_memory、review_memory。项目的持久知识：包含陷阱的部署、不应被重新争论的决策、任何 README 中都没有的命令。项目中的每个人（无论是人还是代理）共享这些记忆。新的会话在行动之前会先读取它，而不是重新发现。

提醒 - add_reminder、list_reminders。带有日期、不能被悄然错过的事项。

附件 - add_attachment、get_attachment。属于某个条目的文件。

它写入哪个项目

Trail 包含许多项目。连接器使用你打开的文件夹作为项目——即文件夹名称，或旁边 .trail 文件中的内容，或 TRAIL_PROJECT 变量。这样代理无需被告知就能写入正确的项目，两个仓库之间也永远不会相互干扰。要跨项目操作时，代理会在工具上显式传递 project。

会话钩子（Claude Code）

npx -y usetrail@latest hooks install

在 ~/.claude/settings.json 中注册一个开场钩子（带备份，且不会重复）：每个在带有追踪器的项目中启动的会话，都会从第一条消息起在上下文中获得打开的条目和项目记忆——代理一开始就了解情况，而不是依赖有人记得去询问。设计上静默失败：没有登录或没有网络时，钩子保持安静。hooks uninstall 可撤销它。

没有钩子机制的客户端也同样适用：服务器自身的指令会告诉代理在行动之前自行获取摘要。

你自己的 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" 面板里撤销它。

配置

旧名称（TETHER_*）仍然有效，没有截止日期——该产品以前叫 Tether，任何人已经配置好的内容都不需要更改。

更新

@latest 不是装饰。 以 npx -y usetrail@latest 注册后，连接器会在你的代理每次启动会话时解析已发布的版本，因此新版本无需任何人操作就能到达你手中。以裸 npx usetrail 注册时，npm 会复用第一次缓存的副本——那台机器将永远停留在那个版本上。请使用 @latest。

@latest 的代价是会话启动时大约一秒钟的时间，以及一次网络调用。这两者在实践中都无关紧要：连接器本来就要通过网络与 Trail 通信。

克隆安装的更新方式不同：启动时它会在后台静默执行一次快进拉取，最多每六小时一次。正在运行的会话保持其加载的版本；下一个会话启动时就是更新后的版本。没有网络或存在本地冲突时，什么都不会发生，静默地。

卡在旧版本上？npx -y usetrail@latest doctor 会找到安装位置，报告版本并解除卡住的状态。

要求

Node 18 或更高版本。

许可证

MIT。这个包是客户端——你在自己机器上运行的连接器。可以使用它、分叉它、改造它。它所通信的 Trail 服务是一个独立的托管产品。