MCP-NixOS Document Linker - Guaranteeing Factual Precision for AI Outputs

✨ MAJOR REVISION (v1.0.0): This release marks a comprehensive architectural overhaul, aggressively stripping out complex caching layers, redundant abstractions, and legacy patterns. We prioritized simplicity: less overhead, more directness.

⚡️ ASYNCHRONOUS UPGRADE (v1.0.1): Migration to the FastMCP 2.x framework introduced modernized asynchronous handling across all operations, embracing await for non-blocking I/O.

Immediate Deployment Guide (Get Started Now)

Prerequisite Note: Running this tool does not necessitate a local Nix or NixOS installation. It exclusively interacts with remote web services.

Method A: Utilizing uvx (Preferred for General Users)

{ "mcpServers": { "nixos": { "command": "uvx", "args": ["mcp-nixos"] } } }

Method B: Executing via Native Nix (For Nix Enthusiasts)

{ "mcpServers": { "nixos": { "command": "nix", "args": ["run", "github:utensils/mcp-nixos", "--"] } } }

Method C: Containerized Deployment via Docker

{ "mcpServers": { "nixos": { "command": "docker", "args": ["run", "--rm", "-i", "ghcr.io/utensils/mcp-nixos"] } } }

Deployment complete. Your generative model now accesses validated NixOS datasets instead of speculating.

System Capabilities Overview

MCP-NixOS functions as a Model Context Provider, furnishing AI systems with verifiable, current data pertaining to: - NixOS Software Repository: Access to the official registry (over 130,000 entries). - System Configuration Parameters: Detailed lookups on over 22,000 configurable settings. - Home Manager Directives: Specific data for user-level configuration (4K+ options). - nix-darwin Settings: macOS-specific configurations (over 1,000 entries). - Version Chronology: Utilizing NixHub.io to retrieve historical package states and associated Git commit identifiers.

Function Toolkit

🗂️ Core NixOS Query Set

• nixos_search(query, type, channel) - Locate packages, configuration variables, or executables.
• nixos_info(name, type, channel) - Retrieve granular details for a specific item.
• nixos_stats(channel) - Fetch aggregate counts for packages and options.
• nixos_channels() - Enumerate supported distribution channels.
• nixos_flakes_search(query) - Query community-managed flake repositories.
• nixos_flakes_stats() - Report on the size and scope of the flake ecosystem.

⏳ Version Tracking Tools (New)

• nixhub_package_versions(package, limit) - Obtain a timeline of package updates, including specific commit references.
• nixhub_find_version(package, version) - Precision search for a known package/version pair.

🏠 Home Manager Specifics

• home_manager_search(query) - Targeted search within user environment options.
• home_manager_info(name) - Detailed documentation for a setting, including usage hints.
• home_manager_stats() - Overview of the available configuration space.
• home_manager_list_options() - Comprehensive listing across all 131 configuration sections.
• home_manager_options_by_prefix(prefix) - Hierarchical exploration based on configuration path segments.

🍎 Darwin (macOS) Tools

• darwin_search(query) - Search the macOS configuration space handled by Darwin.
• darwin_info(name) - Retrieve specifics on a Darwin setting.
• darwin_stats() - Statistics summarizing Darwin options.
• darwin_list_options() - Browse all 21 configuration categories.
• darwin_options_by_prefix(prefix) - Drill down into macOS settings by their structural prefix.

Deployment Pathways

Crucial Reminder: This tool operates independently of a Nix installation environment.

Standard Environment Installation (Any OS)

bash

Execute immediately without persistence

uvx mcp-nixos

Global installation

pip install mcp-nixos uv pip install mcp-nixos

Nix Environment Integration

bash

On-demand execution

nix run github:utensils/mcp-nixos

Installation into user profile

nix profile install github:utensils/mcp-nixos

Key Functional Attributes

🚀 1.0.1 Update: The Asynchronous Paradigm Shift (Post-Simplification)

