Usage Examples

#Overview

These examples demonstrate how to use MCP-NixOS tools to solve common Nix ecosystem tasks. Each example shows the JSON request format and the corresponding response, helping you understand how to effectively leverage MCP-NixOS in your workflows.

#Configuration

Before using these examples, you'll need to configure your MCP server. Add the following to your MCP configuration file:

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

This configuration enables your AI assistant to access NixOS package information and configuration options through the MCP protocol. For additional configuration options, see the configuration documentation.

#Example Scenarios

These examples demonstrate practical use cases for MCP-NixOS tools and the type of information they provide. Each example shows the complete workflow from user question to AI response.

#Example 1: PostgreSQL Versions and Configuration

User Prompt

"What PostgreSQL versions are available in NixOS, and what are the configuration options?"

AI Assistant Response:

NixOS provides multiple versions of PostgreSQL:

  • PostgreSQL 13 (13.14)
  • PostgreSQL 14 (14.10)
  • PostgreSQL 15 (15.5)
  • PostgreSQL 16 (16.1) - This is the default version
  • PostgreSQL 17 (17.0) - Latest version

For configuration, you can use the services.postgresql module with these key options:

  • enable - Enable the PostgreSQL server
  • package - Select which PostgreSQL version to use
  • authentication - Configure client authentication methods
  • enableTCPIP - Allow network connections (not just local socket)
  • dataDir - Specify where to store the database files

This information helps system administrators choose the appropriate PostgreSQL version and configure it according to their specific requirements.

#Example 2: Checking Package Availability

User Prompt

"Is the tldr package available in NixOS, and what variants exist?"

AI Assistant Response:

NixOS provides several implementations of the tldr client:

  • The main Python-based tldr package
  • Rust implementations: tlrc (official) and tealdeer (optimized for speed)
  • Language-specific implementations for Haskell, Emacs Lisp, and R

The main package is available across multiple platforms and provides a simple command-line interface for accessing community-maintained simplified documentation. This is particularly useful for quickly finding common usage examples without having to read through comprehensive man pages.

#Example 3: Validating NixOS Configuration

User Prompt

"Can you validate this Nginx configuration for me?"

AI Assistant Response:

I've analyzed your Nginx configuration and found several issues that need to be corrected:

  • fastReload, cacheStrategy, compressionLevel, timeoutMs, requestRateLimiting, and tlsSettings are not valid NixOS options
  • workerProcesses should be "auto" not "optimal"
  • Custom settings should use extraConfig and appendHttpConfig

Here's the corrected configuration:

nix
{ config, pkgs, ... }:

{
  services.nginx = {
    enable = true;
    # fastReload is not a valid option, removed
    
    virtualHosts."example.com" = {
      enableACME = true;
      forceSSL = true;
      root = "/var/www/example.com";
      
      locations."/" = {
        index = "index.html";
        # cacheStrategy is not a valid option
        # You can use extraConfig to add caching directives:
        extraConfig = ''
          expires max;
          add_header Cache-Control "public, immutable";
        '';
      };
      
      locations."/api" = {
        proxyPass = "http://localhost:8080";
        # compressionLevel is not a valid option
        # timeoutMs is not a valid option
        # Use extraConfig for these custom settings:
        extraConfig = ''
          proxy_read_timeout 5s;
          gzip on;
          gzip_comp_level 9;
        '';
      };
    };
    
    workerProcesses = "auto"; # "optimal" is not valid, use "auto"
    
    # requestRateLimiting is not a valid option block
    # Use recommendedProxySettings and limit_req_zone in httpConfig
    recommendedProxySettings = true;
    appendHttpConfig = ''
      limit_req_zone $binary_remote_addr zone=limit:10m rate=100r/s;
      limit_req zone=limit burst=20 nodelay;
    '';
    
    # tlsSettings is not a valid option block
    # Use recommendedTlsSettings instead
    recommendedTlsSettings = true;
    # For additional TLS settings, use sslCiphers and sslProtocols
    sslCiphers = "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
    sslProtocols = "TLSv1.2 TLSv1.3";
  };
}

