docs: Add examples and declarative usage

README.md

@@ -108,14 +108,142 @@ uv pip install mcp-nixos
 ```
 
 ### For Nix Users (You Know Who You Are)
+
+#### Imperative Installation (Quick & Dirty)
 ```bash
 # Run without installing
 nix run github:utensils/mcp-nixos
 
-# Install to profile
+# Install to profile (not recommended for most Nix users)
 nix profile install github:utensils/mcp-nixos
 ```
 
+#### Declarative Installation (The Nix Way™)
+
+Most Nix users prefer declarative configuration. Here's how to properly integrate MCP-NixOS:
+
+##### Using Flakes (Recommended)
+
+Add to your `flake.nix`:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    mcp-nixos.url = "github:utensils/mcp-nixos";
+  };
+
+  outputs = { self, nixpkgs, mcp-nixos, ... }: {
+    # For NixOS systems
+    nixosConfigurations.mysystem = nixpkgs.lib.nixosSystem {
+      modules = [
+        ({ pkgs, ... }: {
+          environment.systemPackages = [
+            mcp-nixos.packages.${pkgs.system}.default
+          ];
+        })
+      ];
+    };
+
+    # For Home Manager users
+    homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {
+      modules = [
+        ({ pkgs, ... }: {
+          home.packages = [
+            mcp-nixos.packages.${pkgs.system}.default
+          ];
+        })
+      ];
+    };
+
+    # For nix-darwin (macOS) users
+    darwinConfigurations.mymac = darwin.lib.darwinSystem {
+      modules = [
+        ({ pkgs, ... }: {
+          environment.systemPackages = [
+            mcp-nixos.packages.${pkgs.system}.default
+          ];
+        })
+      ];
+    };
+  };
+}
+```
+
+##### Using Home Manager (without flakes)
+
+Add to your `home.nix`:
+
+```nix
+{ pkgs, ... }:
+
+let
+  mcp-nixos = pkgs.fetchFromGitHub {
+    owner = "utensils";
+    repo = "mcp-nixos";
+    rev = "main"; # Or pin to a specific commit/tag
+    sha256 = "0000000000000000000000000000000000000000000000000000"; # Use nix-prefetch-github
+  };
+
+  mcp-nixos-pkg = pkgs.callPackage "${mcp-nixos}/default.nix" { };
+in
+{
+  home.packages = [
+    mcp-nixos-pkg
+  ];
+}
+```
+
+##### Using NixOS Configuration (without flakes)
+
+Add to your `configuration.nix`:
+
+```nix
+{ config, pkgs, ... }:
+
+let
+  mcp-nixos = pkgs.fetchFromGitHub {
+    owner = "utensils";
+    repo = "mcp-nixos";
+    rev = "main"; # Or pin to a specific commit/tag
+    sha256 = "0000000000000000000000000000000000000000000000000000"; # Use nix-prefetch-github
+  };
+
+  mcp-nixos-pkg = pkgs.callPackage "${mcp-nixos}/default.nix" { };
+in
+{
+  environment.systemPackages = with pkgs; [
+    mcp-nixos-pkg
+  ];
+}
+```
+
+##### Using an Overlay
+
+Create an overlay in `~/.config/nixpkgs/overlays/mcp-nixos.nix`:
+
+```nix
+self: super: {
+  mcp-nixos = super.callPackage (super.fetchFromGitHub {
+    owner = "utensils";
+    repo = "mcp-nixos";
+    rev = "main";
+    sha256 = "0000000000000000000000000000000000000000000000000000";
+  } + "/default.nix") { };
+}
+```
+
+Then use it in any Nix expression:
+```nix
+{ pkgs, ... }: {
+  environment.systemPackages = [ pkgs.mcp-nixos ];
+}
+```
+
+After installation, configure your MCP client as shown in the Quick Start section above.
+
+📁 **See the `examples/` directory for complete, copy-paste ready configuration files for all installation methods.**
+
 ## Features Worth Mentioning
 
 ### 🚀 Version 1.0.1: The Async Revolution (After The Great Simplification)

default.nix

@@ -0,0 +1,34 @@
+{ pkgs ? import <nixpkgs> { } }:
+
+let
+  pythonVersion = "312";
+  python = pkgs."python${pythonVersion}";
+  ps = pkgs."python${pythonVersion}Packages";
+
+  pyproject = pkgs.lib.importTOML ./pyproject.toml;
+in
+ps.buildPythonApplication {
+  pname = pyproject.project.name;
+  inherit (pyproject.project) version;
+  meta.mainProgram = pyproject.project.name;
+
+  src = ./.;
+
+  format = "pyproject";
+
+  nativeBuildInputs = with ps; [
+    hatchling
+  ];
+
+  propagatedBuildInputs = with ps; [
+    fastmcp
+    requests
+    beautifulsoup4
+  ];
+
+  # Disable runtime dependency checks since the available versions in nixpkgs
+  # may not match exactly what's specified in pyproject.toml
+  pythonImportsCheck = [ ];
+  doCheck = false;
+  dontCheckRuntimeDeps = true;
+}

examples/configuration.nix

