mcp-server-decisions

⚡ Zero Dependências Externas • Python apenas com stdlib • Armazenamento JSONL somente-acréscimo • Totalmente portátil

---

📌 Principais Recursos

• 🎯 Registro de Decisões — Capture escolhas arquiteturais com declaração do problema, solução, alternativas rejeitadas e tecnologias-alvo.
• 📈 Vínculo de Previsões — Anexe afirmações testáveis (latência, custo, escalabilidade, confiabilidade) ligadas às decisões.
• ✅ Validação de Resultados — Registre resultados medidos e calcule automaticamente pontuações de precisão (escala de 0–100).
• 📊 Registro de Desempenho de Tecnologias — Agregue taxas de sucesso e métricas de confiança por tecnologia ao longo do tempo.
• 🚪 Padrão de Portão de Resultado — Leves lembretes in-band dentro das respostas das ferramentas evitam que os ciclos de feedback de decisões vazem (3.8% → 14.5% de taxa de fechamento).
• ⚡ Zero Dependências — Log JSONL portátil somente-acréscimo. Sem servidores de banco de dados, sem migrações, sem daemons em segundo plano.

---

⚡ Exemplo Rápido

1️⃣ Registre uma Decisão

# Agent or user records a choice:
record-decision(
  problem="Query latency exceeds SLA (p99 > 500ms)",
  chosen_solution="DuckDB + Parquet caching",
  rejected_alternatives=["Redis", "Elasticsearch"],
  technologies=["duckdb", "parquet"],
  predictions=[
    {"prediction_type": "LATENCY", "predicted_value": "p99 < 200ms"},
    {"prediction_type": "COST", "predicted_value": "< $50/month"}
  ]
)
# ➔ Returns: DEC-2026-0001, PRD-2026-0001, PRD-2026-0002

2️⃣ Registre um Resultado

record-outcome(
  prediction_id="PRD-2026-0001",
  actual_value="p99 = 180ms",
  measurement_source="MONITORING",
  accuracy_score=95
)
# ➔ Returns: SUCCESS ✅ (95% accuracy)

3️⃣ Consulte Decisões Anteriores e Estatísticas de Tecnologia

# Search past decisions before choosing a technology:
query-decisions(technology="duckdb", max_results=5)

# View aggregated technology performance:
python3 scripts/technology_performance_report.py
# ➔ Output:
# technology: duckdb  | successful: 12 | failed: 1 | avg_accuracy: 91.2% | confidence: HIGH

---

🚀 Início Rápido e Configuração

📦 Instalação

# From PyPI (once published) or local editable install:
pip install -e .

🛠️ Configuração do Cliente

Adicione à configuração do seu cliente MCP (ex.: Claude Desktop, Claude Code, Cursor, OpenCode):

{
  "mcpServers": {
    "mcp-server-decisions": {
      "type": "stdio",
      "command": "mcp-server-decisions"
    }
  }
}

Para guias de configuração específicos por cliente (Claude, OpenCode, Codex, Antigravity), consulte 📖 docs/INTEGRATIONS.md.

---

Como Funciona

O Ciclo

Decide → Predict → Implement → Measure → Validate → Learn → Next Decision

1. Registre uma decisão — Armazene o problema, a solução escolhida, as alternativas e as tecnologias
2. Faça previsões — Anexe afirmações testáveis (latência, custo, confiabilidade, etc.)
3. Implemente — Construa o sistema
4. Meça os resultados — Capture valores reais de monitoramento, logs e benchmarks
5. Valide — O servidor calcula a precisão (0-100) e o status de validação (SUCCESS / PARTIAL_SUCCESS / FAILED)
6. Aprenda — Revise o que funcionou por meio do Registro de Desempenho de Tecnologias
7. Próxima decisão — Consulte decisões anteriores antes de fazer novas recomendações

O Padrão de Portão de Resultado

Os ciclos de decisão vazam porque as previsões não são validadas. Este servidor incorpora um lembrete diretamente nas respostas das ferramentas:

Sem o Portão de Resultado:

• A decisão é tomada → a implementação começa → os resultados chegam → ninguém verifica se a previsão estava correta

Com o Portão de Resultado:

{
  "decision_id": "DEC-2026-0001",
  "status": "OK",
  "OUTCOME_GATE": "⚠️  2 prediction(s) from this session still lack outcomes: [PRD-2026-0001, PRD-2026-0002]. Record results via record-outcome before ending."
}

O lembrete é in-band (dentro da resposta da ferramenta), onde os agentes já estão olhando. Resultado: melhoria de 3.8% → 14.5% na taxa de fechamento (validado em ferramenta interna).

Exemplo Real: Após registrar uma decisão com 3 previsões, a resposta inclui:

{
  "decision_id": "DEC-2026-0042",
  "prediction_ids": ["PRD-2026-0051", "PRD-2026-0052", "PRD-2026-0053"],
  "status": "OK",
  "OUTCOME_GATE": "⚠️  3 prediction(s) from this session still lack outcomes: [PRD-2026-0051, PRD-2026-0052, PRD-2026-0053]. Record results via record-outcome before ending."
}

A próxima consulta ainda mostra o portão até que todos os 3 resultados sejam registrados. Quando isso acontece, o portão desaparece automaticamente.

Para a explicação completa do padrão, consulte docs/OUTCOME-GATE-PATTERN.md.

🏛️ Arquitetura e Pilha Tecnológica

• Armazenamento: Arquivo JSONL único somente-acréscimo (sem configuração de banco de dados, sem migrações, portátil e amigável ao git).
• IDs: Sequenciais por ano civil (DEC-2026-0001, PRD-2026-0002, OUT-2026-0003).
• Pontuação de Precisão: Classificação automática (≥90 SUCCESS, 50–89 PARTIAL_SUCCESS, <50 FAILED).
• Runtime: Python 3.10+ apenas com stdlib (zero dependências externas de pip em tempo de execução).
• Protocolo: Model Context Protocol (JSON-RPC 2.0 via stdio).

---

⚙️ Variáveis de Ambiente

Variável	Descrição	Caminho Padrão
MCP_DECISIONS_LOG_PATH	Caminho para o arquivo de log JSONL somente-acréscimo	~/.local/share/mcp-decisions/decisions_log.json

---

📚 Documentação e Recursos

Documento	Finalidade
⚡ Início Rápido	Guia de configuração de 5 minutos e primeira decisão
🔌 Integrações de Cliente	Configurações para Claude, OpenCode, Codex, Antigravity
📐 Arquitetura e Design	Fundamentos do design e modelos de dados
💡 Exemplos Detalhados	Payloads reais de requisição/resposta JSON-RPC
🚪 Padrão de Portão de Resultado	Filosofia de design do ciclo de feedback in-band
📖 Wiki	FAQ e tópicos avançados

---

🧪 Desenvolvimento e Testes

Execute testes unitários e autotestes localmente:

python3 server.py --selftest
# ➔ ✅ All self-tests passed

Consulte 📝 CONTRIBUTING.md para contribuir com funcionalidades ou correções.

---

🗺️ Roteiro

• Rastreamento principal de decisão / previsão / resultado
• Lembretes in-band do Portão de Resultado
• Registro de Desempenho de Tecnologias
• Interface web para navegar e pesquisar decisões
• Webhooks / notificações em caso de baixa precisão de previsão
• Modelos de decisão pré-construídos e padrões de domínio

---

📄 Licença e Aviso Legal

MIT © 2026 Roberton003 — Consulte LICENSE.

Este projeto é construído pela comunidade e é independente. Não é afiliado a nenhuma organização ou órgão de padronização.

---