mcp-nixos

Executes package searches across 6 distinct NixOS ecosystem data sources (nixos, home-manager, darwin, flakes, flakehub, nixvim) through a single consolidated 'search' action on the nix() tool. Internally routes queries to Elasticsearch for nixos/home-manager/darwin packages, FlakeHub API for flake discovery, and NixHub.io for nixvim programs, aggregating results into a unified response format that prevents LLM hallucination of non-existent package names.

Implements a hierarchical options action that traverses configuration option trees for home-manager, nix-darwin, and nixvim by parsing HTML documentation and building in-memory option hierarchies. Supports drilling down from top-level option categories (e.g., 'programs.neovim') to leaf options with type information, defaults, and descriptions, enabling LLMs to explore configuration spaces without hallucinating invalid option paths.

Integrates with NixHub.io to search Nixvim plugins and retrieve plugin metadata. Implements NixvimCache class (lines 159-199 in server.py) that handles paginated loading of Nixvim options (50 results per page) to manage memory and API load. The search action queries NixHub for plugins, and the options action traverses Nixvim option hierarchies with pagination support.

Parses HTML documentation from NixHub.io and other sources to extract hierarchical option information (option paths, types, defaults, descriptions) for home-manager, nix-darwin, and nixvim. Implements custom HTML parsing logic that builds in-memory option trees from documentation, enabling the options action to traverse hierarchies without requiring API calls for each option.

Implements ChannelCache and NixvimCache classes that cache query results in memory with time-based invalidation (default 1 hour). Caching reduces latency for repeated queries and API load on upstream sources, while time-based invalidation ensures eventual freshness. Cache keys are based on query parameters, enabling efficient cache hits for identical queries.

Implements comprehensive error handling that catches API failures, parsing errors, and invalid parameters, returning structured error responses with source attribution and fallback suggestions. Response formatting standardizes output across all sources, including metadata about which source provided the result, enabling users to understand result provenance and trust level.

Dedicated nix_versions() tool that queries package version history across NixOS channels (unstable, stable, 23.11, 24.05, etc.) by integrating with FlakeHub API and channel resolution system. Returns version timelines, availability across channels, and deprecation status, enabling users to understand package evolution and select appropriate channel versions for reproducible builds.

Info action on the nix() tool retrieves comprehensive package metadata (maintainers, licenses, dependencies, source URLs, descriptions) from nixos, home-manager, darwin, flakehub, and nixvim sources. Queries Elasticsearch indices and FlakeHub API to surface authoritative package information with source attribution, enabling LLMs to provide users with complete context about package provenance and maintenance status.

Stats action on the nix() tool aggregates ecosystem statistics (package counts, maintainer counts, update frequency) across nixos, home-manager, darwin, flakes, and flakehub sources by querying Elasticsearch aggregation endpoints and FlakeHub API. Returns time-series data and comparative metrics that enable users to understand ecosystem health and package distribution patterns.

Channels action on the nix() tool dynamically discovers available NixOS channels at runtime using the ChannelCache class, which queries official NixOS channel sources and caches results. Returns a list of available channels (unstable, stable, 23.11, 24.05, etc.) with metadata, enabling users to understand channel options without hardcoding channel lists.

Implements a FastMCP server instance that handles Model Context Protocol communication via stdio/JSON-RPC, translating MCP tool calls into internal function invocations and serializing responses back to JSON. Manages the full MCP lifecycle including tool registration, parameter validation, error handling, and response formatting, enabling seamless integration with MCP clients like Claude Desktop.

Implements an action-source-type matrix that routes tool calls to appropriate data sources based on action (search, info, stats, options, channels) and source (nixos, home-manager, darwin, flakes, flakehub, nixvim). The nix() tool function (lines 1245-1324 in server.py) contains conditional logic that dispatches to Elasticsearch, FlakeHub API, HTML parsers, or NixHub.io based on the action-source combination, consolidating 17 individual tools into 2 unified tools.

Integrates with Elasticsearch indices for nixos, home-manager, and darwin packages, executing full-text searches against indexed package metadata (names, descriptions, maintainers). The search action routes queries to Elasticsearch endpoints that return ranked results based on relevance scoring, enabling fast, accurate package discovery without requiring local Nix installation or package database.

Integrates with FlakeHub API to discover flakes and retrieve flake metadata (description, source URL, inputs, outputs) for the flakehub source. The search action queries FlakeHub's flake registry, and the info action retrieves detailed flake metadata including dependencies and output types. Enables users to discover community flakes and understand their structure without cloning repositories.