• Massive Code Reduction: v1.0.0 dramatically minimized codebase size; v1.0.1 layered async capabilities on top.
• Full Feature Parity: All prior functions are operational, now leveraging await.
• Zero Cache Risk: The legacy cache system remains decommissioned.
• Stateless Operation: No persistent artifacts requiring cleanup (asynchronicity doesn't change this).
• Direct Data Fetching: Bypass intermediaries for immediate, though now asynchronous, API interaction.
• Modern Standard: Adopts FastMCP 2.x protocols, moving beyond outdated synchronous methods.

📊 Data Delivery Characteristics

• Temporal Relevance: Data retrieved is always immediate, eliminating staleness.
• Readability: Output is formatted as clear, machine-parsable plaintext.
• Assisted Input: Provides remedial suggestions for miskeyed configuration names.
• Portability: Fully operational across Linux, macOS, and Windows environments.
• Zero-Config Startup: Functionality is inherent upon execution.

🎯 Major Enhancements

• Dynamic Channel Mapping: The term stable resolves dynamically to the current production branch.
• Improved Diagnostics: Error reporting is significantly more instructive.
• Flake Result Normalization: Duplicated entries in flake searches are suppressed.
• Historical Context Awareness: Enhanced capability to locate versions based on age.
• Systematic Browsing: Improved tools for exploring option categories.

For Project Contributors (Advanced Users)

Local Testing Environment Setup

To facilitate debugging within an MCP client (like Claude Code), place a .mcp.json file in your root directory:

{ "mcpServers": { "nixos": { "type": "stdio", "command": "uv", "args": [ "run", "--directory", "/path/to/your/mcp-nixos/source", "mcp-nixos" ] } } }

This configuration: - Activates automatically when launching the client from that project folder. - Directs queries to your locally modified source code. - Enables immediate validation of changes upon client restart. - Is safely ignored by Git via .gitignore.

Within the Nix Development Shell

bash nix develop menu # Displays available operational targets

Standard operations

run # Initializes the server process (now FastMCP enabled) run-tests # Executes the test suite (async compliant) lint # Code formatting and static analysis (using ruff) typecheck # Static type validation via mypy build # Package creation publish # Deployment to PyPI (requires credential setup)

Outside the Nix Shell (Standard Python Workflow)

bash

Install development toolchain

uv pip install -e ".[dev]"

Execute the server directly

uv run mcp-nixos # or python -m mcp_nixos.server

Development testing scripts

pytest tests/ # Running tests with asyncio considerations ruff format mcp_nixos/ # Code style enforcement ruff check mcp_nixos/ # Linting checks mypy mcp_nixos/ # Type checking rigor

Packaging and Distribution

python -m build # Create source and wheel distributions twine upload dist/* # Submit packages to the repository

Testing Methodology

• Coverage: 367 focused unit and integration tests (now incorporating async testing patterns).
• Data Integrity: Prefer real network interactions over brittle mocks.
• Output Verification: Strict assertion on plaintext format purity.
• Platform Testing: Ensuring consistent behavior across different operating systems.
• Test File Count: Reduced from 29 to 15 through consolidation and better structure.

Operational Environment Configuration

Only a single environment variable influences execution; minimalism prevails:

Variable	Purpose	Default Value
ELASTICSEARCH_URL	Endpoint for the primary NixOS search backend	https://search.nixos.org/backend

Resolving Common Issues

Nix Sandbox Constraint Violation

If using the Nix execution method yields this error:

error: derivation '/nix/store/...-python3.11-watchfiles-1.0.4.drv' specifies a sandbox profile, but this is only allowed when 'sandbox' is 'relaxed'

Remedy: Execute the command explicitly permitting relaxed sandboxing: bash nix run --option sandbox relaxed github:utensils/mcp-nixos --

Underlying Cause: The dependency watchfiles (required for file system monitoring in some setups) requires non-default permissions, which are blocked by Nix's default 'strict' sandbox policy.

Permanent Configuration Adjustment: Modify /etc/nix/nix.conf:

sandbox = relaxed

Gratitude to Data Providers

This utility relies on external data sources for its accuracy: - NixHub.io: Critical for version tracking and commit mapping. - search.nixos.org: Primary interface to the package and option catalogs. - Jetify: Originators of Devbox and contributors to NixHub.

Disclaimer: None of these services officially endorse this specific tool; we are appreciative consumers of their publicly exposed APIs.

Licensing

MIT License - Fostering open access to code and knowledge.

---

Developed and sustained by enthusiasts who appreciate the intersection of Unix philosophy and asynchronous programming paradigms.

Deepest appreciation to the NixOS community for engineering a distribution that presents constant intellectual challenges.