model-advisor-mcp

<p align="center"> <a href="README.en.md">English version</a> · <a href="guia_gentle_ai.md">Criterios de selección (guía)</a> </p>

📢 Aporte comunitario — Las recomendaciones de este MCP están diseñadas para los agentes del harness Gentle AI. Este es un proyecto independiente creado para ayudar a la comunidad a elegir los mejores modelos para cada agente. No está afiliado oficialmente con Gentle AI ni con OpenCode.

Servidor MCP que ayuda a los LLMs a elegir el mejor modelo de IA para cada agente de coding. Obtiene datos en tiempo real de tus suscripciones OpenCode y los cruza con benchmarks y capacidades de razonamiento de OpenRouter.

⚠️ Aviso: El paquete aún no está publicado en npm. La instalación solo está disponible clonando el repositorio (ver Opción B: Manual). El soporte para npm install -g model-advisor-mcp llegará próximamente.

Qué hace

• Lista todos los modelos disponibles en tu suscripción OpenCode Go y/o Zen
• Los enriquece con benchmarks de OpenRouter (inteligencia, coding, agentic), precios y ventana de contexto
• Muestra el soporte de razonamiento — si el modelo tiene niveles explícitos (xhigh, high, low) o solo un toggle on/off
• Lee los criterios de selección de la guía Gentle AI para que el LLM sepa qué necesita cada agente antes de elegir modelo
• Recomienda modelos por agente basándose en datos reales, no en suposiciones

Instalación

Opción A: npm (recomendado)

npm install -g model-advisor-mcp

Luego, configúralo en OpenCode (consulta Configuración).

Opción B: Manual (desarrollo)

git clone https://github.com/AlonsoSG0/model-advisor-mcp.git
cd model-advisor-mcp
pnpm install
pnpm build

Requisitos

• Node.js 18+
• API key de OpenCode — obténla en opencode.ai (requerida)
• API key de OpenRouter — obténla en openrouter.ai/keys (opcional; el catálogo público funciona sin ella)

Configuración

Antes de configurar OpenCode, asegurate de que tu API key de OpenCode esté disponible como variable de entorno en tu shell. Agregala a tu ~/.zshrc, ~/.bashrc o perfil equivalente:

export OPENCODE_API_KEY="sk-tu-api-key"

Luego de agregarla, reiniciá tu terminal o ejecutá source ~/.zshrc para que la variable esté disponible.

Nota: OPENROUTER_API_KEY es opcional. Si querés usarla, agregala de la misma forma: export OPENROUTER_API_KEY="sk-tu-key".

Agrega lo siguiente a tu opencode.json o opencode.jsonc:

{
  "mcp": {
    "model-advisor": {
      "type": "local",
      "command": [
        "node",
        "/ruta/a/model-advisor-mcp/dist/server.js"
      ],
      "cwd": "/ruta/a/model-advisor-mcp",
      "enabled": true,
      "timeout": 30000,
      "environment": {
        "OPENCODE_API_KEY": "{env:OPENCODE_API_KEY}",
        "OPENROUTER_API_KEY": "{env:OPENROUTER_API_KEY}"
      }
    }
  }
}

Si instalaste vía npm (npm install -g model-advisor-mcp):

{
  "mcp": {
    "model-advisor": {
      "type": "local",
      "command": ["model-advisor-mcp"],
      "enabled": true,
      "timeout": 30000,
      "environment": {
        "OPENCODE_API_KEY": "{env:OPENCODE_API_KEY}"
      }
    }
  }
}

Nota: OPENROUTER_API_KEY es opcional. El servidor consulta el catálogo público sin credenciales; si defines la clave, la envía como autenticación en las solicitudes de enriquecimiento.

Inicio rápido y ejemplos

Después de instalar y configurar el MCP:

