mcp-server-decisions

🧠 MCP 服务：决策

一个开源 MCP 服务，可帮助团队记录架构决策，将其与可测试的预测关联起来，并随着时间推移验证结果。它为 AI Agent 和开发者提供轻量、可审计的技术选择记忆。

✨ 项目亮点

• 关联结果的决策 — 将每项技术选择与可衡量的预测和观察到的结果关联起来。
• 带内结果关卡 — 工具响应会指出仍需验证的预测，之后才能将工作视为完成。
• 可移植存储 — 仅追加的 JSONL 让日志便于检查、备份，且无需设置数据库。
• 零运行时依赖 — 运行此服务只需 Python 标准库。
• 原生 MCP 接口 — 通过 stdio 上的 JSON-RPC 向兼容 MCP 的客户端提供决策跟踪功能。
• 技术反馈 — 汇总经过验证的结果，为未来的技术选择提供参考。

🧰 技术栈

层	技术
协议	基于 JSON-RPC 2.0 的 Model Context Protocol
运行环境	Python 3.10+
存储	仅追加的 JSONL 文件
打包	PyPI / Hatchling
测试	内置自测命令
许可证	MIT

🔄 架构

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]

📌 提供的功能

该服务提供四个工具：

工具	用途
record-decision	存储问题、选定的解决方案、备选方案、技术和预测。
record-prediction	为现有决策添加可衡量的预测。
record-outcome	记录观察到的结果，并将预测归类为成功、部分成功或失败。
query-decisions	按关键词、技术、领域或结果数量上限搜索决策。

示例流程

Decide → Predict → Implement → Measure → Validate → Learn

决策可以生成如下结果关卡提醒：

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

该提醒是工作流信号，并不代表产品已被采用或产生了可衡量的影响。有关设计和权衡，请参阅结果关卡模式。

📊 当前项目状态

领域	状态
决策、预测和结果跟踪	可用
结果关卡提醒	可用
技术性能报告	可用
PyPI 包	已发布，版本为 1.0.2
外部采用指标	尚未收集
Web UI 和通知	规划中

该项目仍处于早期阶段。欢迎贡献、分享真实项目中的示例并提供反馈。

🚀 设置

前提条件

• Python 3.10 或更高版本
• 兼容 MCP 的客户端

从 PyPI 安装

python3 -m pip install mcp-server-decisions

运行自测

python3 -m pip install -e .
python3 server.py --selftest

配置 MCP 客户端

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

有关特定客户端的配置和故障排除，请参阅客户端集成。有关引导式首次运行，请参阅快速入门。

配置日志路径

默认情况下，服务会写入 ~/.local/share/mcp-decisions/decisions_log.json。设置 MCP_DECISIONS_LOG_PATH 可使用其他文件：

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

🗂️ 项目结构

.
├── 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

📚 文档

• 快速入门 — 安装并记录第一个决策。
• 客户端集成 — 配置 MCP 客户端。
• 详细示例 — JSON-RPC 请求与响应。
• 架构与设计 — 存储、ID、评分与权衡。
• 结果门控模式 — 可复用的反馈循环模式。
• 参与贡献 — 提出修复、功能和文档方面的建议。

🛣️ 路线图

• 核心决策、预测和结果跟踪
• 结果门控提醒
• 技术性能报告
• 用于浏览和搜索决策的 Web UI
• 预测准确率低时发送通知
• 可复用的决策模板和领域模式

🤝 参与贡献

欢迎提交问题和拉取请求。请先阅读 CONTRIBUTING.md，运行自测，并在拉取请求中说明问题或使用场景。

📄 许可证

MIT © 2026 Roberto Nascimento