AI Counsel

Verdadero consenso deliberativo MCP server donde los modelos de IA debaten y refinan posiciones a lo largo de múltiples rondas

GitHub

Prueba este MCPPatrocinado

Documentación

AI Counsel Logo

AI Counsel

Servidor MCP de consenso deliberativo real donde los modelos de IA debaten y refinan posiciones a lo largo de múltiples rondas.

🎬 Véalo en Acción

Debate de Modelos en la Nube (Claude Sonnet, GPT-5.1 Codex, Gemini):

mcp__ai-counsel__deliberate({
  question: "Should we use REST or GraphQL for our new API?",
  participants: [
    {cli: "claude", model: "claude-sonnet-4-5-20250929"},
    {cli: "codex", model: "gpt-5.2-codex"},
    {cli: "gemini", model: "gemini-2.5-pro"}
  ],
  mode: "conference",
  rounds: 3
})

Resultado: Convergencia en arquitectura híbrida (confianza 0.82-0.95) • Ver transcripción completa

Debate de Modelos Locales (100% privado, cero costos de API):

mcp__ai-counsel__deliberate({
  question: "Should we prioritize code quality or delivery speed?",
  participants: [
    {cli: "ollama", model: "llama3.1:8b"},
    {cli: "ollama", model: "mistral:7b"},
    {cli: "ollama", model: "deepseek-r1:8b"}
  ],
  mode: "conference",
  rounds: 2
})

Resultado: 2 modelos cambiaron de posición después del debate de la Ronda 1 • Ver transcripción completa

Qué Lo Hace Diferente

AI Counsel permite un CONSENSO DELIBERATIVO REAL donde los modelos ven las respuestas de los demás y refinan posiciones a lo largo de múltiples rondas:

Los modelos participan en un debate real (se ven y responden entre sí)
Convergencia multi-ronda con votación y niveles de confianza
Registro de auditoría completo con resúmenes generados por IA
Detención temprana automática cuando se alcanza el consenso (ahorra costos de API)

Características

🎯 Dos Modos: quick (una sola ronda) o conference (debate multi-ronda)
🤖 Adaptadores Mixtos: Herramientas CLI (claude, codex, droid, gemini) + servicios HTTP (ollama, lmstudio, openrouter, nebius)
⚡ Auto-Convergencia: Se detiene cuando las opiniones se estabilizan (ahorra costos de API)
🗳️ Votación Estructurada: Los modelos emiten votos con niveles de confianza y justificación
🧮 Agrupación Semántica: Las opciones de voto similares se fusionan automáticamente (similitud 0.70+)
🎛️ Detención Controlada por el Modelo: Los modelos deciden cuándo dejar de deliberar
🔬 Deliberación Basada en Evidencia: Los modelos pueden leer archivos, buscar código, listar archivos y ejecutar comandos para fundamentar decisiones en la realidad
💰 Soporte de Modelos Locales: Cero costos de API con Ollama, LM Studio, llamacpp
🔐 Privacidad de Datos: Mantenga todos los datos en sus instalaciones con modelos autoalojados
🧠 Inyección de Contexto: Encuentra automáticamente debates pasados similares e inyecta contexto para una convergencia más rápida
🔍 Búsqueda Semántica: Consulte decisiones pasadas con la herramienta query_decisions (encuentra contradicciones, rastrea evolución, analiza patrones)
🛡️ Tolerante a Fallos: Las fallas individuales del adaptador no detienen la deliberación
📝 Transcripciones Completas: Exportaciones en Markdown con resúmenes generados por IA

Inicio Rápido

Póngase en marcha en minutos:

Instale – siga los comandos en Instalación para clonar el repositorio, crear un virtualenv e instalar los requisitos.
Configure – configure su cliente MCP usando el ejemplo .mcp.json en Configurar en Claude Code.
Ejecute – inicie el servidor con python server.py y active la herramienta deliberate usando los ejemplos en Uso.