1. Verifica en la terminal que el ejecutable instalado globalmente esté disponible:

   command -v model-advisor-mcp
   

   El comando debe devolver la ruta del ejecutable. Si hiciste una instalación manual, este paso no aplica: OpenCode usa la ruta a dist/server.js configurada arriba.

2. Reinicia OpenCode para que cargue la configuración y verifica el estado de la conexión:

   opencode mcp list
   

   model-advisor debe aparecer conectado.

3. Envía uno de estos prompts a tu agente u orquestador de IA. No son comandos de terminal:

   Usando el MCP model-advisor, dime qué modelos hay disponibles en las suscripciones OpenCode Go y Zen.

   Usando el MCP model-advisor, dame una recomendación low cost usando solamente modelos de OpenCode Go.

Si el agente puede listar modelos o generar una recomendación usando datos del MCP, la conexión funciona correctamente.

Herramientas

list_available_models

Obtiene todos los modelos de IA de tus suscripciones OpenCode (Go y/o Zen), enriquecidos con OpenRouter.

Parámetros:

Parámetro	Tipo	Default	Descripción
subscription	"go" | "zen" | "both"	"both"	Qué suscripción consultar
enrich	boolean	true	Poner false para omitir OpenRouter (más rápido)

Devuelve por cada modelo:

Campo	Descripción
ocId / ocName / ocProvider	Identidad del modelo
pricing	Costo input/output por 1M tokens (USD)
contextLength	Ventana de contexto máxima en tokens
benchmarks	Puntajes de inteligencia, coding y agentic (Artificial Analysis)
reasoning	Niveles de esfuerzo disponibles (supportedEfforts) y defaults
subscription	A qué suscripción(es) pertenece el modelo

Ejemplo de reasoning:

// Modelo con niveles de esfuerzo explícitos
"reasoning": {
  "supportedEfforts": ["xhigh", "high"],
  "defaultEffort": "high",
  "mandatory": false,
  "defaultEnabled": true
}

// Modelo con toggle on/off
"reasoning": {
  "supportedEfforts": [],
  "defaultEffort": null,
  "mandatory": false,
  "defaultEnabled": true
}

// Modelo sin razonamiento
"reasoning": null

get_agent_criteria

Lee los criterios de selección de agentes de la guía Gentle AI. Usa esta herramienta antes de elegir modelo: cada agente tiene necesidades específicas (contexto, razonamiento, velocidad y costo).

Parámetros:

Parámetro	Tipo	Default	Descripción
agent	string	(guía completa)	ID del agente a filtrar. Omitir para obtener todos.

IDs de agentes: gentle-orchestrator, sdd-init, sdd-onboard, sdd-explore, sdd-propose, sdd-spec, sdd-design, sdd-tasks, sdd-apply, sdd-verify, sdd-archive, review-risk, review-readability, review-reliability, review-resilience, review-refuter, jd-judge-a, jd-judge-b, jd-fix-agent

Grupos de agentes (mostrar recomendaciones en este orden):

1. Orchestrator
2. Agentes SDD
3. Review (4R)
4. Judgment Day

get_model_benchmarks

Búsqueda detallada de un modelo específico en OpenRouter. Útil cuando list_available_models no trajo benchmarks para un modelo.

Parámetros:

Parámetro	Tipo	Descripción
query	string (requerido)	ID o nombre del modelo (ej. "deepseek-v4-pro", "kimi")

Cómo usa el LLM estas herramientas

El flujo típico:

1. list_available_models → ve qué hay disponible, sus benchmarks y soporte de razonamiento
2. get_agent_criteria (por agente) → entiende qué necesita cada agente
3. get_model_benchmarks (opcional) → datos más profundos de un modelo específico
4. El LLM razona → empareja modelos con agentes según criterios + benchmarks + costo

Desarrollo

# Instalar dependencias
pnpm install

# Compilar TypeScript
pnpm build

# Ejecutar directo (para pruebas)
pnpm start

# Modo watch (recarga automática)
pnpm dev