Saga MCP

saga-mcp

Your coding agent loses the plan between sessions. You come back tomorrow and it has no idea which of the five things you agreed on are done, which one is blocked on which, or why you rejected the second approach — because the plan lived in the context window, or in a TODO.md nobody updates.

saga-mcp gives the agent a real tracker instead: a SQLite file in your project holding projects, epics, tasks, subtasks, dependencies, comments, notes and decisions, exposed as 41 MCP tools. The agent writes to it as it works and reads it back when it returns. No accounts, no external service, no network calls — the database is a file you own.

---

Install

Add saga-mcp to your MCP client. The same block works for Claude Code (.mcp.json in your project), Claude Desktop (claude_desktop_config.json), and any other MCP client:

{

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

Restart the client. DB_PATH is the only required setting; the file and its schema are created on first use. Prefer a global install? npm install -g saga-mcp, then use saga-mcp as the command instead of npx.

Tested on Node 20, 22 and 24, on Linux, macOS and Windows.

Settings

No API keys, no accounts, no external services.

---

Your first session

You: "Set up tracking for the e-commerce API and plan out auth."

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] })

Tasks 2 and 3 come back blocked — their dependencies aren't done. Finish task 1 and task 2 unblocks itself. That whole exchange, actually run against saga-mcp:

Next session, you: "Where were we?"

tracker_next({})

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

One recommendation with the reason. For the whole picture instead, tracker_dashboard({}) returns stats, epics, blocked and overdue tasks, recent activity and notes, with a summary on top.

And when you would rather look than ask, saga-web puts the same database in a browser:

---

What you get

• [The next thing to do](#asking-what-to-do-next) — one recommendation with its reason, at a third the cost of the dashboard
• [Real sequencing](#ordering-and-dependencies) — dependencies that auto-block and auto-unblock, a manual order the tools respect, and cycles refused rather than deadlocked
• [Guards against agent drift](#keeping-agents-on-the-rails) — a lockable description, and prerequisites enforced on write rather than merely reported
• [A web UI](#web-ui) — saga-web serves the same database in a browser, read *and* write
• [Templates](#templates) — reusable task sets with {variable} substitution, editable in place
• [Archiving and soft delete](#getting-old-work-out-of-the-way) — get finished work out of the context you pay for, reversibly
• [Forgiving input](#forgiving-input) — a smaller model sending an array as a JSON string doesn't silently collapse your batch into one record
• [One file, many projects](#one-database-many-projects) — per-repo databases or one shared file
• A full audit trail — every mutation logged with old and new values, and nothing an agent removes is unrecoverable
• 41 tools with MCP safety annotations on every one, and a tiered surface when you want a smaller context bill

---

Asking what to do next

tracker_dashboard hands an agent everything and leaves it to reason. tracker_next answers the question:

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.

One recommendation with the reason, the next unfinished subtask inside it, a couple of alternatives, and anything overdue or blocked. About a third the size of the dashboard.

The ordering rule worth knowing: continuing beats starting. A task already in progress outranks an untouched one that is overdue or higher priority, because abandoning work in flight just leaves two things unfinished — the overdue work is named in the summary instead. Blocked tasks are never recommended, archived epics and removed tasks are skipped, and subtask dependencies decide which step comes next inside the chosen task.

When nothing is actionable it says what to unblock rather than returning an empty answer:

Nothing is actionable: all 4 remaining task(s) are blocked.

Unblocking #7 'the keystone' would release 3 of them.

---

Ordering and dependencies

A deliberate order wins over a guess. task_list sorts by priority until someone arranges an epic, and from then on it follows the arrangement:

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

Priority is a reasonable guess about what matters; a sequence someone wrote down is not a guess. An agent handed a plan should start at the beginning of it, not at whichever step happens to be marked critical.

Nothing changes for epics nobody has arranged — those sort by priority exactly as before, and an explicit sort_by is always obeyed literally.

Anything omitted from ordered_ids keeps its relative position at the end. sort_order runs ascending — lower sorts first — and a task created *after* an arrangement has no place in it, so it lands at the end rather than the front. In the web UI you can drag tasks into place inside an epic.

Task dependencies auto-block and auto-unblock:

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

Re-evaluation runs whenever a blocker's *doneness* changes in either direction, so reopening a finished blocker blocks its dependents again, and clearing the last dependency releases them. Circular dependencies are refused with the loop named, for tasks and subtasks alike — anything in a cycle would be blocked forever. The web UI shows a banner at the top of a blocked task naming what it waits on, with a picker to add or remove dependencies.

---

Keeping agents on the rails

Two guards for the ways an agent goes wrong on a long task.

A locked description. Agents sometimes rewrite a task's description to record progress, when they meant to add a comment — and the spec you agreed on is gone. Lock it and task_update refuses:

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.

Everything else about the task stays editable — the point is to protect the spec, not freeze the task. The lock cannot be cleared as a side effect of an ordinary task_update; it takes a deliberate task_lock_description call or the lock toggle in the web UI, and both are logged.

This is a guard against confusion, not an adversarial control: an agent that is told to unlock still can. It turns a silent overwrite into a visible, reversible decision.

Locking each task by hand does not scale across a plan, so SAGA_DESCRIPTION_LOCK=on_progress does it for you: a task locks as work starts on it — when it moves to in_progress, review or done, or is created there. It is off unless you set it, since it changes what an agent is allowed to do.

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

It sets the same flag task_lock_description sets, rather than second-guessing every write. So one mechanism governs the field: unlock a task and it stays unlocked, whatever its status does next. blocked is not "started" — a task waiting on a dependency has not been worked on, and dependencies move tasks in and out of that status on their own.

Subtask order and dependencies. New subtasks are appended in order rather than all landing at position 0, subtask_reorder sets the order in one call (or drag them in the UI), and a subtask can wait on its siblings:

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

Reads carry depends_on and blocked, and the block is enforced on write: starting or finishing a subtask whose prerequisites are unmet is refused, and so is completing a task whose checklist is still open.

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 is the way past, for when a person has decided the blocker no longer applies. It works on subtask_update, task_update and task_batch_update, and every override is written to the activity log naming what was skipped. The web UI asks for confirmation and then sends it.

The distinction that matters is between an agent quietly ignoring a blocker and someone choosing to override one. Dependencies stay within one task — a checklist item waiting on something under a *different* task is a task-level dependency, and task_update depends_on already models that.

---

Comments as a decision trail

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" })

Comments persist across sessions — next time an agent calls task_get(5), it sees the full thread.

If a comment turns out to b