Pruebe una Deliberación:

// Mix local + cloud models, zero API costs for local models
mcp__ai-counsel__deliberate({
  question: "Should we add unit tests to new features?",
  participants: [
    {cli: "ollama", model: "llama2"},           // Local
    {cli: "lmstudio", model: "mistral"},        // Local
    {cli: "claude", model: "sonnet"}            // Cloud
  ],
  mode: "quick"
})

⚠️ El Tamaño del Modelo Importa para las Deliberaciones

Recomendado: Use modelos de 7B-8B+ parámetros (Llama-3-8B, Mistral-7B, Qwen-2.5-7B) para una salida estructurada confiable y formato de votos.

No Recomendado: Los modelos de menos de 3B parámetros (p. ej., Llama-3.2-1B) pueden tener dificultades con instrucciones complejas y producir votos inválidos.

Modelos Disponibles: claude (opus 4.5, sonnet, haiku), codex (gpt-5.2-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5.2), droid, gemini, adaptadores HTTP (ollama, lmstudio, openrouter). Consulte Referencia de Modelos CLI para detalles completos.

🧠 Control del Esfuerzo de Razonamiento

Controle la profundidad del razonamiento por participante para los adaptadores codex y droid:
participants: [
  {cli: "codex", model: "gpt-5.2-codex", reasoning_effort: "high"},    // Razonamiento profundo
  {cli: "droid", model: "gpt-5.1-codex-max", reasoning_effort: "low"}   // Respuesta rápida
]
Codex: none, minimal, low, medium, high, xhigh

Droid: off, low, medium, high

Los valores predeterminados de configuración se establecen en config.yaml, las anulaciones por participante se aplican en tiempo de ejecución

Para opciones de modelos y flujo de trabajo del selector, consulte Registro de Modelos y Selector.

Instalación

Requisitos Previos

Python 3.11+: python3 --version
Al menos una herramienta de IA (opcional - los adaptadores HTTP funcionan sin CLI):
- Claude CLI: https://docs.claude.com/en/docs/claude-code/setup
- Codex CLI: https://github.com/openai/codex
- Droid CLI: https://github.com/Factory-AI/factory
- Gemini CLI: https://github.com/google-gemini/gemini-cli

Configuración

git clone https://github.com/blueman82/ai-counsel.git
cd ai-counsel
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux; Windows: .venv\Scripts\activate
pip install -r requirements.txt
python3 -m pytest tests/unit -v  # Verify installation

✅ ¡Listo para usar! El servidor incluye dependencias principales más backends de convergencia opcionales (scikit-learn, sentence-transformers) para la mejor precisión.

Configuración

Edite config.yaml para configurar adaptadores y ajustes:

adapters:
  claude:
    type: cli
    command: "claude"
    args: ["-p", "--model", "{model}", "--settings", "{\"disableAllHooks\": true}", "{prompt}"]
    timeout: 300

  ollama:
    type: http
    base_url: "http://localhost:11434"
    timeout: 120
    max_retries: 3

defaults:
  mode: "quick"
  rounds: 2
  max_rounds: 5

Nota: Use type: cli para herramientas CLI y type: http para adaptadores HTTP (Ollama, LM Studio, OpenRouter).

Configuración del Registro de Modelos

Controle qué modelos están disponibles para selección en el registro de modelos. Cada modelo puede habilitarse o deshabilitarse sin eliminar su definición:

model_registry:
  claude:
    - id: "claude-sonnet-4-5-20250929"
      label: "Claude Sonnet 4.5"
      tier: "balanced"
      default: true
      enabled: true  # Model is active and available
    - id: "claude-opus-4-20250514"
      label: "Claude Opus 4"
      tier: "premium"
      enabled: false  # Temporarily disabled (cost control, testing, etc.)

Comportamiento del Campo Habilitado:

