Saga

saga-mcp

コーディングエージェントはセッションをまたぐと計画を忘れてしまいます。翌日戻ってくると、合意した5つの項目のうち何が完了し、何が何に阻まれているのか、なぜ2つ目のアプローチを却下したのかも分かりません。計画がコンテキストウィンドウにあったか、誰も更新しないTODO.mdに書かれていたからです。

saga-mcpは代わりに、エージェントに本格的なトラッカーを提供します。プロジェクト内のSQLiteファイルに、プロジェクト、エピック、タスク、サブタスク、依存関係、コメント、メモ、決定事項を保存し、41個のMCPツールとして公開します。エージェントは作業中にデータを書き込み、戻ってきたときに読み取ります。アカウントも外部サービスもネットワーク呼び出しも不要です。データベースは自分で所有するファイルです。

---

インストール

saga-mcpをMCPクライアントに追加します。同じ設定ブロックがClaude Code（プロジェクト内の.mcp.json）、Claude Desktop（claude_desktop_config.json）、その他のMCPクライアントで使えます。

{
  "mcpServers": {
    "saga": {
      "command": "npx",
      "args": ["-y", "saga-mcp"],
      "env": { "DB_PATH": "/absolute/path/to/your/project/.tracker.db" }
    }
  }
}

クライアントを再起動します。必須の設定はDB_PATHだけです。初回使用時にファイルとスキーマが作成されます。グローバルインストールを使う場合は、npm install -g saga-mcpを実行し、npxの代わりにコマンドとしてsaga-mcpを指定します。

Linux、macOS、Windowsで、Node 20、22、24を使ってテスト済みです。

設定

変数	必須	説明
DB_PATH	はい	.tracker.db SQLiteファイルへのパスです。初回使用時に作成されます。
SAGA_PROJECT	いいえ	IDまたは名前を指定して、すべてのツールの対象を1つのプロジェクトに限定します。複数のリポジトリで1つのデータベースを共有する場合は、リポジトリごとに設定します。
SAGA_DESCRIPTION_LOCK	いいえ	on_progressは、タスクの作業が始まった時点でその説明をロックします。デフォルトでは無効です。エージェントの作業方針を維持する方法を参照してください。
SAGA_TOOLS	いいえ	full（デフォルト）は41個すべてのツールを一覧表示します。coreは通常のトラッキングセッションで必要な13個のみを一覧表示し、セッションあたり約4,300トークンを節約します。トークンコストを参照してください。

APIキー、アカウント、外部サービスは不要です。

---

初めてのセッション

あなた：「eコマースAPIのトラッキングを設定して、認証の計画を立ててください。」

tracker_init({ project_name: "E-Commerce API" })
epic_create({ project_id: 1, name: "Authentication", priority: "high" })
task_create({ epic_id: 1, title: "Design auth schema", priority: "critical" })
task_create({ epic_id: 1, title: "Implement JWT auth", depends_on: [1] })
task_create({ epic_id: 1, title: "Add OAuth2 Google login", depends_on: [2] })

タスク2と3は、依存先が完了していないためブロック中になります。タスク1を完了すると、タスク2のブロックが自動的に解除されます。このやり取り全体を、実際にsaga-mcpで実行した様子です。

次のセッション、あなた：「どこまで進みましたか？」

tracker_next({})
  -> Work on #1 'Design auth schema' — critical priority, in the active epic
     'Authentication'. 2 other task(s) are blocked.

理由付きの推奨が1つ返されます。全体像を確認するには、tracker_dashboard({})を使うと、統計、エピック、ブロック中および期限超過のタスク、最近のアクティビティ、メモが要約とともに返されます。

質問する代わりに画面で確認したい場合は、saga-webを使うと、同じデータベースをブラウザーで表示できます。

---

得られるもの

