RippleBack — About the Project

Inspiration

Every delivery plan looks like a list of tickets—until something breaks. Suddenly, it becomes a dependency graph, and the team has to reconstruct the impact on a whiteboard.

A payment service slips. An integration test becomes impossible. A release timeline is no longer realistic. Traditional project-management tools track tasks and deadlines, but understanding the consequences of a disruption requires more: What is blocked? What can still proceed? Which recovery options are structurally valid? How does each option affect the critical path?

The real question isn't simply “What is late?” It's “What has become impossible, and what is the most reliable way to recover?”

That question inspired RippleBack, a disruption-analysis and recovery platform designed for the moment a delivery plan breaks. Disruptions ripple forward through dependencies, so recovery must reason backward through their consequences. We wanted a tool that could analyze the blast radius, evaluate feasible alternatives, explain its recommendations with evidence, and acknowledge uncertainty instead of inventing answers.

What It Does

RippleBack is an MCP-native disruption and recovery platform that models delivery plans as typed dependency graphs and exposes its deterministic analysis engines through 17 Model Context Protocol (MCP) tools.

When a disruption occurs, RippleBack helps teams:

Analyze impact: Identify blocked, at-risk, external, healthy, and completed entities, with evidence supporting each classification.
Find parallel work: Determine which tasks can continue despite the disruption.
Generate recovery alternatives: Explore potential changes and validate their structural feasibility against dependency constraints.
Compare critical paths: Measure how each feasible alternative changes the relative project timeline.
Triage blockers and rebalance workloads: Identify actionable priorities and evaluate workload redistribution.
Evaluate recovery proposals: Rank feasible, scorable alternatives using explicit criteria.
Forecast responsibly: Produce schedules when sufficient duration data exists and clearly identify missing information when it does not.

The platform exposes 12 read-only analysis tools and five write tools. Writes are disabled by default and protected by explicit enablement, dry-run previews, confirmation, optimistic concurrency, and idempotency controls.

A React dashboard and conversational assistant make these capabilities accessible through interactive dependency graphs, timeline comparisons, and visible MCP tool traces. The assistant can interpret requests and orchestrate read-only analysis, while a separate, explicitly confirmed workflow handles state-changing operations.

How We Built It

1. A deterministic recovery engine

We built the analytical core before the interface. A delivery plan is represented as a directed graph:

[ G=(V,E) ]

Dependencies have explicit semantics:

requires_completion represents a hard ordering constraint.
requires_arrival_by represents a hard arrival-time constraint.
benefits_from represents a soft dependency that introduces risk without automatically blocking work.

The critical path is the longest chain of hard dependencies:

[ L(G)=\max_{P\in\mathcal{P}(G)}\sum_{v\in P}d(v) ]

Here, (d(v)) represents an entity's declared duration, using one unit when the model specifies no duration. We calculate the longest path over a directed acyclic graph in (O(|V|+|E|)), with deterministic tie-breaking to ensure reproducible results.

For a recovery option (o), let (G_o) represent the proposed plan and (G_0) the committed plan. Its relative critical-path change is:

[ \Delta(o)=L(G_o)-L(G_0) ]

Options are validated before scoring:

[ F(o)=1 \iff G_o\text{ is acyclic and all hard constraints hold} ]

Only feasible options proceed to scoring:

[ S(o)=\sum_m w_m m(o),\qquad w_m\geq 0 ]

Lower scores are better. By default, the score considers relative delay, the metric available across feasible options. If a configured metric has a nonzero weight but lacks a real value, the option is marked unscorable rather than silently assigning zero.

The recommendation is the lowest-scoring feasible, scorable option, with ties resolved by option ID. If no qualifying option exists, RippleBack returns no recommendation instead of manufacturing one.

2. An MCP-native architecture

We organized the platform into distinct layers:

Python analysis engine: Handles dependency-graph construction, cycle detection, impact analysis, blocker triage, recovery alternatives, constraint validation, forecasting, workload rebalancing, scheduling, scoring, and comparison.
MCP server: Exposes the analysis and recovery capabilities through the official Python MCP SDK over Streamable HTTP.
MCP client adapter: Uses a genuine MCP client session, discovers the live tool catalog, validates arguments against tool schemas, and exposes a narrow REST interface to the browser.
React dashboard: Built with React 19 and TypeScript, using React Flow for dependency graphs, Recharts for timeline comparisons, and an MCP inspector for tool calls, arguments, execution times, and structured results.
Persistence and audit layer: Uses SQLAlchemy for persistence, plan versioning, audit trails, project-management synchronization overlays, and controlled write operations.
Conversational assistant: Supports optional Amazon Bedrock interpretation through the Bedrock Runtime Converse API, with a deterministic interpreter as a fallback.

