Follow-Through

The MCP agent that remembers what everyone promised — so nothing quietly dies.

Follow-Through is a TypeScript Model Context Protocol (MCP) server built on NitroStack. It listens to meeting transcripts, extracts every spoken commitment (who promised what, to whom, by when, and with what confidence), persists it durably, and then keeps working autonomously: it polls Slack, email, and Linear for real evidence of completion, sends escalating nudges when deadlines slip, and escalates to a manager's inbox when a commitment goes silent — all without a human having to re-prompt it.

For a demo, a compressed virtual clock (simulate_days_passing) makes a full week of follow-up observable in seconds, and a companion widget renders the live commitment board.

Why this exists

Most action items from meetings never make it into a tracker. They live in a transcript nobody re-reads, get half-remembered, and quietly expire. Follow-Through closes that loop in three moves:

1. Capture — the moment a promise is spoken, it becomes a durable record with an auto-created Linear ticket.

2. Verify — instead of nagging blindly, the agent checks Slack and email for evidence that the work actually got done.

3. Escalate gracefully — if there's no evidence and no response, nudges get more specific, and a human manager is looped in with full context.

Related MCP server: Docket MCP Server

Key features

How it works

                 ┌────────────────────────────────────────────────────────┐
   transcript    │                        App                             │
  ─────────────► │  ingestion ──► store ──► evidence ──► nudge ──► linear  │
                 │                     ▲                                 │
                 │                     │  scheduler (poll loop / clock)   │
                 │      widget ◄───────┴── query_commitments              │
                 └────────────────────────────────────────────────────────┘

Modules

The decision state machine

For each due, non-aspirational commitment, the scheduler runs every poll:

        due (+ grace)            +3d (committed)           +6d (committed)
 open ───────────────────► nudged_1 ─────────────► nudged_2 ─────────────► escalated
     gentle nudge                specific nudge             manager + watcher

At every step it first checks evidence (Slack/email) and ticket status (Linear Done) — proof beats nagging. Nudges only happen when there is neither evidence nor a completed ticket.

Confidence tiers and cadence

Evidence scoring

scoreEvidence() in src/common/matching.ts combines three signals:

• Recall — what fraction of the commitment's key terms appear in the message

• Completion signals — words like sent, published, shipped, delivered, merged

• Author match — the message came from the commitment owner

A score ≥ 0.6 marks the commitment done. Keyword-only mentions cap at 0.55 — deliberately below the bar, because a false "done" is worse than a false nudge.

Technology stack

• Runtime: Node.js ≥ 20 (ESM, TypeScript strict mode)

• Framework: NitroStack (@nitrostack/core) — decorator-based modules, DI, MCP server

• Persistence: Pure-JS JSON-file store (data/follow-through.json, atomic writes) — zero native dependencies, deploy-safe on any base image

• Validation: Zod

• LLM: fetch-based calls (no heavy SDK) — Anthropic Messages API or OpenRouter chat-completions

• Widgets: Next.js 14 + React 18 (@nitrostack/widgets)

Project structure

src/
  app.module.ts                 # root module — wires all six modules
  common/
    types.ts                    # Commitment, Person, Ticket, evidence/nudge types
    dates.ts                    # date math + virtual-today helpers
    matching.ts                 # evidence scoring + thresholds
  modules/
    ingestion/                  # extract_commitments + sample transcript fixture
    store/                      # JSON-file store + virtual clock + query/upsert/promote
    evidence/                   # search_slack_evidence / search_email_evidence
    nudge/                      # send_nudge
    linear/                     # linear_create_ticket / get_status / update_status / escalate
    scheduler/                  # simulate_days_passing / reset_demo + poll loop
  providers/
    slack.ts                    # real Slack evidence search + DM nudges (Slack Web API)
    email.ts                    # real SMTP send + IMAP evidence search
    linear.ts                   # real Linear GraphQL client
  widgets/app/commitment-dashboard/  # the live dashboard widget (Next.js)
scripts/
  e2e-smoke.mts                 # full-lifecycle regression test (30+ asserts)
  extract-sample.mts            # one-liner demo: sample transcript → extract_commitments
  check-state.mts               # dump live server truth (commitments + ticket statuses)
  providers-check.mts           # which real providers/LLM keys are configured
  live-check.mts                # live create/read/update against real Linear + Slack/email search

Getting started

Prerequisites

• Node.js ≥ 20 (developed on 24.15.0)

• npm

Install

npm install
npm run build

The build compiles TypeScript to dist/ and bundles the widget to src/widgets/out/.

Configuration

Copy .env.example to .env. Everything has sane defaults; no key is required.

Provider resolution (auto): uses Anthropic if its key is set, else OpenRouter if its key is set, else the offline deterministic extractor. Any LLM failure falls back to the offline extractor — the demo never breaks.

Demo vs. real mode: when none of SLACK_BOT_TOKEN, EMAIL_IMAP_*, or LINEAR_API_KEY are set, the server runs in demo mode and all Slack/email/ Linear traffic is fixture-based. Configure any subset and only those providers go real — the rest keep their fixtures. Run npx tsx scripts/providers-check.mts to see which mode you're in.

No key? No problem. The deterministic extractor produces the same structured output from the same tool schema with zero network and zero cost.

Running

Development (recommended for demoing)

npm run dev

• MCP server runs over stdio (wait for a client, see Connect a client)

• Widget dev server runs on http://localhost:3001 with hot reload (route: http://localhost:3001/commitment-dashboard)

Production

npm run build
npm start