• 次にやること — その理由とともに、ダッシュボードの3分の1のコストで1つの推奨事項を提示します
• 実際の順序付け — 自動でブロックおよび解除される依存関係、ツールが尊重する手動の順序、デッドロックさせるのではなく拒否される循環依存
• エージェントの逸脱を防ぐ仕組み — ロック可能な説明と、報告するだけでなく書き込み時に適用される前提条件
• Web UI — saga-web は同じデータベースをブラウザーで読み書きできます
• テンプレート — {variable} による置換に対応した再利用可能なタスクセットを、その場で編集できます
• アーカイブとソフト削除 — 完了した作業を、元に戻せる形で、料金のかかるコンテキストから取り除きます
• 柔軟な入力 — 小規模なモデルが配列を JSON 文字列として送信しても、バッチ全体が1つのレコードにひそかにまとめられることはありません
• 1つのファイルで複数のプロジェクト — リポジトリごとのデータベース、または1つの共有ファイル
• 完全な監査証跡 — すべての変更を変更前後の値とともに記録し、エージェントが削除したものは復元できます
• すべてに MCP の安全性アノテーションが付いた 41個のツールと、コンテキスト料金を抑えたい場合に使える段階的なインターフェース

---

次に何をするかを尋ねる

tracker_dashboard はすべての情報をエージェントに渡し、あとはエージェントの推論に任せます。tracker_next は次の質問に答えます。

tracker_next()
  -> Work on #12 'Write the adapter' — already in progress, high priority, in the
     active epic 'Provider swap'. Next step: implement. Also overdue: #18 'Renew cert'.
     3 other task(s) are blocked.

理由とともに1つの推奨事項、その中で次に完了する未完了のサブタスク、いくつかの代替案、期限超過またはブロック中の項目を提示します。ダッシュボードの約3分の1のサイズです。

知っておくべき順序付けのルールは、新しく始めるより、続行することを優先するということです。進行中のタスクは、期限超過や優先度の高い未着手のタスクよりも優先されます。進行中の作業を放棄すると、未完了の作業が2つになるからです。期限超過の作業は、代わりにサマリーに記載されます。ブロック中のタスクは推奨されず、アーカイブされたエピックと削除されたタスクはスキップされます。また、選択されたタスク内で次に進むステップは、サブタスクの依存関係によって決まります。

実行可能な項目がない場合は、空の回答を返すのではなく、解除すべきブロックを示します。

Nothing is actionable: all 4 remaining task(s) are blocked.
Unblocking #7 'the keystone' would release 3 of them.

---

順序付けと依存関係

意図的に決めた順序は、推測より優先されます。 task_list は、誰かがエピックの順序を設定するまでは優先度順に並べ、それ以降は設定された順序に従います。

task_reorder({ epic_id: 2, ordered_ids: [8, 5, 6] })
task_list({ epic_id: 2 })                        // 8, 5, 6 — the plan, in order
task_list({ epic_id: 2, sort_by: "priority" })   // priority, if that is what you want

優先度は重要なものを推測するための妥当な手がかりですが、書き留められた順序は推測ではありません。計画を渡されたエージェントは、たまたまクリティカルとマークされたステップではなく、計画の最初から始めるべきです。

順序が設定されていないエピックは、これまでどおり優先度順に並ぶため、何も変わりません。また、明示的な sort_by は常に指定どおりに適用されます。

ordered_ids から省略された項目は、相対的な順序を保ったまま末尾に配置されます。sort_order は昇順で、値が小さいものほど先に並びます。順序を設定した後に作成されたタスクはその順序に含まれないため、先頭ではなく末尾に配置されます。Web UI では、エピック内のタスクをドラッグして順序を変更できます。

タスクの依存関係は、自動でブロックおよび解除されます。

task_update({ id: 9, depends_on: [8] })   // 9 becomes blocked while 8 is open

ブロック元のタスクの完了状態がどちらの方向に変化しても再評価されるため、完了済みのブロック元を再開すると依存先も再びブロックされ、最後の依存関係を解除するとブロックが解消されます。タスクもサブタスクも、循環依存はループを示して拒否されます。循環に含まれる項目は永久にブロックされるためです。Web UI では、ブロック中のタスクの上部に、待機中の対象を示すバナーが表示され、依存関係を追加または削除するためのピッカーも利用できます。

---

エージェントが脱線しないようにする

長いタスクでエージェントが間違った方向に進むのを防ぐ、2つのガード機能です。

説明のロック。 エージェントはコメントを追加するつもりで、進捗を記録するためにタスクの説明を書き換えてしまうことがあります。その結果、合意した仕様が失われてしまいます。説明をロックすると、task_update による変更が拒否されます。