enabled: true (predeterminado) - El modelo aparece en list_models y puede seleccionarse para deliberaciones
enabled: false - El modelo está oculto de la selección pero se conserva la definición para re-habilitarlo fácilmente
Los modelos deshabilitados no pueden usarse incluso si se especifican explícitamente en llamadas deliberate
La selección de modelo predeterminada omite automáticamente los modelos deshabilitados

Casos de Uso:

Control de Costos: Deshabilite modelos costosos temporalmente sin perder configuración
Pruebas: Habilite/deshabilite modelos específicos durante pruebas de integración
Despliegue por Etapas: Configure nuevos modelos como deshabilitados, habilítelos cuando estén listos
Ajuste de Rendimiento: Deshabilite modelos lentos durante iteración rápida
Cumplimiento: Restrinja temporalmente modelos pendientes de aprobación

Análisis Profundo de Funciones Principales

Detección de Convergencia y Auto-Detención

Los modelos convergen automáticamente y dejan de deliberar cuando las opiniones se estabilizan, ahorrando tiempo y costos de API. Estado: Convergido (≥85% de similitud), Refinando (40-85%), Divergiendo (<40%), o Punto Muerto (desacuerdo estable). La votación tiene prioridad: cuando los modelos emiten votos, la convergencia refleja el resultado de la votación.

→ Guía Completa - Umbrales, backends, configuración

Votación Estructurada

Los modelos emiten votos con niveles de confianza (0.0-1.0), justificación y señales de continuar_debate. Los votos determinan el consenso: Unánime (3-0), Mayoría (2-1) o Empate. Las opciones similares se fusionan automáticamente con un umbral de similitud de 0.70+.

→ Guía Completa - Estructura de votos, ejemplos, integración

Adaptadores HTTP y Modelos Locales

Ejecute Ollama, LM Studio, OpenRouter o Nebius para costos de API flexibles y opciones de privacidad. Mezcle con modelos en la nube (Claude, GPT-4) en una sola deliberación.

→ Guías de Configuración - Ollama, LM Studio, OpenRouter, análisis de costos

Extender AI Counsel

Agregue nuevas herramientas CLI o adaptadores HTTP para adaptarse a su infraestructura. Proceso simple de 3-5 pasos con ejemplos y patrones de prueba.

→ Guía para Desarrolladores - Tutoriales paso a paso, ejemplos del mundo real

Deliberación Basada en Evidencia

Fundamente las decisiones de diseño en la realidad consultando código, archivos y datos reales:

// MCP client example (e.g., Claude Code)
mcp__ai_counsel__deliberate({
  question: "Should we migrate from SQLite to PostgreSQL?",
  participants: [
    {cli: "claude", model: "sonnet"},
    {cli: "codex", model: "gpt-4"}
  ],
  rounds: 3,
  working_directory: process.cwd()  // Required - enables tools to access your files
})

Durante la deliberación, los modelos pueden:

📄 Leer archivos: TOOL_REQUEST: {"name": "read_file", "arguments": {"path": "config.yaml"}}
🔍 Buscar código: TOOL_REQUEST: {"name": "search_code", "arguments": {"pattern": "database.*connect"}}
📋 Listar archivos: TOOL_REQUEST: {"name": "list_files", "arguments": {"pattern": "*.sql"}}
⚙️ Ejecutar comandos: TOOL_REQUEST: {"name": "run_command", "arguments": {"command": "git", "args": ["log", "--oneline"]}}

Flujo de trabajo de ejemplo:

El Modelo A propone PostgreSQL basándose en suposiciones
El Modelo B solicita: read_file para verificar la configuración actual
La herramienta devuelve: database: sqlite, max_connections: 10
El Modelo B busca: search_code consultas de base de datos
La herramienta devuelve: 50+ consultas con JOINs complejos
Los modelos convergen: "PostgreSQL es necesario por la complejidad de consultas y la escala"
Decisión respaldada por evidencia, no por opinión

Beneficios:

