mcp -systems-thinking

This Systems-Thinking MCP server provides a single tool, systems_thinking_writer, which accepts a complete systems-thinking JSON document via HTTP and validates it against the defined Zod schema. On a POST or PUT to /model, the server persists the latest document atomically (in-memory with a nightly Postgres JSONB flush) and returns a validation result, including complete, missing_fields, and inconsistency_warnings. A GET to /model returns the latest stored document so agents can inspect the current state. Use this to iteratively refine your model: if validation fails, the response highlights gaps or structural inconsistencies so the agent can adjust the document and retry until complete becomes true. The server also streams responses under FastMCP, enabling efficient long-lived connections for agents that need incremental feedback during iteration.

Prerequisites:

• Node.js v20+ (with npm)
• Git
• Optional: PostgreSQL if you plan to enable nightly flush persistence to JSONB

1. Clone the repository git clone https://github.com/<org>/<repo>.git cd <repo>/mcp-server-systems-thinking

2. Install dependencies npm install

3. Build (TypeScript to JavaScript) npm run build

4. Configure environment (optional, for Postgres persistence)

   • If you want to enable Postgres nightly flush, set: PGHOST, PGUSER, PGPASSWORD, PGDATABASE, PGPORT
   • If you’re running locally with in-memory persistence only, you can skip Postgres configuration.

5. Run the server

   • Development (in-memory, with FastMCP): npm run start

6. Verify the health endpoints

   • GET http://localhost:YOUR_PORT/healthz
   • GET http://localhost:YOUR_PORT/model

7. Optional: Docker build/run docker build -t systems-thinking-mcp:latest . docker run -p 3000:3000 systems-thinking-mcp:latest

Notes and tips:

• The tool expects a full JSON document that adheres to the provided schema. Use the /model POST/PUT to submit, and the response will include complete, missing_fields, and inconsistency_warnings.
• Validation is performed with Zod; a 422 response is returned when the JSON fails schema validation.
• The server overwrites the existing document on every successful POST/PUT; use this to maintain the latest version atomically.
• If you plan to enable Postgres persistence, ensure the JSONB column is set up and the nightly flush job is running in your environment.
• Health checks and basic logs are provided (pino), which helps with observability in Kubernetes or containerized deployments.
• Endpoints: POST /model – submit a complete JSON document; returns validation results and a copy of the stored doc. GET /model – retrieve the latest stored document.
• If you encounter schema errors, verify field names and types against the Data Model section in the PRD; common issues include mismatched stock/flow references and missing mandatory fields.