task_lock_description({ id: 12 })
task_update({ id: 12, description: "..." })
  -> Task 12's description is locked and was not changed. Record progress with
     comment_add instead, or unlock it in the web UI if the description is genuinely wrong.

タスクのほかの項目は引き続き編集できます。目的は仕様を保護することであり、タスクを凍結することではありません。通常の task_update の副作用としてロックが解除されることはありません。意図的に task_lock_description を呼び出すか、ウェブ UI でロックを切り替える必要があり、どちらの場合もログに記録されます。

これは混乱を防ぐためのガードであり、敵対的な操作を防ぐものではありません。ロック解除を指示されたエージェントは、引き続きロックを解除できます。これにより、気付かないうちに上書きされる代わりに、可視化された取り消し可能な判断として扱われます。

計画内の各タスクを手動でロックするのは大変なので、SAGA_DESCRIPTION_LOCK=on_progress を設定すると自動で行われます。タスクの作業が始まると、つまりステータスが in_progress、review、done に変わるとき、またはそのステータスで作成されたときにロックされます。エージェントに許可される操作が変わるため、この設定は明示的に有効にしない限りオフです。

"env": { "DB_PATH": "…", "SAGA_DESCRIPTION_LOCK": "on_progress" }

この設定は、すべての書き込みを個別に再判定するのではなく、task_lock_description が設定するものと同じフラグを設定します。つまり、このフィールドは1つの仕組みで管理されます。タスクのロックを解除すれば、その後のステータス変更にかかわらず、ロックされないままです。blocked は「着手済み」ではありません。依存関係のために待機しているタスクはまだ作業されておらず、依存関係によってタスクが自動的にそのステータスに移動したり、そこから移動したりします。

サブタスクの順序と依存関係。 新しいサブタスクはすべて位置 0 に追加されるのではなく、順番に末尾へ追加されます。subtask_reorder を使うと1回の呼び出しで順序を設定でき（UI ではドラッグして並べ替えられます）、サブタスクを兄弟サブタスクの完了待ちにできます。

subtask_update({ id: 8, depends_on: [5, 6] })    // 8 waits for 5 and 6
subtask_update({ id: 4, blocks: [5, 6, 7, 8] })  // a bug that holds up the rest

読み取り結果には depends_on と blocked が含まれます。また、ブロックは書き込み時に強制されます。前提条件が満たされていないサブタスクの開始や完了は拒否され、チェックリストが未完了のタスクの完了も拒否されます。

subtask_update({ id: 8, status: "in_progress" })
  -> Subtask 8 cannot be started — it waits on #5 'write the parser' (todo).
     Finish those first, or pass force: true to override deliberately (the override is logged).

force: true を使うと先へ進めます。ブロッカーがもはや適用されないと人が判断した場合に使用します。subtask_update、task_update、task_batch_update で使用でき、すべての上書きは、スキップした項目を明記してアクティビティログに記録されます。ウェブ UI では確認を求めたうえで送信します。

重要なのは、エージェントがブロッカーを黙って無視することと、誰かがブロッカーの上書きを選択することの違いです。依存関係は1つのタスク内に限られます。別のタスクに属する項目を待つチェックリスト項目はタスクレベルの依存関係であり、task_update depends_on ですでにモデル化されています。

---

判断の経緯としてのコメント

comment_add({ task_id: 5, content: "Investigated root cause: CORS headers missing on preflight" })
comment_add({ task_id: 5, content: "Fixed by adding OPTIONS handler. Tested with curl." })
task_update({ id: 5, status: "done" })

コメントはセッションをまたいで保持されます。次回エージェントが task_get(5) を呼び出すと、スレッド全体が表示されます。

コメントが間違いだと分かった場合は、経緯を残したまま撤回できます。

comment_delete({ id: 12, reason: "Root cause was wrong — it was a proxy timeout", deleted_by: "pranab" })

行はデータベースとアクティビティログに残ります。comment_list と task_get では表示されませんが、comment_list({ task_id: 5, include_deleted: true }) を使うと理由とともに表示され、comment_restore({ id: 12 }) で元に戻せます。エージェントが削除したものは、すべて復元できます。

---

テンプレート

{variable} プレースホルダーを含む、再利用可能なタスクのセットです。適用時に値を入力します。

