feat: add simple Nix flake for reproducible development environment

.envrc

@@ -0,0 +1,2 @@
+use flake
+dotenv

.gitignore

@@ -184,3 +184,8 @@ CLAUDE.local.md
 logs/
 *.backup
 /.desktop_configured
+
+# Nix development environment
+.nix-venv/
+.direnv/
+result

code_quality_checks.sh

@@ -67,16 +67,16 @@ echo "📋 Step 1: Running Linting and Formatting Checks"
 echo "--------------------------------------------------"
 
 echo "🔧 Running ruff linting with auto-fix..."
-$RUFF check --fix --exclude test_simulation_files --exclude .zen_venv
+$RUFF check --fix --exclude test_simulation_files --exclude .zen_venv --exclude .nix-venv
 
 echo "🎨 Running black code formatting..."
-$BLACK . --exclude="test_simulation_files/" --exclude=".zen_venv/"
+$BLACK . --exclude="test_simulation_files/" --exclude=".zen_venv/" --exclude=".nix-venv/"
 
 echo "📦 Running import sorting with isort..."
-$ISORT . --skip-glob=".zen_venv/*" --skip-glob="test_simulation_files/*"
+$ISORT . --skip-glob=".zen_venv/*" --skip-glob=".nix-venv/*" --skip-glob="test_simulation_files/*"
 
 echo "✅ Verifying all linting passes..."
-$RUFF check --exclude test_simulation_files --exclude .zen_venv
+$RUFF check --exclude test_simulation_files --exclude .zen_venv --exclude .nix-venv
 
 echo "✅ Step 1 Complete: All linting and formatting checks passed!"
 echo ""

docs/contributions.md

@@ -7,14 +7,63 @@ Thank you for your interest in contributing to Zen MCP Server! This guide will h
 1. **Fork the repository** on GitHub
 2. **Clone your fork** locally
 3. **Set up the development environment**:
+
+   **Option A: Traditional Setup**
    ```bash
    ./run-server.sh
    ```
+
+   **Option B: Nix Flake (Recommended for Nix users)**
+   ```bash
+   # Automatic environment activation with direnv (one-time setup)
+   direnv allow
+
+   # Or manually enter development shell
+   nix develop
+
+   # Build and test the package
+   nix build
+   nix run
+   ```
+
 4. **Create a feature branch** from `main`:
    ```bash
    git checkout -b feat/your-feature-name
    ```
 
+### Nix Development Environment
+
+The Nix flake provides several advantages for development:
+
+- **Reproducible Environment**: Identical dependencies across all systems
+- **Zero Setup**: No need to install Python, pip, or manage virtual environments  
+- **Isolated Dependencies**: No conflicts with system packages
+- **Cross-Platform**: Works on Linux, macOS, and NixOS
+
+**Available Nix Commands:**
+```bash
+# Enter development shell with all dependencies
+nix develop
+
+# Build the package
+nix build
+./result/bin/zen-mcp-server
+
+# Run directly without building
+nix run
+
+# Install system-wide
+nix profile install .
+
+# Install from GitHub (for users)
+nix profile install github:BeehiveInnovations/zen-mcp-server
+```
+
+**With direnv** (`.envrc` included):
+- Environment automatically activates when entering the directory
+- All development tools (Python, pytest, black, ruff, isort) available instantly
+- No manual activation needed
+
 ## Development Process
 
 ### 1. Code Quality Standards

flake.nix

@@ -0,0 +1,63 @@
+{
+  description = "Zen MCP Server";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { nixpkgs, flake-utils, ... }:
+    flake-utils.lib.eachDefaultSystem (system: let
+      pkgs = import nixpkgs { inherit system; };
+      python = pkgs.python312;
+    in {
+      packages.default = python.pkgs.buildPythonApplication {
+        pname = "zen-mcp-server";
+        version = "1.1.0";
+        src = ./.;
+        format = "pyproject";
+
+        nativeBuildInputs = with python.pkgs; [ 
+          setuptools 
+          setuptools-scm 
+          wheel 
+        ];
+        propagatedBuildInputs = with python.pkgs; [
+          mcp google-genai openai pydantic python-dotenv
+        ];
+
+        # If packages aren't in nixpkgs, override here
+        # postInstall = "ln -s $out/bin/server.py $out/bin/zen-mcp-server";
+      };
+
+      devShells.default = pkgs.mkShell {
+        packages = [ 
+          python
+          python.pkgs.pip
+          python.pkgs.virtualenv
+          # Basic tools
+          pkgs.git
+        ] ++ (with python.pkgs; [
+          # Only basic packages from nixpkgs
+          pytest black ruff isort setuptools wheel
+        ]);
+
+        shellHook = ''
+          if [ ! -d ".nix-venv" ]; then
+            echo "Setting up Python environment..."
+            python -m venv .nix-venv --quiet
+            source .nix-venv/bin/activate
+            pip install -q --upgrade pip
+            pip install -q mcp google-genai openai pydantic python-dotenv pytest-asyncio
+            deactivate
+          fi
+          source .nix-venv/bin/activate
+        '';
+
+        # Ensure proper shared library paths
+        LD_LIBRARY_PATH = pkgs.lib.makeLibraryPath [
+          pkgs.stdenv.cc.cc.lib
+        ];
+      };
+    });
+}

run_integration_tests.sh

@@ -11,13 +11,15 @@ echo "=============================================="
 echo "These tests use real API calls with your configured keys"
 echo ""
 
-# Activate virtual environment
-if [[ -f ".zen_venv/bin/activate" ]]; then
+# Activate virtual environment (skip if in Nix environment)
+if [[ -n "$NIX_BUILD_TOP" ]] || [[ "$IN_NIX_SHELL" == "1" ]]; then
+    echo "✅ Using Nix development environment"
+elif [[ -f ".zen_venv/bin/activate" ]]; then
     source .zen_venv/bin/activate
     echo "✅ Using virtual environment"
 else
     echo "❌ No virtual environment found!"
-    echo "Please run: ./run-server.sh first"
+    echo "Please run: ./run-server.sh first or use 'nix develop'"
     exit 1
 fi