MCP Server Decisions

🧠 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

🔄 Architecture

flowchart TD

A[MCP client or AI agent] --> B[JSON-RPC over stdio] B --> C[mcp-server-decisions] C --> D[Record decision] C --> E[Attach prediction] C --> F[Record outcome] C --> G[Query decisions and technology history] D --> H[(Append-only JSONL log)] E --> H F --> H G --> H F --> I[Validation status and accuracy] I --> J[Future technical decisions]

📌 What It Provides

The server exposes four tools:

Example flow

Decide → Predict → Implement → Measure → Validate → Learn

A decision can produce an outcome-gate reminder such as:

{

"decision_id": "DEC-2026-0001", "status": "OK", "OUTCOME_GATE": "2 prediction(s) still lack outcomes." }

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

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

python3 -m pip install mcp-server-decisions

Run the self-test

python3 -m pip install -e .

python3 server.py --selftest

Configure an MCP client

{

"mcpServers": { "mcp-server-decisions": { "command": "mcp-server-decisions" } } }

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:

MCP_DECISIONS_LOG_PATH=/path/to/decisions.json mcp-server-decisions

🗂️ Project Structure

.

├── server.py # MCP server and tool implementations ├── scripts/ # Reports derived from the decision log ├── docs/ # Architecture, examples, and integrations ├── .github/ISSUE_TEMPLATE/ # Reusable bug and feature templates ├── CONTRIBUTING.md # Development and contribution workflow ├── QUICKSTART.md # Guided setup and first decision ├── server.json # MCP Registry metadata ├── pyproject.toml # PyPI package metadata └── LICENSE # MIT license

📚 Documentation

• Quick Start — install and record a first decision.
• Client Integrations — configure MCP clients.
• Detailed Examples — JSON-RPC requests and responses.
• Architecture & Design — storage, IDs, scoring, and trade-offs.
• Outcome Gate Pattern — the reusable feedback-loop pattern.
• Contributing — propose fixes, features, and documentation.

🛣️ Roadmap

• Core decision, prediction, and outcome tracking
• Outcome-gate reminders
• Technology performance reporting
• Web UI for browsing and searching decisions
• Notifications for low prediction accuracy
• Reusable decision templates and domain patterns

🤝 Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md, run the self-test, and explain the problem or use case in the pull request.

📄 License

MIT © 2026 Roberto Nascimento