template_create({
  name: "feature_workflow",
  tasks: [
    { title: "Design {feature} API",       priority: "critical", estimated_hours: 2 },
    { title: "Implement {feature}",        priority: "high",     estimated_hours: 8 },
    { title: "Write tests for {feature}",  priority: "high",     estimated_hours: 4 }
  ]
})

template_apply({ template_id: 1, epic_id: 2, variables: { feature: "user auth" } })
// -> "Design user auth API", "Implement user auth", "Write tests for user auth"

テンプレートはその場で編集可能です。template_apply が参照するのは ID であるため、テンプレートを作り直すと、それを参照しているものが使えなくなります。

template_update({ id: 1, name: "Feature rollout" })                  // tasks untouched
template_update({ id: 1, tasks: [{ title: "Design {feature}" }] })   // name untouched
template_list({ include_tasks: true })                               // see what one creates

タスク定義は適用時ではなく、書き込み時に検証されます。そのため、不適切な優先度やタイトルの欠落は、すでに選択したエピックに対して後から失敗するのではなく、その場で拒否されます。テンプレートは、個々のプロジェクト内ではなく、データベース全体に保存されます。

Templates タブには、各テンプレートが作成するタスクと、入力が必要な {placeholders} が表示されます。

---

古い作業を片付ける

ほとんど完了した作業と、サブタスクにすべきタスクをエージェントが作成したままのエピック一覧は、呼び出しのたびにコストがかかるコンテキストです。

epic_archive({ id: 4 })            // the epic and its tasks drop out of listings
task_delete({ id: 12, reason: "should have been a subtask" })

アーカイブは意図的に cancelled ステータスとは異なります。cancelled は「これはやらないと決めた」という意味ですが、アーカイブしたいもののほとんどは 完了済み です。アーカイブしたエピックとそのタスクは、統計情報も一覧と同様に、epic_list、tracker_dashboard、task_list、tracker_search から表示されなくなり、include_archived を指定すると再び表示されます。Web UI では、Overview と Epics タブのどちらからでもエピックをアーカイブでき、アーカイブ済みのものはデフォルトで非表示になり、アーカイブ済み項目の表示切り替えを共有します。

何も黙って消えることはありません。ダッシュボードには除外した内容が表示されます。

Hidden: 2 archived epic(s) and 1 removed task(s) — pass include_archived to include them.

task_delete は、コメントのソフト削除と同じで、まだ todo のタスクに限られます。それより先に進んだタスクには、削除すると行き場を失うコメント、時間記録、アクティビティログがあるためです。また、他のタスクが依存しているタスクは削除を拒否し、永久にブロックされたままになることを防ぎます。行は保持され、task_restore で復元できます。また、tracker_export にはアーカイブ済みおよび削除済みの行も含まれます。項目を省いたバックアップはバックアップとは言えないためです。

---

柔軟な入力

小規模なモデルは、JSON を含む 文字列 として配列パラメーターを送ることがよくあります。すべての配列を受け取るツールがこれを受け入れるため、バッチ処理が誤って1件のレコードにまとまることはありません。

subtask_create({ task_id: 3, titles: '["Write it","Test it"]' })   // 2 subtasks
subtask_create({ task_id: 3, titles: "- Write it\n- Test it" })    // 2 subtasks
task_batch_update({ ids: "[4,5]", status: "done" })                // both tasks
task_create({ epic_id: 1, title: "x", tags: "billing, urgent" })   // 2 tags

意図が曖昧になる場合は、変換を行いません。タイトル 内のカンマはそのまま残ります。"Design the API, then implement it" は2つではなく1つのサブタスクです。一方、タグや ID のリスト内のカンマは区切り文字として扱われます。どちらもカンマを含められないためです。本当に使用できない入力は、ids.map is not a function のようなエラーを漏らすのではなく、受け取った内容と期待される内容を示すメッセージとともに拒否されます。

返される値は、入力した内容に対応します。tags、metadata、source_ref は JSON テキスト列に格納されますが、各レスポンスでは境界でデコードされるため、エージェントが使えないエスケープ済み文字列 "[\"billing\",\"urgent\"]" ではなく、タグのリストが ["billing", "urgent"] として読み取れます。

---

1つのデータベースで複数のプロジェクトを管理

saga-mcp は、リポジトリごとに .tracker.db を用意する方法（ポータブルで、無関係な作業を分離できます）でも、すべてのリポジトリが参照する共有データベースを使う方法でも動作します。

