https://github.com/tiberriver256/mcp-server-systems-thinking
An MCP server built around Donella Meadow's book "Thinking in Systems, a primer"
https://github.com/tiberriver256/mcp-server-systems-thinking
Last synced: about 1 month ago
JSON representation
An MCP server built around Donella Meadow's book "Thinking in Systems, a primer"
- Host: GitHub
- URL: https://github.com/tiberriver256/mcp-server-systems-thinking
- Owner: Tiberriver256
- Created: 2025-06-20T19:40:45.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-06-25T21:14:45.000Z (3 months ago)
- Last Synced: 2025-08-30T07:57:26.557Z (about 1 month ago)
- Language: TypeScript
- Size: 78.1 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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)
```jsonc
{
"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. fileciteturn3file4L20-L30
> - **elements & interconnections** – the nouns and their physical/info links. fileciteturn3file9L38-L41
> - **stocks & flows** – accumulations and the rates that change them. fileciteturn3file3L9-L22
> - **loops** – balancing (B) dampen change; reinforcing (R) amplify. fileciteturn3file11L12-L19
> - **leverage_points** – Meadows’s 12 intervention levers, from parameters (12) to paradigm shifts (2) and _transcending paradigms_ (1). fileciteturn3file2L34-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. fileciteturn3file1L18-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.” fileciteturn3file14L1-L4
---