Roberton003/mcp-server-decisions

An open-source MCP server that helps teams record architectural decisions, connect them to testable predictions, and validate outcomes over time. It gives AI agents and developers a lightweight, auditable memory for technical choices.
✨ Project Highlights
- **Outcome-linked decisions** — connect each technical choice to measurable predictions and observed results.
- **In-band outcome gates** — tool responses identify predictions that still need validation before the work is considered complete.
- **Portable storage** — append-only JSONL keeps the log inspectable, easy to back up, and free from database setup.
- **Zero runtime dependencies** — Python's standard library is enough to run the server.
- **MCP-native interface** — expose decision tracking through JSON-RPC over stdio to MCP-compatible clients.
- **Technology feedback** — aggregate validated outcomes to inform future technology choices.
🧰 Technical Stack
| Layer | Technology |
|---|---|
| Protocol | Model Context Protocol over JSON-RPC 2.0 |
| Runtime | Python 3.10+ |
| Storage | Append-only JSONL file |
| Packaging | PyPI / Hatchling |
| Testing | Built-in self-test command |
| License | MIT |
🔄 Architecture
📌 What It Provides
The server exposes four tools:
| Tool | Purpose |
|---|---|
| record-decision | Store the problem, chosen solution, alternatives, technologies, and predictions. |
| record-prediction | Add a measurable prediction to an existing decision. |
| record-outcome | Record the observed result and classify the prediction as success, partial success, or failure. |
| query-decisions | Search decisions by keyword, technology, domain, or result limit. |
Example flow
A decision can produce an outcome-gate reminder such as:
The reminder is a workflow signal, not a claim about adoption or measured impact. See the Outcome Gate Pattern for the design and trade-offs.
📊 Current Project Status
| Area | Status |
|---|---|
| Decision, prediction, and outcome tracking | Available |
| Outcome-gate reminders | Available |
| Technology performance report | Available |
| PyPI package | Published as 1.0.2 |
| External adoption metrics | Not collected yet |
| Web UI and notifications | Roadmap |
The project is early-stage. Contributions, examples from real projects, and feedback are welcome.
🚀 Setup
Prerequisites
- Python 3.10 or newer
- An MCP-compatible client
Install from PyPI
Run the self-test
Configure an MCP client
For client-specific configuration and troubleshooting, see Client Integrations. For a guided first run, see Quick Start.
Configure the log path
By default, the server writes to ~/.local/share/mcp-decisions/decisions_log.json. Set MCP_DECISIONS_LOG_PATH to use another file: