MCP-NixOS: Porque tu asistente de IA no debería alucinar con los paquetes

⚠️ DESARROLLO ACTIVO : Este paquete está en desarrollo. Al igual que mis opciones profesionales, está en constante evolución.

📢 RENOMBRADO : Este paquete cambió su nombre de nixmcp a mcp-nixos en la versión 0.2.0. Actualice sus referencias según corresponda o continúe en el pasado; usted decide.

¿Qué diablos es esta cosa?

MCP-NixOS es un servidor de Protocolo de Contexto de Modelo que impide que tu asistente de IA invente cosas sobre NixOS. Porque, seamos sinceros, lo único peor que confundir la documentación de NixOS es que una IA alucine con ella.

Proporciona acceso en tiempo real a:

• Paquetes de NixOS (sí, los que realmente existen)
• Opciones del sistema (las que pasarás horas configurando)
• Configuración del Home Manager (para cuando el caos en todo el sistema no es suficiente)
• Configuraciones de macOS nix-darwin (porque los usuarios de Apple también necesitan complejidad)

Inicio rápido: para los impacientes crónicos

Mira, ambos sabemos que solo vas a hojear este README y luego quejarte cuando algo no funcione. Aquí tienes lo mínimo para empezar:

Listo. Ahora tu asistente de IA puede darte información correcta sobre NixOS en lugar de alucinar con nombres de paquetes de 2019. De nada.

Variables de entorno (para fanáticos del control)

*Ubicaciones de caché predeterminadas (donde sus gigabytes desaparecerán silenciosamente):

• Linux: ~/.cache/mcp_nixos/ (porque ~/.cache no estaba lo suficientemente desordenado)
• macOS: ~/Library/Caches/mcp_nixos/ (enterrado donde nunca mirarás)
• Windows: %LOCALAPPDATA%\mcp_nixos\Cache\ (perdido en el vacío de los directorios de Windows)

Características que realmente podrían funcionar

• Recursos de NixOS : Paquetes y opciones del sistema a través de la API de Elasticsearch
  • Múltiples canales: inestable (para los valientes), estable (para los aburridos) y versiones específicas.
  • Metadatos detallados del paquete que le indican todo excepto cómo hacerlo funcionar
• Home Manager : Opciones de configuración del usuario a través de documentación analizada
  • Programas, servicios y configuraciones que pasarás los fines de semana configurando
  • Rutas jerárquicas para cuando quieres ser absurdamente específico
• nix-darwin : configuración de macOS para los usuarios de Apple que usan NixOS.
  • Valores predeterminados del sistema, servicios y configuraciones. Apple nunca tuvo la intención de que los tocara.
  • ¡Rompe tu Mac de formas nuevas y emocionantes!
• Almacenamiento en caché inteligente : porque nadie quiere esperar las consultas de Elasticsearch
  • Reduce las solicitudes de red y mejora el tiempo de inicio.
  • Funciona sin conexión una vez almacenado en caché (perfecto para la próxima interrupción de Internet)
• Búsqueda enriquecida : encuentre lo que necesita o algo lo suficientemente parecido
  • Un motor de búsqueda rápido en memoria que sorprendentemente no es terrible
  • Opciones relacionadas para cuando no estás muy seguro de lo que estás buscando

Recursos y herramientas de MCP: Las herramientas eléctricas que no sabías que necesitabas

NixOS: El sistema operativo que te hace sentir más inteligente y más tonto al mismo tiempo

Recursos:

• nixos://package/{name} - Encuentra el paquete que estás seguro que existe
• nixos://search/packages/{query} - Busca paquetes que puedan existir
• nixos://search/options/{query} - Opciones del sistema de búsqueda que configurarás incorrectamente
• nixos://option/{name} - Obtén información sobre las opciones que aún puedes arruinar
• nixos://search/programs/{name} - Encuentra paquetes que ofrecen programas
• nixos://packages/stats - Estadísticas para impresionar a tus amigos nerds

Herramientas:

• nixos_search(query, type, channel) : la función de búsqueda que usarás con más frecuencia
• nixos_info(name, type, channel) - Obtener detalles del paquete o la opción
• nixos_stats(channel) - Obtenga estadísticas de NixOS que nadie solicitó

Canales:

• unstable (predeterminado) - Vivir al límite, donde nada es estable, incluida tu cordura.
• stable (24.11) - Para aquellos que prefieren su descanso en un horario
• Versiones antiguas: para cuando sientes nostalgia por fracasos pasados

Home Manager: Porque la configuración de todo el sistema no era lo suficientemente complicada

Recursos:

• home-manager://search/options/{query} - Buscar opciones de configuración del usuario
• home-manager://option/{name} - Detalles de la opción que capturarás en pantalla para más adelante
• home-manager://options/prefix/{prefix} - Todas las opciones bajo un prefijo
• home-manager://options/{category} - Opciones de categoría (programas, servicios, etc.)

Herramientas:

• home_manager_search(query) - Opciones de configuración de búsqueda
• home_manager_info(name) : obtiene los detalles de la opción con una explicación real
• home_manager_options_by_prefix(option_prefix) - Obtener opciones por prefijo
• home_manager_list_options() - Listar todas las categorías de opciones cuando esté sobrecargado

nix-darwin: Para usuarios de Mac que anhelan el dolor

Recursos:

• darwin://search/options/{query} - Buscar opciones de macOS
• darwin://option/{name} - Detalles de las opciones para sus dispositivos Apple
• darwin://options/prefix/{prefix} - Todas las opciones bajo un prefijo
• darwin://options/{category} - Opciones de categoría (sistema, servicios, etc.)

