Trail

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 で作成してください。無料プランでは、3 つのプロジェクトと 3 人まで利用できます。

特定のエージェントに限定されません。 これは stdio 経由で動作し、現在使われている 3 つのプロトコルバージョンに対応する、シンプルな 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 は展開しないためです。

エージェントが利用できる機能

トラッカー - 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、update_reminder、delete_reminder。期日を見落としてはならないタスクです。期日になると、エージェントが自ら完了するか、スケジュールを変更します。

添付ファイル - add_attachment、get_attachment。項目に関連付けられたファイルです。

書き込み先のプロジェクト

Trail では複数のプロジェクトを管理できます。コネクターは、開いているフォルダーをプロジェクトとして使用します。フォルダー名、隣にある .trail ファイルの内容、または TRAIL_PROJECT 変数をもとに判断します。そのため、エージェントは指示されなくても適切なプロジェクトに書き込み、2 つのリポジトリの内容が混ざることもありません。別のプロジェクトにアクセスする場合は、エージェントがツールで project を明示的に指定します。

セッションフック（Claude Code、Gemini CLI、Antigravity）

ログイン時に一度、またはコネクターの初回実行時にインストールされます。これは、ブラウザーからログインせず、登録時にトークンを貼り付けた場合も対象です。トラッカーのあるプロジェクトでセッションを開始すると、最初のメッセージから未完了の項目とプロジェクトのメモリがコンテキストに含まれます。エージェントは誰かが尋ねるのを覚えている必要なく、最初から状況を把握できます。設計上、失敗しても通知しません。ログインしていない場合やネットワークに接続できない場合、フックは何もせず静かに終了します。

各ツールはそれぞれ独自の場所を参照するため、コネクターは実際に読み込まれる場所に設定を書き込みます。

• 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）で実機検証したところ、この設定フォルダー内にある3つの項目のうち、認識されるのはツールの登録だけでした。起動時の要約フックは実行されず、ドキュメントの指示どおりの場所に配置したプラグインフォルダーも読み込まれません。そのため Antigravity では、エージェントはツールとサーバーの作業ルールを利用できますが、要約を受け取る代わりに、最初のターンでプロジェクトの要約を自ら取得します。プラグインのパスは実装・テスト済みで、状況が変わるのを待っています。

usetrail status を実行すると、このマシンで見つかったツールごとに有効かどうかがわかります。設定ファイルを探し回る必要はありません。

無理に設定を変更することはありません。マシンにないツール用の設定は作成されず、hooks install もインストールされていないプログラムの設定を勝手に作成しません。hooks uninstall で削除した場合、自動的に再追加されることはありません。次のコマンドで再追加できます。

npx -y usetrail@latest hooks install

フック機構のないクライアントにも対応しています。サーバーの指示により、エージェントは作業を始める前に自ら要約を取得します。

自分専用の 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 を指定します。指定しない場合はシステムの言語を使い、システムの言語が設定されていなければ英語を使います。エージェントが読む内容は変わりません。

以前の名前（TETHER_*）も期限なく引き続き使えます。以前の製品名は Tether でしたが、すでに設定済みの項目を変更する必要はありません。

更新

@latest は飾りではありません。 npx -y usetrail@latest として登録すると、エージェントがセッションを開始するたびに、コネクターは公開済みの最新バージョンを取得します。そのため、新しいリリースは何もしなくても適用されます。npx usetrail とだけ登録すると、npm は初回にキャッシュしたコピーを再利用し、そのマシンではいつまでも同じバージョンが使われます。@latest を指定してください。

@latest にかかるコストは、セッション開始時に約1秒とネットワークリクエスト1回です。実際にはどちらも問題になりません。コネクターは、いずれにせよネットワーク経由で Trail と通信するためです。

クローンしたインストールの更新方法は異なります。起動時にバックグラウンドで静かに早送りプルを行い、頻度は最大でも6時間に1回です。実行中のセッションでは読み込み時のバージョンが維持され、次のセッションから更新後のバージョンが使われます。ネットワークに接続できない場合やローカルで競合が発生した場合は、何も起こらず、通知もされません。

古いバージョンのままですか？ npx -y usetrail@latest doctor を実行すると、インストールを見つけてバージョンを報告し、問題を解消します。

必要条件

Node 18 以降。

ライセンス

MIT。このパッケージはクライアント、つまりお使いのマシンで実行するコネクターです。自由に使用、フォーク、改変してください。このパッケージが接続する Trail サービスは、別途ホストされている製品です。