Decisiones arraigadas en el estado actual, no en suposiciones
Se aplica a revisiones de código, elecciones de arquitectura, estrategia de pruebas
Registro de auditoría completo de evidencia en transcripciones

Herramientas Soportadas:

read_file - Leer contenido de archivos (máx. 1MB)
search_code - Buscar patrones regex (ripgrep o respaldo en Python)
list_files - Listar archivos que coincidan con patrones glob
run_command - Ejecutar comandos seguros de solo lectura (ls, git, grep, etc.)

Configuración

Controle el comportamiento de las herramientas en config.yaml:

Directorio de Trabajo (Requerido):

Establezca el parámetro working_directory al llamar a la herramienta deliberate
Las herramientas resuelven rutas relativas desde este directorio
Ejemplo: working_directory: process.cwd() en clientes MCP de JavaScript

Seguridad de Herramientas (deliberation.tool_security):

exclude_patterns: Bloquear acceso a directorios sensibles (predeterminado: transcripts/, .git/, node_modules/)
max_file_size_bytes: Límite de tamaño de archivo para read_file (predeterminado: 1MB)
command_whitelist: Comandos seguros para run_command (ls, grep, find, cat, head, tail)

Árbol de Archivos (deliberation.file_tree):

enabled: Inyectar estructura del repositorio en los avisos de la Ronda 1 (predeterminado: true)
max_depth: Límite de profundidad de directorio (predeterminado: 3)
max_files: Número máximo de archivos a incluir (predeterminado: 100)

Requisitos Específicos del Adaptador:

Adaptador	Comportamiento del Directorio de Trabajo	Configuración
Claude	Aislamiento automático mediante subproceso `{working_directory}`	No se necesita configuración especial
Codex	Sin aislamiento real - puede acceder a cualquier archivo	Consideración de seguridad: los modelos pueden leer fuera de `{working_directory}`
Droid	Aislamiento automático mediante subproceso `{working_directory}`	No se necesita configuración especial
Gemini	Aplica límites del espacio de trabajo	Requerido: indicador `--include-directories {working_directory}`
Ollama/LMStudio	N/A - adaptadores HTTP	Sin restricciones de acceso al sistema de archivos

Aprenda Más:

Referencia Completa de Configuración - Todos los ajustes de config.yaml explicados
Aislamiento del Directorio de Trabajo - Cómo manejan las rutas de archivos los adaptadores
Modelo de Seguridad de Herramientas - Listas blancas, límites y exclusiones
Agregar Herramientas Personalizadas - Guía para desarrolladores para extender el sistema de herramientas

Solución de Problemas

Errores de "Archivo no encontrado":

Asegúrese de que working_directory esté configurado correctamente en su llamada al cliente MCP
Use el patrón de descubrimiento: list_files → read_file
Verifique que las rutas de archivos sean relativas al directorio de trabajo

Errores de "Acceso denegado: La ruta coincide con el patrón de exclusión":

Las herramientas bloquean transcripts/, .git/, node_modules/ de forma predeterminada
Personalice mediante deliberation.tool_security.exclude_patterns en config.yaml

Errores de Gemini "La ruta del archivo debe estar dentro del espacio de trabajo":

Verifique que el indicador --include-directories de Gemini use el marcador de posición {working_directory}
Consulte la configuración específica del adaptador arriba

Errores de tiempo de espera de herramientas:

Aumente deliberation.tool_security.tool_timeout para operaciones lentas
Predeterminado: 10 segundos para operaciones de archivos, 30 segundos para comandos

Aprenda Más:

Agregar Herramientas Personalizadas - Guía para desarrolladores para extender el sistema de herramientas
Arquitectura y Seguridad - Cómo funcionan las herramientas internamente
Errores Comunes - Ajustes avanzados y problemas conocidos

Memoria de Grafo de Decisiones

AI Counsel aprende de deliberaciones pasadas para acelerar decisiones futuras. Dos capacidades principales:

