mcp-server-decisions

🧠 MCP サーバー：意思決定

チームがアーキテクチャ上の意思決定を記録し、検証可能な予測と結び付け、時間をかけて結果を検証できるようにするオープンソースの MCP サーバーです。AI エージェントや開発者に、技術的な選択のための軽量で監査可能なメモリを提供します。

✨ プロジェクトの主な特長

• 成果に結び付いた意思決定 — 技術的な選択をそれぞれ、測定可能な予測や観測された結果と結び付けます。
• ワークフロー内の成果ゲート — ツールの応答で、作業完了とみなす前に検証が必要な予測を特定します。
• ポータブルなストレージ — 追記専用の 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]

📌 提供機能

サーバーは 4 つのツールを公開します。

ツール	目的
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
• 予測精度が低い場合の通知
• 再利用可能な意思決定テンプレートとドメインパターン

🤝 貢献

Issue とプルリクエストを歓迎します。CONTRIBUTING.mdを確認し、セルフテストを実行したうえで、プルリクエストに問題やユースケースを記載してください。

📄 ライセンス

MIT © 2026 Roberto Nascimento