共有構成では、もう1つ設定が必要です。projects は最上位のテーブルなので、共有ファイルには複数のプロジェクトが格納されます。しかし、task_list、note_list、activity_log、tracker_search は、指定がない限りファイル全体を対象にします。リポジトリ B のエージェントからリポジトリ A のタスクが見えてしまいます。リポジトリごとに SAGA_PROJECT を設定すると、各エージェントには自身のプロジェクトだけが表示されます。

{
  "mcpServers": {
    "saga": {
      "command": "npx",
      "args": ["-y", "saga-mcp"],
      "env": {
        "DB_PATH": "/Users/you/saga/central.tracker.db",
        "SAGA_PROJECT": "Payments platform"
      }
    }
  }
}

SAGA_PROJECT にはプロジェクト ID またはプロジェクト名（大文字と小文字は区別されません）を指定でき、一致するものがない場合は、実際のプロジェクト一覧とともに起動時にエラーになります。スコープが適用される各ツールは、明示的な project_id 引数も受け付けます。この引数は環境変数より優先されます。

構成	設定する値	結果
リポジトリごとに1つのデータベース	DB_PATH	スコープの指定は不要です。1ファイルにつき1プロジェクトです
共有データベース、リポジトリごとのエージェント	DB_PATH + SAGA_PROJECT	各エージェントには自身のプロジェクトだけが表示されます
共有データベース、すべてを対象にする1つのエージェント	DB_PATH	ツールはすべてのプロジェクトを対象にします

SAGA_PROJECT も project_id も指定されていない場合、tracker_dashboard はファイル内の最初のプロジェクトを使用し、そのことを明示します。レスポンスには other_projects が含まれ、サマリーでは、対象のプロジェクトが推測されたことを説明します。別のリポジトリについて誤って報告することはありません。

いずれの構成でも Web UI には影響しません。プロジェクト切り替えメニューにはデータベース内のすべてのプロジェクトが表示され、各タブは選択したプロジェクトにスコープされます。

---

Web UI

上記はすべてエージェント向けです。saga-web を使うと、同じデータベースをブラウザーで操作できます。エージェントが書いた仕様を確認したり、1つのフィールドを手動で修正したりするほうが、もう1回プロンプトを送るより速い場合に便利です。

npx -p saga-mcp saga-web ./.tracker.db --open

MCP サーバーがすでに参照しているデータベースを使う場合も同様です。

saga-web --db ~/saga/central.tracker.db --port 8080

オプション	デフォルト	説明
--db <path>	$DB_PATH	開くデータベースです。位置引数でパスを指定することもできます。
--port <n>	4319 から最初に空いているポート	省略すると、saga-web は最初に空いているポートを使うため、プロジェクトごとにインスタンスを起動するだけで使えます。--port N は N にバインドし、そのポートが使用中なら失敗します。--port 0 を指定すると、OS がポートを選択します。また、SAGA_WEB_PORT も使用できます。
--host <addr>	127.0.0.1	バインドアドレスです。デフォルトではローカルからのみアクセスできます。
--read-only	オフ	編集コントロールをすべて取り除いた状態で UI を表示します。
--open	オフ	デフォルトのブラウザーで UI を開きます。

6 つのタブ：

• 概要 — 統計、エピックごとの進捗、ブロック中および期限超過のタスク
• ボード — 5 つのタスクステータスにわたるカンバンボード。カードをドラッグしてステータスを変更できます

• エピック — Epic → Task → Subtask の完全なツリーです。エージェントが書いたばかりの仕様をすばやく確認できます。ブロック中のタスクには、何待ちなのかを示す ⛔ が付き、完了したタスクには取り消し線が引かれます。タスクはドラッグして並べ替えられます。エピックも同様に表示され、進行中は太字、完了またはキャンセル後は取り消し線が引かれます。エピックのアーカイブはここからも概要からも行えます

• ノート — 決定事項、背景情報、ブロッカー
• テンプレート — 作成されるタスクと使用する {placeholders} を含むすべてのテンプレート。詳細やタスクリストの編集、エピックへの適用、削除ができます
• アクティビティ — 変更履歴のすべて

また、全体を通じて次の機能があります：