This corrected configuration follows NixOS best practices for Nginx setup, using standard options and proper syntax for custom settings. The configuration enables HTTPS with ACME (Let's Encrypt), sets up a static file server with caching, configures an API proxy with compression, implements rate limiting, and applies recommended security settings.

#Example 4: Checking Cross-Platform Package Availability

User Prompt

"Is codename goose available in nix packages for mac?"

AI Assistant Response:

While there isn't a package specifically named "codename goose", I found two relevant packages that might match what you're looking for:

  • goose-cli (v1.0.15) - An open-source AI agent for coding tasks
  • goose-lang (v0.9.2) - A tool that converts Go code to Coq

Both packages are available for macOS, as indicated by the platform identifiers in their metadata:

  • x86_64-darwin - Intel-based Macs
  • aarch64-darwin - Apple Silicon Macs (M1/M2/M3)

If you're looking for the AI coding assistant called "Goose", the goose-cli package is likely what you want. You can install it on your Mac using:

bash
nix-env -iA nixpkgs.goose-cli  # For global installation

# Or in a development shell
nix-shell -p goose-cli

#Example 5: macOS Configuration with nix-darwin

User Prompt

"What all can be configured on macOS when using nix?"

AI Assistant Response:

nix-darwin provides extensive configuration options for macOS, allowing you to manage your system declaratively. Here's a comprehensive overview of what you can configure:

System Configuration
  • System Defaults: Appearance (dark mode, accent colors), Dock behavior, Mission Control, keyboard/trackpad settings, Finder preferences, security settings
  • Window Managers: Configure tiling window managers like yabai, AeroSpace, and Amethyst
  • Networking: Hostname, DNS settings, WireGuard interfaces, firewall rules
Package Management
  • Homebrew Integration: Install command-line tools (brews), GUI applications (casks), App Store apps (masApps)
  • Nix Packages: System-wide and per-user packages, package overlays
Shell Environment
  • Shell Configuration: Bash, Zsh, Fish with customizations for prompts, completions, and plugins
  • Environment Variables: System-wide and shell-specific variables, PATH modifications
System Services
  • Application Services: Databases (PostgreSQL, MySQL, Redis), web servers, development tools
  • macOS Specific: Fonts, launchd services, Spotlight configuration, Time Machine settings

Here's a simple example configuration for customizing macOS with nix-darwin:

nix
{ config, pkgs, ... }:

{
  # System defaults
  system.defaults.NSGlobalDomain = {
    AppleInterfaceStyle = "Dark";       # Enable dark mode
    AppleShowScrollBars = "Always";    # Always show scrollbars
    NSAutomaticSpellingCorrectionEnabled = false;
  };
  
  system.defaults.dock = {
    autohide = true;                   # Auto-hide the dock
    orientation = "left";              # Position dock on the left
    tilesize = 48;                     # Icon size
  };
  
  # Homebrew packages
  homebrew = {
    enable = true;
    onActivation.autoUpdate = true;
    casks = [ "firefox" "visual-studio-code" "iterm2" ];
    brews = [ "ripgrep" "fd" "jq" ];
  };
  
  # Shell configuration
  programs.zsh = {
    enable = true;
    enableCompletion = true;
    enableSyntaxHighlighting = true;
  };
  
  # System packages
  environment.systemPackages = with pkgs; [
    git
    neovim
    tmux
    htop
  ];
  
  # Window manager
  services.yabai = {
    enable = true;
    config = {
      layout = "bsp";
      window_gap = 10;
    };
  };
}

This configuration can be applied by adding it to your ~/.nixpkgs/darwin-configuration.nix file and running darwin-rebuild switch. The changes will be applied immediately and persist across reboots, giving you a consistent, reproducible macOS environment.