mcp-server-decisions

🧠 Servidor MCP: Decisions

Un servidor MCP de código abierto que ayuda a los equipos a registrar decisiones arquitectónicas, conectarlas con predicciones comprobables y validar resultados con el tiempo. Proporciona a los agentes de IA y a los desarrolladores una memoria ligera y auditable para las decisiones técnicas.

✨ Aspectos destacados del proyecto

• Decisiones vinculadas a resultados — conecta cada decisión técnica con predicciones medibles y resultados observados.
• Puertas de resultados en banda — las respuestas de las herramientas identifican predicciones que aún necesitan validación antes de considerar el trabajo completo.
• Almacenamiento portátil — el registro JSONL de solo añadidura mantiene el log inspeccionable, fácil de respaldar y sin necesidad de configurar una base de datos.
• Cero dependencias en tiempo de ejecución — la biblioteca estándar de Python es suficiente para ejecutar el servidor.
• Interfaz nativa MCP — expone el seguimiento de decisiones mediante JSON-RPC sobre stdio a clientes compatibles con MCP.
• Retroalimentación tecnológica — agrega resultados validados para informar futuras decisiones tecnológicas.

🧰 Stack técnico

Capa	Tecnología
Protocolo	Model Context Protocol sobre JSON-RPC 2.0
Tiempo de ejecución	Python 3.10+
Almacenamiento	Archivo JSONL de solo añadidura
Empaquetado	PyPI / Hatchling
Pruebas	Comando de autocomprobación integrado
Licencia	MIT

🔄 Arquitectura

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]

📌 Qué proporciona

El servidor expone cuatro herramientas:

Herramienta	Propósito
record-decision	Almacena el problema, la solución elegida, las alternativas, las tecnologías y las predicciones.
record-prediction	Añade una predicción medible a una decisión existente.
record-outcome	Registra el resultado observado y clasifica la predicción como éxito, éxito parcial o fracaso.
query-decisions	Busca decisiones por palabra clave, tecnología, dominio o límite de resultados.

Flujo de ejemplo

Decide → Predict → Implement → Measure → Validate → Learn

Una decisión puede generar un recordatorio de puerta de resultados como:

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

El recordatorio es una señal de flujo de trabajo, no una afirmación sobre adopción o impacto medido. Consulta el Patrón de puerta de resultados para conocer el diseño y las compensaciones.

📊 Estado actual del proyecto

Área	Estado
Seguimiento de decisiones, predicciones y resultados	Disponible
Recordatorios de puerta de resultados	Disponible
Informe de rendimiento tecnológico	Disponible
Paquete PyPI	Publicado como 1.0.2
Métricas de adopción externa	Aún no recopiladas
Interfaz web y notificaciones	Hoja de ruta

El proyecto está en una etapa temprana. Las contribuciones, los ejemplos de proyectos reales y los comentarios son bienvenidos.

🚀 Configuración

Requisitos previos

• Python 3.10 o más reciente
• Un cliente compatible con MCP

Instalar desde PyPI

python3 -m pip install mcp-server-decisions

Ejecutar la autocomprobación

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

Configurar un cliente MCP

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

Para la configuración específica del cliente y la resolución de problemas, consulta Integraciones de clientes. Para una primera ejecución guiada, consulta Inicio rápido.

Configurar la ruta del log

De forma predeterminada, el servidor escribe en ~/.local/share/mcp-decisions/decisions_log.json. Establece MCP_DECISIONS_LOG_PATH para usar otro archivo:

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

🗂️ Estructura del proyecto

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

📚 Documentación

• Inicio rápido — instala y registra una primera decisión.
• Integraciones de clientes — configura clientes MCP.
• Ejemplos detallados — solicitudes y respuestas JSON-RPC.
• Arquitectura y diseño — almacenamiento, IDs, puntuación y compensaciones.
• Patrón de puerta de resultados — el patrón reutilizable de bucle de retroalimentación.
• Contribuciones — propón correcciones, funciones y documentación.

🛣️ Hoja de ruta

• Seguimiento central de decisiones, predicciones y resultados
• Recordatorios de puerta de resultados
• Informes de rendimiento tecnológico
• Interfaz web para explorar y buscar decisiones
• Notificaciones para baja precisión de predicciones
• Plantillas de decisión reutilizables y patrones de dominio

🤝 Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas. Comienza con CONTRIBUTING.md, ejecuta la autocomprobación y explica el problema o caso de uso en la solicitud de extracción.

📄 Licencia

MIT © 2026 Roberto Nascimento