mcp-server-decisions

Rastreamento de decisões com validação de previsões e portões de resultado para agentes de IA

Documentação

🧠 MCP Server: Decisions

Um servidor MCP de código aberto que ajuda equipes a registrar decisões arquiteturais, conectá-las a previsões testáveis e validar resultados ao longo do tempo. Ele oferece a agentes de IA e desenvolvedores uma memória leve e auditável para escolhas técnicas.

Architectural Decision Feedback Loop with Outcome Gates

✨ Destaques do Projeto

Decisões vinculadas a resultados — conecte cada escolha técnica a previsões mensuráveis e resultados observados.
Portões de resultado integrados — respostas das ferramentas identificam previsões que ainda precisam de validação antes que o trabalho seja considerado concluído.
Armazenamento portátil — JSONL somente de acréscimo mantém o registro inspecionável, fácil de fazer backup e sem necessidade de configuração de banco de dados.
Zero dependências em tempo de execução — a biblioteca padrão do Python é suficiente para executar o servidor.
Interface nativa MCP — exponha o rastreamento de decisões via JSON-RPC sobre stdio para clientes compatíveis com MCP.
Feedback de tecnologia — agregue resultados validados para informar futuras escolhas tecnológicas.

🧰 Stack Técnica

Camada	Tecnologia
Protocolo	Model Context Protocol sobre JSON-RPC 2.0
Runtime	Python 3.10+
Armazenamento	Arquivo JSONL somente de acréscimo
Empacotamento	PyPI / Hatchling
Testes	Comando de autoteste integrado
Licença	MIT

🔄 Arquitetura

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]

📌 O Que Ele Oferece

O servidor expõe quatro ferramentas:

Ferramenta	Finalidade
`record-decision`	Armazenar o problema, a solução escolhida, alternativas, tecnologias e previsões.
`record-prediction`	Adicionar uma previsão mensurável a uma decisão existente.
`record-outcome`	Registrar o resultado observado e classificar a previsão como sucesso, sucesso parcial ou falha.
`query-decisions`	Pesquisar decisões por palavra-chave, tecnologia, domínio ou limite de resultados.

Fluxo de exemplo

Decide → Predict → Implement → Measure → Validate → Learn

Uma decisão pode gerar um lembrete de portão de resultado, como:

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

O lembrete é um sinal de fluxo de trabalho, não uma afirmação sobre adoção ou impacto medido. Consulte o Padrão de Portão de Resultado para ver o design e as compensações.

📊 Status Atual do Projeto

Área	Status
Rastreamento de decisões, previsões e resultados	Disponível
Lembretes de portão de resultado	Disponível
Relatório de desempenho de tecnologia	Disponível
Pacote PyPI	Publicado como `1.0.2`
Métricas externas de adoção	Ainda não coletadas
Interface web e notificações	Roadmap

O projeto está em estágio inicial. Contribuições, exemplos de projetos reais e feedback são bem-vindos.

🚀 Configuração

Pré-requisitos

Python 3.10 ou mais recente
Um cliente compatível com MCP

Instalar a partir do PyPI

python3 -m pip install mcp-server-decisions

Executar o autoteste

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

Configurar um cliente MCP

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

Para configuração específica de cliente e solução de problemas, consulte Integrações de Cliente. Para uma primeira execução guiada, consulte Início Rápido.

Configurar o caminho do log

Por padrão, o servidor grava em ~/.local/share/mcp-decisions/decisions_log.json. Defina MCP_DECISIONS_LOG_PATH para usar outro arquivo:

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

🗂️ Estrutura do Projeto

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

📚 Documentação

Início Rápido — instale e registre uma primeira decisão.
Integrações de Cliente — configure clientes MCP.
Exemplos Detalhados — solicitações e respostas JSON-RPC.
Arquitetura e Design — armazenamento, IDs, pontuação e compensações.
Padrão de Portão de Resultado — o padrão reutilizável de ciclo de feedback.
Contribuindo — proponha correções, funcionalidades e documentação.

🛣️ Roadmap

Rastreamento central de decisões, previsões e resultados
Lembretes de portão de resultado
Relatório de desempenho de tecnologia
Interface web para navegar e pesquisar decisões
Notificações para baixa precisão de previsões
Modelos reutilizáveis de decisão e padrões de domínio

🤝 Contribuindo

Issues e pull requests são bem-vindos. Comece com CONTRIBUTING.md, execute o autoteste e explique o problema ou caso de uso no pull request.

mcp-server-decisions

Documentação