Product Requirements Document (PRD)

1  Objective

Deliver a Systems‑Thinking MCP server that lets an AI agent submit a full systems‑thinking representation (single JSON document) over HTTP. The server validates structure, persists the latest version atomically, and returns validation gaps so the agent can iterate until the document is complete.

2  Background & Motivation

Sequential‑thinking servers proved that forcing LLMs through a rigid I/O contract improves reasoning quality. We apply the same pattern to Donella Meadows‑style systems analysis, enabling agents to reason about boundaries, stocks/flows, feedback loops, and leverage points with minimal server logic.

3  Scope

In‑scope (MVP)

• One MCP Tool: systems_thinking_writer (PUT/POST full JSON each time)
• Validation & gap detection (hard structural checks)
• Atomic persistence of latest document (in‑memory → Postgres JSONB)
• HTTP streaming transport (FastMCP default)
• Basic observability (request logs, health endpoint)

Out‑of‑scope (Post‑MVP)

• Soft warnings / heuristics (e.g., too many reinforcing loops)
• Fine‑grained PATCH updates
• Multi‑document branching or version history navigation
• Role‑based read/write permission model

4  Personas & Use Cases

| Persona | Job‑to‑be‑Done | | ------------------ | --------------------------------------------------------------------------------- | | LLM Agent | Build a complete systems model iteratively; keep retrying until validation passes | | System Analyst | Fetch the current JSON document for visualization or manual review | | DevOps | Deploy and monitor the MCP service |

5  Functional Requirements

5.1  Tool Definition

• Name: systems_thinking_writer
• Input: Full JSON document conforming to Zod schema
• Output: { complete: boolean, missing_fields: string[], inconsistency_warnings: string[] }
• Contract: Reject (HTTP 422) if JSON fails schema; otherwise return validation arrays. complete === true only when both arrays are empty.

5.2  Endpoint Behaviour

| Method | Path | Body | Response | | ------ | -------- | -------- | -------------------------------------- | | POST | /model | JSON doc | Validation result & copy of stored doc | | GET | /model | – | Latest stored doc |

Server overwrites existing doc on every successful POST.

5.3  Validation Rules (MVP)

• Every flow.from_stock & flow.to_stock must have matching stocks.id
• Loops may reference only declared elements
• If a leverage_point.is_applicable === true there must be at least one matching intervention.target_leverage_id

6  Data Model (abridged)

{
  "version": "1.0.0",
  "system_name": "string",
  "boundary": { "purpose": "string", "scope_in": [""], "scope_out": [""] },
  "elements": ["string"],
  "interconnections": [ { "from": "", "to": "", "type": "causal|flow|info" } ],
  "stocks": [ { "id": "", "unit": "", "description": "" } ],
  "flows":  [ { "id": "", "from_stock": "", "to_stock": "", "rate_expr": "" } ],
  "loops": {
    "balancing":   [ { "id": "", "description": "" } ],
    "reinforcing": [ { "id": "", "description": "" } ]
  },
  "leverage_points": [ { "id": 12, "label": "Constants / parameters", "is_applicable": false }, … ],
  "interventions": [ { "target_leverage_id": 4, "proposal": "…", "expected_effect": "…", "confidence": 0.7 } ]
}

7  Architecture & Tech Stack

• Runtime: Node 20+ with TypeScript
• Framework: FastMCP (HTTP streaming transport)
• Validation: Zod (schema reused for prompts & runtime)
• Persistence: In‑memory Map → nightly flush to Postgres (JSONB)
• Container: Dockerfile with multi‑stage build (tsc compile then dist run)
• Observability: pino logs, /healthz endpoint for k8s liveness/readiness

Component Diagram (text)

Client Agent → FastMCP Tool → Zod Validator → InMemoryCache → Postgres
                                   ↑
                        Gap‑Detection Logic

8 Systems‑Thinking Tutorial (Tool Prompt Seed)