Herramientas:

• darwin_search(query) - Buscar opciones de configuración de macOS
• darwin_info(name) : obtiene los detalles de las opciones que Apple no quiere que usted sepa
• darwin_options_by_prefix(option_prefix) - Obtener opciones por prefijo
• darwin_list_options() - Lista todas las categorías de opciones

Ejemplos de uso de herramientas (compatibles con copiar y pegar)

Instalación y configuración: la parte que probablemente omitirás

Instálalo (Elige tu veneno)

Configúralo (La parte que seguro arruinarás)

Agregue a su archivo de configuración de MCP (por ejemplo, ~/.config/claude/config.json ):

Para el desarrollo con el código fuente (para aquellos que disfrutan del castigo):

Caché y canales: donde ocurre la magia y desaparecen los archivos

Sistema de caché:

• Ubicaciones predeterminadas que olvidarás en 5 minutos
• Almacena contenido HTML, datos serializados e índices de búsqueda.
• Funciona sin conexión una vez almacenado en caché (la única característica que realmente apreciarás)

Canales de NixOS:

• unstable : Último NixOS inestable (para temerarios)
• stable : Versión estable actual (para quienes son reacios al riesgo)
• 24.11 : Referencia de versión específica (para los con inclinación histórica)

Desarrollo: Para aquellos que no se conforman con solo usar cosas

Dependencias (porque ya nada se sostiene solo)

Este proyecto usa pyproject.toml porque no somos animales.

Usando Nix (Por supuesto que existe un entorno de desarrollo Nix)

Pruebas (Sí, realmente lo hacemos)

Las pruebas utilizan llamadas API de Elasticsearch reales en lugar de simulaciones porque no tememos al mundo real:

La cobertura del código se rastrea en Codecov (donde pretendemos preocuparnos por una cobertura del 100%).

Uso con LLM: el objetivo principal de este ejercicio

Una vez configurado, utilice MCP-NixOS en sus indicaciones con modelos compatibles con MCP:

El LLM obtendrá información a través del servidor MCP y es posible que, en algún momento, le brinde información correcta.

Detalles de implementación: El castillo de naipes revelado

Arquitectura de código: cómo lo logramos (de alguna manera)

MCP-NixOS está organizado en una estructura modular que de alguna manera logra funcionar a pesar de todas las dificultades:

• mcp_nixos/cache/ - Componentes de almacenamiento en caché que ahorran ancho de banda y tranquilidad
• mcp_nixos/clients/ - Clientes API que se comunican con Elasticsearch y analizan documentos HTML
• mcp_nixos/contexts/ - Objetos de contexto que evitan que todo se desmorone
• mcp_nixos/resources/ - Definiciones de recursos de MCP para todas las plataformas
• mcp_nixos/tools/ - Implementaciones de herramientas MCP que hacen el trabajo real
• mcp_nixos/utils/ - Funciones de utilidad porque no somos animales
• mcp_nixos/server.py - El pegamento que mantiene unido este castillo de naipes

Integración de la API de NixOS: la conexión externa

Se conecta a la API Elasticsearch de NixOS con:

• Soporte para múltiples canales (inestable, estable/24.11)
• La búsqueda específica de campo mejora la relevancia
• Manejo de errores que espera lo peor pero espera lo mejor (la historia de mi vida)

Analizadores de documentación HTML: donde los sueños van a morir

En el caso de las opciones Home Manager y nix-darwin, hemos cometido delitos contra el análisis de HTML:

1. Analizadores de documentación : extrae datos estructurados mediante una combinación de encantamientos de BeautifulSoup, magia negra de expresiones regulares y el tipo de determinación que solo se logra al mirar HTML malformado durante 72 horas seguidas.
2. Motores de búsqueda : Combinados con:
   • Índice invertido para búsqueda rápida de texto (cuando no se cae)
   • Árbol de prefijos para búsquedas jerárquicas (parecía una buena idea a las 3 a. m.)
   • Puntuación de resultados basada en un algoritmo que se describe mejor como "clasificación basada en vibraciones".
3. Sistema de almacenamiento en caché : porque analizar ese HTML una vez fue bastante traumático:
   • Almacena contenido HTML, estructuras de datos procesadas e índices de búsqueda.
   • Utiliza ubicaciones de caché específicas de la plataforma para que no tengas que pensar en ello
   • Implementa la expiración basada en TTL para actualizar el contenido cuando sea necesario
   • Retrocede con gracia cuando las cosas inevitablemente salen mal (a diferencia de mis relaciones)

¿Qué es el Protocolo de Contexto Modelo?

Para aquellos que saltaron directamente al final

El Protocolo de Contexto de Modelo (MCP) es un protocolo abierto que conecta los LLM con datos y herramientas externas mediante mensajes JSON a través de la entrada estándar (stdin) y la salida estándar (stdout). Este proyecto implementa MCP para que los asistentes de IA accedan a los recursos de NixOS, Home Manager y nix-darwin, para que finalmente puedan dejar de inventar información sobre el sistema operativo.

Licencia

MIT (Porque no soy un monstruo)

El logotipo del copo de nieve de NixOS se utiliza con atribución al proyecto NixOS. Consulte la información de atribución para obtener más información.

Creado por James Brink, autoproclamado Tinkerer of Terror, quien de alguna manera logra hacer que las cosas funcionen a pesar de sí mismo.