Boots in dual mode — stdio and HTTP at http://localhost:3000/mcp.

Demo walkthrough

The sample transcript (mtg_ops_standup) contains four commitments designed to exercise every path: a completion, a slacker, a hedged promise, and an aspirational wish.

# 0. Clean slate (virtual "today" = real today, e.g. 2026-07-31)
reset_demo

# 1. Extract commitments from the sample transcript → 4 commitments + 4 Linear tickets
get_sample_transcript
extract_commitments  { transcript_text, participants, meeting_date }

# 2. Fast-forward 3 days (→ Aug 3, the first due date)
simulate_days_passing  { days: 3 }
#    Priya  → done_evidence      (Slack + email show the report was sent)
#    Marcus → nudge_1            (gentle nudge, no evidence yet)

# 3. Fast-forward 3 days (→ Aug 6)
simulate_days_passing  { days: 3 }
#    Marcus → nudge_2            (more specific nudge)

# 4. Fast-forward 3 days (→ Aug 9)
simulate_days_passing  { days: 3 }
#    Marcus → escalated          (ticket watcher: raj.patel@company.com + context comment)
#    Aisha  → nudge_1            (hedged — grace period meant she wasn't chased early)
#    Tom    → open, untouched    (aspirational — never auto-chased)

# 5. Inspect the final board
query_commitments
# 6. Prove the escalation stuck to the ticket
linear_get_status  { ticket_id: "LIN-482" }   # → Escalated, watchers: [...]

For a browser visual, open the dashboard widget (see below) — it reflects the same board.

Tools

All 14 tools registered on the follow-through MCP server:

Widget dashboard

query_commitments is auto-attached to a Next.js widget (ui://widget/next-commitment-dashboard.html). Inside an MCP host it renders a theme-aware board: owner, commitment, due date, confidence, status badge, evidence trail, and nudge count.

Standalone (no host injecting data) the page shows only a loading shell — the data is injected by the host when the tool runs.

Testing

npm run build
npx tsx scripts/e2e-smoke.mts

Drives the real server over the MCP stdio protocol and asserts 30+ invariants: extraction shape, confidence tiers, due-date resolution, nudge timing, hedged grace, aspirational immunity, evidence thresholds, escalation watcher, and manual nudges. Ends with ALL CHECKS PASSED.

Verify what the agent reports (before the demo, and anytime a tool call fails)

If a client like Claude.ai ever reports a connector error mid-demo, never assume the answer that followed came from the server — re-run the tools live and compare:

npm run build
npx tsx scripts/check-state.mts

This dumps the server's actual current commitments and Linear ticket statuses (each ticket includes as_of, the server-side date the status was read at), so anything the agent quoted can be checked against ground truth. Real tool responses always carry server data (updated_at, as_of, ticket ids); anything that doesn't match a fresh run is client-side reconstruction, not a result.

Demo etiquette: if a tool call visibly fails, say "let me retry that" and call it again instead of continuing — a visibly retried tool beats a confidently wrong number. Connector errors ("Connector search is off", "Unable to reach …") are almost always Claude.ai's connector settings: open Settings → Connectors, confirm the FollowThrough connector is enabled/approved, and re-approve it for the current conversation (approval is per-chat, so a new chat needs it again).

Simulation semantics

simulate_days_passing takes a single days number and advances the virtual clock by exactly that many days in one call (then runs one scheduler poll). So { days: 9 } jumps straight to due+9 in a single step — it is not three 3-day calls. The demo shows a cleaner narrative with separate calls (3 → 3 → 3), which also makes each nudge/escalation stage observable as it happens, but the tool never requires them.

Connect a client

Point any MCP client (Claude Desktop, Cursor, etc.) at the built server:

{
  "mcpServers": {
    "follow-through": {
      "command": "node",
      "args": ["<path-to>/dist/index.js"],
      "cwd": "<path-to>"
    }
  }
}

Or hit the HTTP endpoint in dual/production mode: http://localhost:3000/mcp. The CLI can also wire up Cursor automatically: npx nitrostack-cli cursor.

Production considerations

• Real integrations, optional. Slack (src/providers/slack.ts), email (src/providers/email.ts), and Linear (src/providers/linear.ts) are plain env-driven clients. Without keys they fall back to the deterministic fixtures, so the demo and the production path are the same code.

  • Slack requires a bot token with channels:read, groups:read, channels:history, groups:history, im:history, users:read, users:read.email, chat:write. The *:read scopes resolve channel names in SLACK_EVIDENCE_CHANNELS to ids (names or ids both accepted); the bot must be added to every channel it searches. Nudges DM the commitment owner.

  • Email uses SMTP (EMAIL_SMTP_*) for outbound nudges and IMAP (EMAIL_IMAP_*) to search mail for evidence, parsed with mailparser.

  • Linear uses the GraphQL API (LINEAR_API_KEY); escalations add the manager as a ticket subscriber plus a contextual comment.

• Real cadence. Set SCHEDULER_INTERVAL_MS to the desired poll rate and remove simulate_days_passing / reset_demo from the tool surface if you don't want them exposed.

• LLM cost. Extraction is the only LLM call. It runs once per transcript; the polling/nudge/escalation machinery is pure code. Use OpenRouter :free models or the offline extractor to keep cost at $0.

• Transport. Production boots in dual mode (stdio + HTTP). OAuth logs at startup are framework noise unless you configure an authorization server.

Troubleshooting

License

MIT — see the repository root. Built for demonstration on the NitroStack MCP framework.