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

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

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, `

... View full README on GitHub