Decision OS MCP Server

Decision OS MCP

An MCP server for Decision OS — an LLM-native decision tracking and learning system.

What is Decision OS?

Decision OS captures novel pressure — moments when reality surprises you during engineering work. Unlike traditional documentation, it focuses on what an LLM couldn't predict, creating a learning loop:

Cases → Pressure Events (surprises) → Outcomes → Foundations (compressed learnings)

Quick Start

1. Install the MCP Server

# Global install
npm install -g decision-os-mcp

# Or use npx (no install needed)
npx decision-os-mcp

2. Add to Your Project

Copy the template to your project:

cp -r templates/.decision-os /path/to/your-project/

Edit config.yaml with your project name.

3. Configure Your Agent

Cursor

Add to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "decision-os": {
      "command": "npx",
      "args": ["-y", "decision-os-mcp"],
      "env": {
        "DECISION_OS_PATH": "${workspaceFolder}/.decision-os"
      }
    }
  }
}

Copy the Cursor rules template:

cp templates/.cursor/rules/decision-os.mdc /path/to/your-project/.cursor/rules/

Claude Code / Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "decision-os": {
      "command": "npx",
      "args": ["-y", "decision-os-mcp"],
      "env": {
        "DECISION_OS_PATH": "/absolute/path/to/your-project/.decision-os"
      }
    }
  }
}

Copy the agent instructions template (includes a .claude/rules/ symlink to AGENTS.md):

cp templates/AGENTS.md /path/to/your-project/
cp -R templates/.claude /path/to/your-project/

Note: Claude Desktop requires absolute paths in DECISION_OS_PATH (no ${workspaceFolder}).

AGENTS.md is an open standard supported by 20+ coding agents including OpenAI Codex, Google Jules, Claude Code, Cursor, Aider, Zed, Warp, VS Code, and more. The .claude/rules/ symlink lets Claude Code pick it up automatically too — one file, every agent.

Tools

Core Concepts

Pressure Events

The primary learning artifact. Logged when something unexpected happens:

expected: "Supabase insert would throw on null FK"
actual: "RLS silently blocked the write, no error"
adaptation: "Added explicit null-check before insert"
remember: "Supabase RLS fails silently on null FK values"

Foundations

Compressed learnings promoted from repeated pressure events:

id: F-0001
title: "Supabase RLS fails silently on null FK"
default_behavior: "Always validate FK values before insert when using RLS"
context_tags: [SUPABASE, RLS, DATA_MODEL]
confidence: 2  # Out of 3
scope: PROJECT  # or GLOBAL
origin_project: my-project
validated_in: [my-project, other-project]
exit_criteria: "Supabase adds explicit error for null FK violations"
source_pressures: [PE-0003, PE-0007]

Hierarchical Foundations (GLOBAL -> PROJECT)

Decision OS supports a cascading scope model similar to Git config:

~/.decision-os/                    # GLOBAL (user-wide, universal learnings)
├── config.yaml
└── defaults/foundations.yaml      # GF-prefixed foundations

~/projects/my-app/.decision-os/    # PROJECT (specific to this codebase)
├── config.yaml
├── cases/
└── defaults/foundations.yaml      # F-prefixed foundations

Resolution order: PROJECT wins over GLOBAL on conflicts.

Global foundations are recommendations, not rules. They represent universal patterns that transcend specific tech stacks:

• Tool behaviors (e.g., "MCP descriptor paths may be stale")
• Debugging strategies (e.g., "Trace call sites before refactoring")
• Meta-learnings (e.g., "Question requirements before implementing")

**Setu