1. Inyección Automática de Contexto

Al iniciar una nueva deliberación, el sistema:

Busca en debates pasados preguntas similares (similitud semántica)
Encuentra las top-k decisiones más relevantes (configurable, predeterminado: 3)
Inyecta contexto en los avisos de la Ronda 1 automáticamente
Resultado: Los modelos comienzan con conocimiento institucional, convergen más rápido

2. Búsqueda Semántica con `query_decisions`

Consulte deliberaciones pasadas programáticamente:

Buscar similares: Encuentre decisiones relacionadas con una pregunta
Encontrar contradicciones: Detecte decisiones pasadas conflictivas
Rastrear evolución: Vea cómo cambiaron las opiniones con el tiempo
Analizar patrones: Identifique temas recurrentes

Configuración (opcional - los valores predeterminados funcionan de inmediato):

decision_graph:
  enabled: true                       # Auto-injection on by default
  db_path: "decision_graph.db"        # Resolves to project root (works for any user/folder)
  similarity_threshold: 0.6           # Adjust to control context relevance
  max_context_decisions: 3            # How many past decisions to inject

Funciona para cualquier usuario desde cualquier directorio - la ruta de la base de datos se resuelve relativa a la raíz del proyecto.

→ Inicio rápido | Configuración | Inyección de contexto

Uso

Iniciar el servidor

python server.py

Configurar en Claude Code

Opción A: Configuración del proyecto (Recomendada) - Crea .mcp.json:

{
  "mcpServers": {
    "ai-counsel": {
      "type": "stdio",
      "command": ".venv/bin/python",
      "args": ["server.py"],
      "env": {}
    }
  }
}

Opción B: Configuración de usuario - Añade a ~/.claude.json con rutas absolutas.

Después de la configuración, reinicia Claude Code.

Selección de modelo y valores predeterminados de sesión

Descubre los modelos permitidos para cada adaptador ejecutando la herramienta MCP list_models.
Establece los valores predeterminados por sesión con set_session_models; deja model en blanco en deliberate para usar esos valores predeterminados.
Las instrucciones completas y ejemplos de solicitudes se encuentran en Registro de modelos y selector.

Ejemplos

Modo rápido:

mcp__ai-counsel__deliberate({
  question: "Should we migrate to TypeScript?",
  participants: [{cli: "claude", model: "sonnet"}, {cli: "codex", model: "gpt-5.2-codex"}],
  mode: "quick"
})

Modo conferencia (multironda):

mcp__ai-counsel__deliberate({
  question: "JWT vs session-based auth?",
  participants: [
    {cli: "claude", model: "sonnet"},
    {cli: "codex", model: "gpt-5.2-codex"}
  ],
  rounds: 3,
  mode: "conference"
})

Buscar decisiones anteriores:

mcp__ai-counsel__query_decisions({
  query_text: "database choice",
  threshold: 0.5,  // NEW! Adjust sensitivity (0.0-1.0, default 0.6)
  limit: 5
})
// Returns: Similar past deliberations with consensus and similarity scores

// NEW! Empty results include helpful diagnostics:
{
  "type": "similar_decisions",
  "count": 0,
  "results": [],
  "diagnostics": {
    "total_decisions": 125,
    "best_match_score": 0.45,
    "near_misses": [{"question": "Database indexing...", "score": 0.45}],
    "suggested_threshold": 0.45,
    "message": "No results found above threshold 0.6. Best match scored 0.450. Try threshold=0.45..."
  }
}

// Find contradictions
mcp__ai-counsel__query_decisions({
  operation: "find_contradictions"
})
// Returns: Decisions where consensus conflicts

// Trace evolution
mcp__ai-counsel__query_decisions({
  query: "microservices architecture",
  operation: "trace_evolution"
})
// Returns: How opinions evolved over time on this topic

Transcripciones

Todas las deliberaciones se guardan en transcripts/ con resúmenes generados por IA y el historial completo del debate.