• タスクドロワー — あらゆるフィールドの編集、コメントの追加、コメントの削除または復元、説明のロック、サブタスクの並べ替え、サブタスク間の依存関係の設定ができます。各サブタスクのコントロールひとつで状態全体（todo / in progress / done、または blocked）を設定でき、端をドラッグしてドロワーのサイズを変更できます。Refresh/Edit/Close の行は、どれだけスクロールしても上部に固定されます。長いフォームでも Save ボタンが常に表示されます

• Markdown — 説明、コメント、ノートでは、見出し、表、リスト、コード、リンクが表示されます。エージェントが書いたコンテンツは Markdown のルールを適用する前にエスケープされるため、生の HTML がページに表示されることはありません。また、http/https/mailto のリンクのみが開かれます
• プロジェクト切り替え — データベース内のすべてのプロジェクトが表示されるため、1 つの中央の .tracker.db ですべてのリポジトリを管理できます。アクティビティを含むすべてのタブは、選択したプロジェクトにスコープされます
• 共有・更新可能な URL — 開いているプロジェクト、タブ、タスクがアドレスバーに表示されるため、ブラウザーを更新しても元の場所に戻り、戻る／進む操作でタスク間を移動できます。タスクドロワーの ⟳ ボタンを使うと、ページを再読み込みせずにタスクを読み直し、エージェントが書いたばかりの内容を確認できます

UI からの書き込みには、MCP ツールと同じハンドラーが使われます。そのため、手動で行った編集も同じように検証され、エージェントの変更と同じアクティビティログに記録されます。何かを修正した後にエージェントが tracker_dashboard を呼び出すと、修正内容とその経緯を確認できます。 いくつか意図的な制限があります。特に指定がない限り、127.0.0.1 にバインドされます。認証機能はありません（共有ネットワーク上に公開しないでください）。データベースも作成しないため、MCP サーバーがすでに使用しているデータベースを指定してください。別々の .tracker.db ファイルは、まだ1つのビューに集約されません。複数のプロジェクトを含む単一のデータベースには対応しています。

---

トークンコスト

ツール一覧は、作業を始める前に毎セッションでコンテキストを消費します。また、一覧のレスポンスも呼び出しのたびにコンテキストを消費します。どちらも意図的に小さく保たれています。

• レスポンスはコンパクトな JSON です。整形用のインデントは付けていません。測定では、レスポンスの20〜27％を占めていました
• task_list の行では、null と metadata を省略し、説明を120文字に切り詰めます（タスクの全文を取得するには task_get を呼び出します）。説明の長さに応じて、19〜39％小さくなります
• activity_log では、null の列と行 ID を省略します（これを受け取るツールはありません）。約27％小さくなります
• tracker_search はレコード全体ではなくプレビューを返します。約47％小さくなります。全文を取得するには、続けて task_get または note_list を呼び出します
• SAGA_TOOLS=core を設定すると、一覧に表示されるツール群は約7,200トークンから約2,900トークンになります

note_list は意図的にノートの内容をすべて保持します。プレビューではなく、取得用のツールです。

エージェントが作業の追跡のみを行う場合は SAGA_TOOLS=core を設定してください。テンプレート、インポート／エクスポート、セッション差分なども一覧で確認したい場合は、設定を解除したままにしてください。一覧に表示されないツールも、名前を指定すれば呼び出せます。core が縮小するのは案内される項目であり、存在する機能ではありません。

コアとなる13のツール：tracker_init、tracker_next、tracker_dashboard、project_list、epic_create、epic_list、task_create、task_list、task_get、task_update、subtask_create、note_save、comment_add。

すべてのツールの説明には、テストスイートでバイト数の上限が設けられています。そのため、機能を追加し続けて一覧を拡張することはできません。ツールを追加するには、別の箇所の文章を削るか、上限を増やす理由を示す必要があります。

---

ツールリファレンス

はじめに

ツール	説明	アノテーション
tracker_init	トラッカーを初期化し、最初のプロジェクトを作成します	readOnly: false、idempotent: true
tracker_next	次に取り組む作業と、その理由およびブロックされている作業を確認します	readOnly: true
tracker_dashboard	自然言語の概要を含む、プロジェクトの全体像を表示します	readOnly: true

プロジェクト