Use the following condensed guidance verbatim in the systems_thinking_writer tool description so the AI knows when and how to use the tool:

WHEN TO USE – Call this tool any time you need a structured, Meadows‑style snapshot of a complex situation that clearly has interacting parts and feedback (e.g. urban traffic, product adoption, climate policy).

WHAT THE FIELDS MEAN

• boundary.purpose – the system’s why. Deduced from observed behaviour, not rhetoric. fileciteturn3file4L20-L30
• elements & interconnections – the nouns and their physical/info links. fileciteturn3file9L38-L41
• stocks & flows – accumulations and the rates that change them. fileciteturn3file3L9-L22
• loops – balancing (B) dampen change; reinforcing (R) amplify. fileciteturn3file11L12-L19
• leverage_points – Meadows’s 12 intervention levers, from parameters (12) to paradigm shifts (2) and transcending paradigms (1). fileciteturn3file2L34-L38

HOW TO IDENTIFY A SYSTEM A) parts exist, and B) they affect each other, and C) they create behaviour distinct from each part alone, and D) that behaviour persists over time. fileciteturn3file1L18-L25

RECOMMENDED FILL‑OUT PATH

1. Purpose & boundary – one sentence each.
2. Elements list – nouns only.
3. Interconnections – causal, flow, or info links.
4. Stocks & flows – declare measurable stores then inflow/outflow pipes.
5. Feedback loops – tag each loop B or R; reference involved stocks.
6. Leverage points – tick applicable IDs (1‑12).
7. Interventions – optional proposals targeting leverage IDs.

Keep iterating until the server returns complete: true.

9 Extended Systems‑Thinking Reference (Team Use Only)

A quick‑access cheat‑sheet so we don’t have to re‑scan Meadows every sprint.

| Concept | One‑liner | Fast sanity check | | ------------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | Elements | Tangible or intangible parts of the system | Can you point at it? If yes, it’s an element. | | Interconnections | Physical flows or information signals | Does changing A alter B without outside influence? | | Purpose/Function | The consistent pattern the system produces | Observe behaviour, not mission statements. | | Stock | Memory of past flows (bathtub water, money) | Units must be additive over time. | | Flow | Rate changing a stock (inflow/outflow) | Has units per time. | | Balancing Loop (B) | Goal‑seeking stabiliser | If discrepancy shrinks over time, it’s B. | | Reinforcing Loop (R) | Self‑amplifying growth/decay | Exponential trends; watch doubling time. | | Delay | Gap between cause & effect | Look for oscillations or overshoot. | | Hierarchy | Nested subsystems with their own purposes | Tight coupling at lower levels, loose at top. | | Resilience | Ability to absorb shock and keep purpose | Diversity, buffers, modular slack increase it. | | Leverage ID 12 → 1 | Parameters → feedback strength → info flows → rules → self‑organisation → purpose → paradigm → transcend paradigm | Higher numbers easier to tweak, lower numbers more powerful but cultural. |

Field‑by‑field Deep‑Dive

• boundary.scope_in / scope_out – Be explicit; ambiguity breeds model creep.
• elements – Prioritise catalytic actors (ones that appear in many loops).
• interconnections.type – causal (solid arrow), flow (pipe), info (dashed).
• stocks – Check each has at least one in‑flow or out‑flow; else it’s inert.
• flows.rate_expr – Keep human‑readable (0.1 * demand). Parser TBD.
• loops – Name loops with verb‑phrase + polarity (Sales Reinvest R).
• leverage_points – If is_applicable=true but no intervention, warn.

Rapid Diagnostic Questions

1. What stock is unexpectedly changing fastest? Why?
2. Which loop currently dominates behaviour?
3. Where is the biggest information delay?
4. Which leverage point needs the least political capital to nudge?

“The behavior of a system cannot be known just by knowing the elements.” fileciteturn3file14L1-L4