@@ -0,0 +1,77 @@
+# Example NixOS system configuration with MCP-NixOS
+# Add this to your /etc/nixos/configuration.nix or create a separate module
+
+{ config, pkgs, lib, ... }:
+
+let
+  # For non-flake users: fetch MCP-NixOS from GitHub
+  mcp-nixos-src = pkgs.fetchFromGitHub {
+    owner = "utensils";
+    repo = "mcp-nixos";
+    rev = "main"; # Pin to a specific commit for reproducibility
+    # To get the correct sha256:
+    # nix-prefetch-github utensils mcp-nixos
+    sha256 = lib.fakeSha256; # Replace with actual sha256
+  };
+
+  # Build the package
+  mcp-nixos = pkgs.callPackage "${mcp-nixos-src}/default.nix" { };
+in
+{
+  # Add MCP-NixOS to system-wide packages
+  environment.systemPackages = with pkgs; [
+    mcp-nixos
+    # Other packages...
+  ];
+
+  # Optional: Configure MCP-NixOS for all users
+  # This creates a system-wide configuration file
+  environment.etc."claude/claude_desktop_config.json" = {
+    text = builtins.toJSON {
+      mcpServers = {
+        nixos = {
+          command = "${mcp-nixos}/bin/mcp-nixos";
+          args = [];
+        };
+      };
+    };
+    # Make it readable by all users
+    mode = "0644";
+  };
+
+  # Optional: Create a systemd service to run MCP-NixOS as a system daemon
+  # (Only useful if your MCP client supports network connections)
+  systemd.services.mcp-nixos = {
+    description = "MCP-NixOS Server";
+    after = [ "network.target" ];
+    wantedBy = [ "multi-user.target" ];
+
+    serviceConfig = {
+      Type = "simple";
+      ExecStart = "${mcp-nixos}/bin/mcp-nixos";
+      Restart = "on-failure";
+      RestartSec = 5;
+      # Run as a non-privileged user
+      User = "nobody";
+      Group = "nogroup";
+      # Security hardening
+      PrivateTmp = true;
+      ProtectSystem = "strict";
+      ProtectHome = true;
+      NoNewPrivileges = true;
+    };
+
+    # Disable by default - users can enable if needed
+    enable = false;
+  };
+
+  # Optional: Create a shell alias for all users
+  programs.bash.shellAliases = {
+    mcp-nixos-test = "${mcp-nixos}/bin/mcp-nixos";
+  };
+
+  # Optional: Add to the system path
+  environment.variables = {
+    MCP_NIXOS_PATH = "${mcp-nixos}/bin/mcp-nixos";
+  };
+}

examples/darwin-configuration.nix

@@ -0,0 +1,91 @@
+# Example nix-darwin configuration with MCP-NixOS for macOS
+# Add this to your darwin-configuration.nix or create a separate module
+
+{ config, pkgs, lib, ... }:
+
+let
+  # For non-flake users: fetch MCP-NixOS from GitHub
+  mcp-nixos-src = pkgs.fetchFromGitHub {
+    owner = "utensils";
+    repo = "mcp-nixos";
+    rev = "main"; # Pin to a specific commit for reproducibility
+    # To get the correct sha256:
+    # nix-prefetch-github utensils mcp-nixos
+    sha256 = lib.fakeSha256; # Replace with actual sha256
+  };
+
+  # Build the package
+  mcp-nixos = pkgs.callPackage "${mcp-nixos-src}/default.nix" { };
+in
+{
+  # Add MCP-NixOS to system-wide packages
+  environment.systemPackages = with pkgs; [
+    mcp-nixos
+    # Other packages...
+  ];
+
+  # Configure Claude Desktop for all users
+  # Note: Adjust path based on where Claude Desktop stores config on macOS
+  environment.etc."claude/claude_desktop_config.json" = {
+    text = builtins.toJSON {
+      mcpServers = {
+        nixos = {
+          command = "${mcp-nixos}/bin/mcp-nixos";
+          args = [];
+        };
+      };
+    };
+  };
+
+  # Create launchd service for MCP-NixOS (macOS equivalent of systemd)
+  launchd.user.agents.mcp-nixos = {
+    command = "${mcp-nixos}/bin/mcp-nixos";
+
+    serviceConfig = {
+      Label = "org.nixos.mcp-nixos";
+      RunAtLoad = false; # Don't start automatically
+      KeepAlive = false; # Don't restart if it crashes
+      StandardErrorPath = "/tmp/mcp-nixos.err";
+      StandardOutPath = "/tmp/mcp-nixos.out";
+    };
+  };
+
+  # Add shell aliases for convenience
+  programs.bash.interactiveShellInit = ''
+    alias mcp-nixos-test='${mcp-nixos}/bin/mcp-nixos'
+  '';
+
+  programs.zsh.interactiveShellInit = ''
+    alias mcp-nixos-test='${mcp-nixos}/bin/mcp-nixos'
+  '';
+
+  # Optional: Configure for Cursor on macOS
+  # This assumes Cursor config is in the user's home directory
+  system.activationScripts.postUserActivation.text = ''
+    # Create Cursor MCP config for all users
+    for user_home in /Users/*; do
+      if [ -d "$user_home" ]; then
+        cursor_config_dir="$user_home/.cursor"
+        if [ ! -d "$cursor_config_dir" ]; then
+          mkdir -p "$cursor_config_dir"
+        fi
+        
+        cat > "$cursor_config_dir/mcp.json" <<EOF
+    {
+      "mcpServers": {
+        "nixos": {
+          "command": "${mcp-nixos}/bin/mcp-nixos",
+          "args": []
+        }
+      }
+    }
+    EOF
+      fi
+    done
+  '';
+
+  # Set environment variable for easy reference
+  environment.variables = {
+    MCP_NIXOS_PATH = "${mcp-nixos}/bin/mcp-nixos";
+  };
+}