decision-os-mcp 0.3.2 → 0.4.0

package/AGENTS.md

@@ -0,0 +1,69 @@
+# Decision OS MCP
+
+MCP server for Decision OS — an LLM-native decision tracking and learning system. TypeScript, Node.js 18+, ES modules, `@modelcontextprotocol/sdk`, YAML storage, Zod validation.
+
+## Commands
+
+```bash
+npm install          # Install dependencies
+npm run build        # Compile TypeScript (tsc)
+npm run dev          # Watch mode (tsc --watch)
+npm test             # Run all tests (vitest run)
+npm run test:watch   # Watch tests (vitest)
+npm start            # Run server (set DECISION_OS_PATH first)
+```
+
+Run `npm run build && npm test` before committing. All tests must pass.
+
+## Architecture
+
+```
+src/
+├── index.ts                  # MCP server entry, tool definitions, request handler
+├── schemas.ts                # Zod schemas for all types and tool inputs
+├── storage.ts                # Single-scope storage engine (YAML read/write)
+└── hierarchical-storage.ts   # Multi-scope storage (PROJECT + GLOBAL cascading)
+test/
+├── storage.test.ts
+└── hierarchical-storage.test.ts
+templates/                    # Setup templates for consumers
+```
+
+- Entry point registers 13 MCP tools via `@modelcontextprotocol/sdk`
+- All tool input validation uses Zod schemas from `schemas.ts`
+- Storage is YAML-based, file-system only, no network calls
+- Hierarchical storage merges `~/.decision-os/` (GLOBAL) with project-level `.decision-os/` (PROJECT)
+- PROJECT scope wins over GLOBAL on conflicts
+
+## Conventions
+
+- ES modules (`"type": "module"` in package.json) — use `.js` extensions in imports
+- Strict TypeScript (`strict: true`, target ES2022, NodeNext module resolution) — no `any`, no `@ts-ignore`
+- Tool definitions in `TOOLS` array follow MCP SDK `Tool` type with `annotations`
+- All tool handlers live in the `switch` block inside `CallToolRequestSchema` handler
+- Zod for all input validation; errors formatted as `path: message`
+- Error handling: `ZodError` → formatted validation message; `Error` → `.message`; else → `String(error)`
+- Regret values accept both number (0-3) and string ("0"-"3") via `z.preprocess`
+- Foundation IDs: `F-NNNN` (project), `GF-NNNN` (global)
+- Pressure event IDs: `PE-NNNN`
+- Case IDs: `NNNN-slug-title`
+
+## Testing
+
+- Tests use Vitest with temp directories for isolation
+- Test files: `test/storage.test.ts`, `test/hierarchical-storage.test.ts`
+
+## Adding a New Tool
+
+1. Add input schema to `schemas.ts`
+2. Add `Tool` definition to `TOOLS` array in `index.ts` (include `annotations`)
+3. Add handler case to the `switch` block in the `CallToolRequestSchema` handler
+4. Add tests in `test/`
+5. Update tool table in `README.md`
+
+## PR Guidelines
+
+- Title format: descriptive summary of the change
+- Run `npm run build && npm test` before opening a PR
+- Include test coverage for new tools or storage logic
+- Update `README.md` tool table if adding/removing tools

package/README.md

@@ -32,7 +32,9 @@ cp -r templates/.decision-os /path/to/your-project/
 
 Edit `config.yaml` with your project name.
 
-### 3. Configure Cursor
+### 3. Configure Your Agent
+
+#### Cursor
 
 Add to your project's `.cursor/mcp.json`:
 
@@ -56,6 +58,35 @@ 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):
+
+```json
+{
+  "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):
+
+```bash
+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](https://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
 
 | Tool | Description |
@@ -178,10 +209,14 @@ your-project/
 │   │       └── ...
 │   └── defaults/
 │       └── foundations.yaml  # F-prefixed project learnings
-├── .cursor/
+├── .cursor/                  # Cursor setup
 │   ├── mcp.json              # MCP server config
 │   └── rules/
-│       └── decision-os.mdc   # LLM instructions
+│       └── decision-os.mdc   # LLM instructions (Cursor format)
+├── .claude/                  # Claude Code setup
+│   └── rules/
+│       └── decision-os.md    # -> symlink to ../../AGENTS.md
+├── AGENTS.md                 # Agent instructions (Claude Code, Codex, Jules, etc.)
 └── src/
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "decision-os-mcp",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "MCP server for Decision OS - LLM-native decision tracking and learning system",
   "type": "module",
   "main": "dist/index.js",
@@ -20,8 +20,18 @@
     "decision-os",
     "llm",
     "cursor",
+    "claude",
+    "codex",
+    "agents-md",
     "ai-engineering"
   ],
+  "files": [
+    "dist/",
+    "templates/",
+    "AGENTS.md",
+    "README.md",
+    "PRIVACY.md"
+  ],
   "author": "",
   "license": "MIT",
   "dependencies": {

package/templates/AGENTS.md

@@ -0,0 +1,38 @@
+# Decision OS
+
+You have access to Decision OS MCP tools for tracking decisions and learning from novel pressure.
+
+## Workflow
+
+1. **Task start**: Call `get_context()` to load active case, foundations, and conflicts. Create a case with `create_case()` if none exists.
+2. **When surprised**: Call `quick_pressure({ expected, actual })` for fast capture or `log_pressure({ expected, actual, adaptation, remember })` for full detail. When in doubt, capture it.
+3. **Before BUILD decisions**: Call `check_policy({ signals })` to check requirements.
+4. **Task end**: Call `close_case()` with regret (0-3), notes, and regressions. Cases with regret 0 and no unpromoted PEs are auto-deleted.
+5. **Periodically**: Call `suggest_review()` to find unextracted learnings.
+
+## When to Log Pressure
+
+- Something failed that you predicted would work
+- You changed approach mid-implementation
+- You discovered an undocumented constraint
+- A library behaved differently than expected
+- Performance was unexpectedly poor or good
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `get_context` | Load active case, foundations, conflicts |
+| `quick_pressure` | Fast pressure capture (expected + actual only) |
+| `log_pressure` | Full pressure capture with adaptation and remember |
+| `create_case` | Start a new unit of work |
+| `close_case` | Close with outcome signals |
+| `set_active_case` | Switch active case |
+| `check_policy` | Check policy requirements for signals |
+| `get_foundations` | Query compressed learnings |
+| `search_pressures` | Search past pressure events |
+| `promote_to_foundation` | Promote PEs to foundation |
+| `elevate_foundation` | Elevate project foundation to global |
+| `validate_foundation` | Validate global foundation in current project |
+| `suggest_review` | Find unextracted learnings |
+| `list_cases` | List all cases |

package/templates/claude-desktop-mcp-config.json

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