Arquitectura

ai-counsel/
├── server.py                # MCP server entry point
├── config.yaml              # Configuration
├── adapters/                # CLI/HTTP adapters
│   ├── base.py             # Abstract base
│   ├── base_http.py        # HTTP base
│   └── [adapter implementations]
├── deliberation/            # Core engine
│   ├── engine.py           # Orchestration
│   ├── convergence.py      # Similarity detection
│   └── transcript.py       # Markdown generation
├── models/                  # Data models (Pydantic)
├── tests/                   # Unit/integration/e2e tests
└── decision_graph/         # Optional memory system

Centro de documentación

Primeros pasos

Inicio rápido - Configuración en 5 minutos
Instalación - Requisitos previos y configuración detallados
Ejemplos de uso - Modos rápido y conferencia

Conceptos principales

Detección de convergencia - Detención automática, umbrales, backends
Votación estructurada - Estructura de votación, tipos de consenso, agrupación de votos
Deliberación basada en evidencia - Fundamenta decisiones en la realidad con read_file, search_code, list_files, run_command
Memoria de grafo de decisiones - Aprendizaje de decisiones pasadas

Configuración y ajustes

Adaptadores HTTP - Configuración de Ollama, LM Studio, OpenRouter
Referencia de configuración - Todas las opciones de YAML
Guía de migración - De cli_tools a adaptadores

Desarrollo

Añadir adaptadores - Desarrollo de adaptadores CLI y HTTP
CLAUDE.md - Arquitectura, flujo de trabajo de desarrollo, gotchas
Registro de modelos y selector - Gestión de modelos permitidos y herramientas de selección MCP

Referencia

Solución de problemas - Problemas con adaptadores HTTP
Documentación del grafo de decisiones - Funciones avanzadas de memoria

Desarrollo

Ejecutar pruebas

pytest tests/unit -v                    # Unit tests (fast)
pytest tests/integration -v -m integration  # Integration tests
pytest --cov=. --cov-report=html       # Coverage report

Consulta CLAUDE.md para el flujo de trabajo de desarrollo y notas de arquitectura.

Contribuciones

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/your-feature)
Escribe las pruebas primero (flujo de trabajo TDD)
Implementa la característica
Asegúrate de que todas las pruebas pasen
Envía un PR con una descripción clara

Licencia

Licencia MIT - consulta el archivo LICENSE

Créditos

Construido con:

MCP SDK - Model Context Protocol
Pydantic - Validación de datos
pytest - Marco de pruebas

Inspirado por la necesidad de un verdadero consenso deliberativo de IA más allá de la recopilación paralela de opiniones.

Estado

GitHub stars GitHub forks GitHub last commit

Listo para producción - Consenso deliberativo multimodelo con memoria de grafo de decisiones entre usuarios, votación estructurada y detención temprana adaptativa para decisiones técnicas críticas!

AI Counsel

Documentación

AI Counsel

🎬 Véalo en Acción

Qué Lo Hace Diferente

Características

Inicio Rápido

Instalación

Requisitos Previos

Configuración

Configuración

Configuración del Registro de Modelos

Análisis Profundo de Funciones Principales

Detección de Convergencia y Auto-Detención

Votación Estructurada

Adaptadores HTTP y Modelos Locales

Extender AI Counsel

Deliberación Basada en Evidencia

Configuración

Solución de Problemas

Memoria de Grafo de Decisiones

1. Inyección Automática de Contexto

2. Búsqueda Semántica con query_decisions

Uso

Iniciar el servidor

Configurar en Claude Code

Selección de modelo y valores predeterminados de sesión

Ejemplos

Transcripciones

Arquitectura

Centro de documentación

Primeros pasos

Conceptos principales

Configuración y ajustes

Desarrollo

Referencia

Desarrollo

Ejecutar pruebas

Contribuciones

Licencia

Créditos

Estado

2. Búsqueda Semántica con `query_decisions`