ツール	説明	アノテーション
project_create	新しいプロジェクトを作成します	readOnly: false
project_list	プロジェクトを完了状況の統計とともに一覧表示します	readOnly: true
project_update	プロジェクトを更新します（アーカイブするとソフト削除になります）	readOnly: false、idempotent: true

エピック

ツール	説明	アノテーション
epic_create	プロジェクト内にエピックを作成します	readOnly: false
epic_list	エピックをタスク数とともに一覧表示します	readOnly: true
epic_update	エピックを更新します	readOnly: false、idempotent: true
epic_archive	エピックをアーカイブ／アーカイブ解除します。エピックとそのタスクは一覧に表示されなくなります	readOnly: false、idempotent: true

タスク

ツール	説明	注釈
task_create	依存関係を任意で指定してタスクを作成します	readOnly: false
task_list	タスクを一覧表示／フィルタリングします。手動で並べ替えられている場合はその順序に従います	readOnly: true
task_get	サブタスク、メモ、コメント、依存関係を含むタスクを取得します	readOnly: true
task_update	タスクを更新します（自動でログを記録し、ブロック／ブロック解除します）	readOnly: false、idempotent: true
task_batch_update	複数のタスクを一括で更新します	readOnly: false、idempotent: true
task_reorder	エピックのタスクの順序を設定します	readOnly: false、idempotent: true
task_lock_description	エージェントが説明を書き換えられないよう、説明をロック／ロック解除します	readOnly: false、idempotent: true
task_delete	todo タスクを削除します（ソフト削除のため復元可能です）	readOnly: false、idempotent: true
task_restore	削除したタスクを復元します	readOnly: false、idempotent: true

サブタスク

ツール	説明	注釈
subtask_create	サブタスクを作成します（バッチ処理に対応）	readOnly: false
subtask_update	タイトル／ステータス／位置を更新します。depends_on と blocks で順序を設定します	readOnly: false、idempotent: true
subtask_reorder	1 回の呼び出しでタスクのサブタスクの順序を設定します	readOnly: false、idempotent: true
subtask_delete	サブタスクを削除します（バッチ処理に対応）	destructive: true、idempotent: true

コメント

ツール	説明	注釈
comment_add	タスクにコメントを追加します（スレッド形式のディスカッション）	readOnly: false
comment_list	タスクのコメントを一覧表示します（include_deleted を指定しない限り、削除済みのものは非表示です）	readOnly: true
comment_delete	コメントを削除します（ソフト削除のため、監査用に行が保持されます）	readOnly: false、idempotent: true
comment_restore	削除したコメントを復元します	readOnly: false、idempotent: true

テンプレート

ツール	説明	注釈
template_create	{variable} プレースホルダーを使用する再利用可能なタスクテンプレートを作成します	readOnly: false
template_list	テンプレートを一覧表示します。include_tasks を指定すると、それぞれのテンプレートが作成する内容を表示します	readOnly: true
template_update	テンプレートをその場で編集します（名前、説明、タスク）	readOnly: false、idempotent: true
template_apply	テンプレートを適用し、変数を置換してタスクを作成します	readOnly: false
template_delete	テンプレートを削除します	destructive: true、idempotent: true

メモ

ツール	説明	注釈
note_save	メモを作成または更新します（アップサート）	readOnly: false
note_list	フィルターを指定してメモを一覧表示します	readOnly: true
note_search	メモを全文検索します	readOnly: true
note_delete	メモを削除します	destructive: true、idempotent: true

検索、履歴、データ転送

ツール	説明	注釈
tracker_search	エンティティを横断して検索します（プロジェクト、エピック、タスク、メモ）	readOnly: true
activity_log	フィルターを指定して変更履歴を表示します	readOnly: true
tracker_session_diff	タイムスタンプ以降の変更を確認します（セッション開始時に呼び出してください）	readOnly: true
tracker_export	プロジェクト全体をネストされた JSON としてエクスポートします（依存関係とコメントを含みます）	readOnly: true
tracker_import	JSON からプロジェクトをインポートします（エクスポート形式に準拠）	readOnly: false

---

動作の仕組み

すべてのデータは単一の SQLite ファイルに保存されます。スキーマは初回使用時に作成され、既存のデータベースはアップグレード時にその場で移行されるため、実行が必要な移行手順はありません。

