{
  "markdown": "<!-- mcp-name: io.github.Roberton003/mcp-server-decisions -->\n\n# 🧠 MCP Server: Decisions\n\nAn 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.\n\n[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)\n[![MCP](https://img.shields.io/badge/MCP-stdio-7C3AED?style=for-the-badge)](https://modelcontextprotocol.io/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)\n[![PyPI](https://img.shields.io/pypi/v/mcp-server-decisions?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/mcp-server-decisions/)\n[![Glama](https://glama.ai/mcp/servers/Roberton003/mcp-server-decisions/badges/score.svg)](https://glama.ai/mcp/servers/Roberton003/mcp-server-decisions)\n\n![Architectural Decision Feedback Loop with Outcome Gates](docs/images/project-hero.svg)\n\n## ✨ Project Highlights\n\n- **Outcome-linked decisions** — connect each technical choice to measurable predictions and observed results.\n- **In-band outcome gates** — tool responses identify predictions that still need validation before the work is considered complete.\n- **Portable storage** — append-only JSONL keeps the log inspectable, easy to back up, and free from database setup.\n- **Zero runtime dependencies** — Python's standard library is enough to run the server.\n- **MCP-native interface** — expose decision tracking through JSON-RPC over stdio to MCP-compatible clients.\n- **Technology feedback** — aggregate validated outcomes to inform future technology choices.\n\n## 🧰 Technical Stack\n\n| Layer | Technology |\n|---|---|\n| Protocol | Model Context Protocol over JSON-RPC 2.0 |\n| Runtime | Python 3.10+ |\n| Storage | Append-only JSONL file |\n| Packaging | PyPI / Hatchling |\n| Testing | Built-in self-test command |\n| License | MIT |\n\n## 🔄 Architecture\n\n```mermaid\nflowchart TD\n    A[MCP client or AI agent] --> B[JSON-RPC over stdio]\n    B --> C[mcp-server-decisions]\n    C --> D[Record decision]\n    C --> E[Attach prediction]\n    C --> F[Record outcome]\n    C --> G[Query decisions and technology history]\n    D --> H[(Append-only JSONL log)]\n    E --> H\n    F --> H\n    G --> H\n    F --> I[Validation status and accuracy]\n    I --> J[Future technical decisions]\n```\n\n## 📌 What It Provides\n\nThe server exposes four tools:\n\n| Tool | Purpose |\n|---|---|\n| `record-decision` | Store the problem, chosen solution, alternatives, technologies, and predictions. |\n| `record-prediction` | Add a measurable prediction to an existing decision. |\n| `record-outcome` | Record the observed result and classify the prediction as success, partial success, or failure. |\n| `query-decisions` | Search decisions by keyword, technology, domain, or result limit. |\n\n### Example flow\n\n```text\nDecide → Predict → Implement → Measure → Validate → Learn\n```\n\nA decision can produce an outcome-gate reminder such as:\n\n```json\n{\n  \"decision_id\": \"DEC-2026-0001\",\n  \"status\": \"OK\",\n  \"OUTCOME_GATE\": \"2 prediction(s) still lack outcomes.\"\n}\n```\n\nThe reminder is a workflow signal, not a claim about adoption or measured impact. See the [Outcome Gate Pattern](docs/OUTCOME-GATE-PATTERN.md) for the design and trade-offs.\n\n## 📊 Current Project Status\n\n| Area | Status |\n|---|---|\n| Decision, prediction, and outcome tracking | Available |\n| Outcome-gate reminders | Available |\n| Technology performance report | Available |\n| PyPI package | Published as `1.0.2` |\n| External adoption metrics | Not collected yet |\n| Web UI and notifications | Roadmap |\n\nThe project is early-stage. Contributions, examples from real projects, and feedback are welcome.\n\n## 🚀 Setup\n\n### Prerequisites\n\n- Python 3.10 or newer\n- An MCP-compatible client\n\n### Install from PyPI\n\n```bash\npython3 -m pip install mcp-server-decisions\n```\n\n### Run the self-test\n\n```bash\npython3 -m pip install -e .\npython3 server.py --selftest\n```\n\n### Configure an MCP client\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-server-decisions\": {\n      \"command\": \"mcp-server-decisions\"\n    }\n  }\n}\n```\n\nFor client-specific configuration and troubleshooting, see [Client Integrations](docs/INTEGRATIONS.md). For a guided first run, see [Quick Start](QUICKSTART.md).\n\n### Configure the log path\n\nBy default, the server writes to `~/.local/share/mcp-decisions/decisions_log.json`. Set `MCP_DECISIONS_LOG_PATH` to use another file:\n\n```bash\nMCP_DECISIONS_LOG_PATH=/path/to/decisions.json mcp-server-decisions\n```\n\n## 🗂️ Project Structure\n\n```text\n.\n├── server.py                         # MCP server and tool implementations\n├── scripts/                          # Reports derived from the decision log\n├── docs/                             # Architecture, examples, and integrations\n├── .github/ISSUE_TEMPLATE/           # Reusable bug and feature templates\n├── CONTRIBUTING.md                   # Development and contribution workflow\n├── QUICKSTART.md                     # Guided setup and first decision\n├── server.json                       # MCP Registry metadata\n├── pyproject.toml                    # PyPI package metadata\n└── LICENSE                           # MIT license\n```\n\n## 📚 Documentation\n\n- [Quick Start](QUICKSTART.md) — install and record a first decision.\n- [Client Integrations](docs/INTEGRATIONS.md) — configure MCP clients.\n- [Detailed Examples](docs/EXAMPLES.md) — JSON-RPC requests and responses.\n- [Architecture & Design](docs/ARCHITECTURE.md) — storage, IDs, scoring, and trade-offs.\n- [Outcome Gate Pattern](docs/OUTCOME-GATE-PATTERN.md) — the reusable feedback-loop pattern.\n- [Contributing](CONTRIBUTING.md) — propose fixes, features, and documentation.\n\n## 🛣️ Roadmap\n\n- [x] Core decision, prediction, and outcome tracking\n- [x] Outcome-gate reminders\n- [x] Technology performance reporting\n- [ ] Web UI for browsing and searching decisions\n- [ ] Notifications for low prediction accuracy\n- [ ] Reusable decision templates and domain patterns\n\n## 🤝 Contributing\n\nIssues and pull requests are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), run the self-test, and explain the problem or use case in the pull request.\n\n## 📄 License\n\n[MIT](LICENSE) © 2026 Roberto Nascimento\n",
  "bytes": 6337,
  "sha": "75a9e9872536194c6e606dd0fcd5a753f80c71ce96df18dc3132f5e8b9f849d7",
  "repo_slug": "roberton003/mcp-server-decisions",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_roberton003_mcp_server_decisio_49a8301f/readme"
}