The assistant uses the available tool catalog to interpret requests and orchestrate analysis. The five write tools are withheld from the model, and the assistant cannot invoke them directly. When Bedrock is unavailable or produces malformed output, the deterministic fallback takes over and reports the reason.

3. Safety through explicit boundaries

RippleBack separates probabilistic language interpretation from deterministic decision-making. The assistant can interpret intent, but it cannot invent entity IDs, parameters, dates, or costs. The orchestration layer validates arguments, sequences tool calls, and passes actual intermediate results between steps.

State-changing operations follow a separate workflow:

Dry run → Confirm → Commit

The write path incorporates expiring HMAC-signed confirmation tokens bound to the exact change set and plan version, optimistic concurrency checks, idempotency keys, audit records, and an outbox for project-management write-back. Writes remain disabled by default.

This separation lets teams benefit from conversational AI without giving the model unrestricted control over the plan of record.

Challenges We Faced

Bridging the browser and MCP

The browser/MCP boundary presented both protocol and reliability challenges. Rather than exposing a raw MCP session to the frontend, we built an adapter that owns the client session, serializes access, validates tool arguments against discovered JSON schemas, and translates errors into explicit responses.

One particularly difficult issue was intermittent HTTP 503 errors caused by Starlette's BaseHTTPMiddleware interacting with the MCP SDK's cancellation scopes. Replacing it with pure ASGI middleware resolved the underlying structural problem.

Making AI useful without letting it invent facts

Language models can produce convincing explanations even when the underlying data is incomplete. We constrained the model to interpretation and delegated analysis, validation, and execution to deterministic components.

Every tool call is validated, intermediate results are grounded in actual tool outputs, and failed steps terminate with an explicit explanation instead of fabricated conclusions.

Preserving uncertainty

We treated honesty as a system invariant rather than a writing style:

Missing duration data does not justify inventing a schedule.
An infeasible recovery option cannot become a recommendation simply because alternatives are worse.
Missing scoring metrics produce an unscorable result, not a fabricated value.
Missing substitute declarations produce no candidates rather than inferred vendors.
Hypothetical recovery results are explicitly labeled.
Relative timeline units are not presented as calendar dates without the data needed to support them.

These rules are enforced through implementation and testing, not merely prompt instructions.

Testing the real protocol

Mocked tests alone would not reveal session lifecycle issues, cancellation behavior, tool-error propagation, or schema drift. We therefore included a live MCP integration test that starts a real server subprocess and communicates with it through the official client SDK.

The system has 659 reported passing tests, including this live-protocol integration coverage. A clearly labeled mock mode also supports dashboard demonstrations without a running backend.

What We Learned

AI safety is an architectural property, not a prompt. Models are useful for understanding natural language and selecting intent, while deterministic code should own graph algorithms, constraint validation, scoring, and state changes.

MCP schemas are part of the product design. Tool descriptions, stable error codes, and predictable result structures determine whether assistants can compose tools correctly and whether users can understand what happened.

Honest answers are more valuable than impressive guesses. Relative critical-path units are preferable to unsupported calendar dates. An unscorable option is better than a misleading ranking. A deterministic fallback is better than a system that stops working when its language model is unavailable.

Most importantly, a recovery recommendation should be explainable, reproducible, and constrained by what the system actually knows.

What's Next

Our next milestones are:

Verify live Amazon Bedrock inference and expand model-assisted explanations.
Build an Alexa skill that exposes the same MCP-powered recovery workflow.
Introduce authenticated remote MCP hosting.
Expand project-management integrations and controlled write-back capabilities.
Continue improving recovery evaluation and the clarity of evidence presented to users.

The Bedrock integration and fallback path are implemented, but successful live inference has not yet been verified because the audit environment lacked the required AWS credentials, region, and model access.

The Vision

RippleBack turns delivery disruption into a structured recovery workflow. It connects dependency analysis, feasible alternatives, workload rebalancing, and transparent recommendations through an MCP-native architecture.

When a plan breaks, teams shouldn't have to guess their way back. They should be able to see what changed, understand their options, and choose a recovery path backed by evidence—not confidence alone.