Project
  └── Epic (feature/workstream)
        └── Task (unit of work)
              ├── Subtask (checklist item)
              ├── Comment (discussion thread)
              └── Dependencies (blocked by other tasks)

メモの種類

メモを使うことで、散在する Markdown ファイルを置き換えられます。各メモには種類があります。

種類	用途
general	自由形式のメモ
decision	アーキテクチャ／設計上の決定
context	今後のセッション向けの会話のコンテキスト
meeting	会議メモ
technical	技術的な詳細、仕様
blocker	阻害要因と問題
progress	進捗状況の更新
release	リリースノート

アクティビティログ

作成、更新、削除のすべてが、変更前と変更後の値とともに記録されます。

{
  "summary": "Task 'Fix CORS issue' status: blocked -> done",
  "action": "status_changed",
  "entity_type": "task",
  "entity_id": 15,
  "field_name": "status",
  "old_value": "blocked",
  "new_value": "done",
  "created_at": "2026-02-21T18:30:00"
}

このログによって論理削除が安全になり、時間も自動で記録されます。作業時間は手動で入力するのではなく、このログから算出されます。

---

プライバシー

saga-mcp は完全にローカルで動作するオフラインツールです。ユーザーデータを収集せず、外部サーバーに何も送信せず、インストール後のインターネット接続も不要で、いかなる分析やテレメトリーも使用しません。

すべてのデータは、DB_PATH で指定されたローカルの SQLite ファイルにのみ保存されます。saga-mcp をアンインストールし、.tracker.db ファイルを削除すれば、すべての痕跡が消去されます。

---

開発

git clone https://github.com/spranab/saga-mcp.git
cd saga-mcp
npm install
npm run build
DB_PATH=./test.db npm start

# the web UI against the same database
node dist/web/index.js ./test.db --open

npm test     # 359 unit and integration tests, no network
npm run e2e  # release gate: packs a tarball, installs it, drives the real binaries

npm test はビルド済みの出力を対象に実行されます。リリース前に重要なゲートとなるのは npm run e2e です。実際に公開される tarball を作成し、別の場所にインストールして、実際の stdio 経由で両方のバイナリを実行します。古いデータベースからのアップグレードを含む、106 件のチェックを行います。

リリース

npm への公開は取り消せません。バージョン番号は二度と使えないため、公開は最後のステップであり、タグのプッシュではなく GitHub リリースの公開によって実行されます。

# 1. bump the version in package.json, manifest.json and server.json, then merge
# 2. tag it. Nothing is published yet.
git tag -a v1.19.0 -m "v1.19.0 — ..." && git push origin v1.19.0

# 3. verify the tagged build: this packs the tarball that would be published
#    and drives it end to end, including an upgrade from an older database.
npm run e2e

# 4. publish the release. This fires the publish workflow.
gh release create v1.19.0 --notes-file notes.md

このワークフローはタグ付けされたコミットに対してテストスイートを再実行し、package.json と一致しないタグや、すでに npm に存在するバージョンを拒否します。また、GitHub のプレリリースを next dist-tag に送るため、npm install saga-mcp を実行した人にそのバージョンが提供されることはありません。公開に失敗した場合は、gh workflow run "Publish to npm" -f tag=v1.19.0 を使って同じタグで再試行できます。

---

サポート

• 課題: https://github.com/spranab/saga-mcp/issues
• リポジトリ: https://github.com/spranab/saga-mcp

再現手順が添えられたバグ報告は、ここでは非常に役立ちます。上記の細かな挙動のいくつかは、当たり前だと思われていた動作が間違っていると誰かが報告してくれたおかげで実現しました。

関連プロジェクト

1 人が構築したエージェントインフラストラクチャの一部で、組み合わせて使うことを想定しています。

• yantrikdb-mcp — 同じエージェント向けの永続的な認知メモリです。計画したことではなく、学習したことを記録します。
• brainstorm-mcp — 計画をトラッカーに登録する前に、複数のモデルで議論します。
• swarmcode — 異なるマシン上の Claude Code インスタンス間のリアルタイムチャンネルです。
• truenas-mcp — 278 の TrueNAS SCALE アクションを、1 つの階層型ツールで利用できます。
• mcpier — API キーをクライアントに置かずに管理できる、セルフホスト可能な MCP コントロールプレーンです。

ライセンス

MIT