feat: add simple Nix flake for reproducible development environment

[svnlto]

Summary

This PR adds a simple and idiomatic Nix flake for reproducible development environment setup, following the approach suggested in #219. This is a much simpler alternative to the closed PR #219 that had 280+ lines of complex configuration.

Key Features

• Simple Nix Flake (flake.nix): 63 lines vs 280+ in the previous attempt
• Standard Nix Patterns: Uses buildPythonApplication and mkShell
• Hybrid Development Environment: Nix provides system dependencies + Python venv for packages
• direnv Integration (.envrc): Automatic environment activation
• Zero Breaking Changes: No Python version bump, no lockfiles, maintains existing workflows
• Cross-Platform: Works on Linux, macOS, and NixOS
• Enhanced Pre-commit Setup: Added standard formatting and validation hooks

Benefits Over Previous Approach

• 90% less code (63 lines vs 280+ lines)
• No uv2nix or pyproject-nix complexity
• No Python version bump needed (keeps 3.9+ support)
• No lockfile generation required
• Standard Nix development patterns
• Less maintenance overhead
• Works alongside existing ./run-server.sh setup

Files Added/Modified

• flake.nix - Simple Nix flake configuration with improved dependency management
• flake.lock - Nix lock file for reproducibility
• .envrc - direnv configuration for auto-activation
• .gitignore - Exclude Nix development artifacts
• code_quality_checks.sh - Exclude .nix-venv from checks
• run_integration_tests.sh - Robust Nix environment detection
• docs/contributions.md - Document Nix development setup
• .pre-commit-config.yaml - Added comprehensive standard hooks for code quality

Pre-commit Improvements

Added standard pre-commit hooks for better code quality and consistency:

• File formatting: trailing-whitespace, end-of-file-fixer, mixed-line-ending
• Syntax validation: check-yaml, check-json, check-toml
• Safety checks: check-merge-conflict, check-added-large-files
• Updated excludes: Added Nix directories (.nix-venv/, .direnv/)

Code Review Feedback Addressed

• ✅ Added pytest-mock to devShell packages for complete test environment
• ✅ Switched to pip install -e . for better dependency management from pyproject.toml
• ✅ Added python-semantic-release to development dependencies
• ✅ Fixed IN_NIX_SHELL detection to handle pure/impure values properly
• ✅ Added trailing newlines to all configuration files

Usage

# Option 1: Manual activation
nix develop

# Option 2: Automatic with direnv
direnv allow

# Build package
nix build

# Run directly
nix run

This addresses the need for reproducible development environments while keeping the implementation simple and maintainable.

Test plan

• Nix flake builds successfully (nix build)
• Development shell provides all dependencies (nix develop)
• Hybrid environment works with existing scripts
• Code quality checks pass with exclusions
• Integration tests detect Nix environment properly
• Pre-commit hooks work correctly and format codebase
• All PR feedback addressed and verified
• Documentation is accurate and helpful
• Existing non-Nix workflows remain unaffected

Fixes the need for Nix support mentioned in #219 with a much simpler approach, plus enhanced code quality tooling.

[gemini-code-assist]

Summary of Changes

Hello @svnlto, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a simple Nix flake to provide a reproducible development environment for the Zen MCP Server. It offers a streamlined alternative to previous complex attempts by integrating Nix for system dependencies while maintaining a Python virtual environment for package management. The changes ensure cross-platform compatibility and zero breaking changes to existing workflows, making the development setup more robust and easier to manage.

Highlights

• Reproducible Development Environment: Implemented a simple Nix flake (flake.nix) for reproducible development, significantly reducing configuration complexity compared to prior attempts.
• Hybrid Environment Setup: Established a hybrid development environment where Nix manages system dependencies and a Python virtual environment handles Python package management.
• Automated Environment Activation: Integrated direnv via a new .envrc file to automatically activate the Nix development shell upon directory entry.
• Tooling Integration: Updated code_quality_checks.sh and run_integration_tests.sh to properly handle the new Nix environment, excluding Nix-managed directories from checks and detecting Nix shell activation.
• Documentation: Added comprehensive documentation in docs/contributions.md detailing the Nix setup, its benefits, and usage instructions for developers.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a simple and idiomatic Nix flake to provide a reproducible development environment, which is a great improvement for contributor onboarding and consistency. The implementation is clean and follows standard Nix patterns. My review focuses on improving the maintainability of the dependency management within the flake and ensuring the development environment is complete and robust. I've suggested changes to avoid hardcoding dependencies in the shellHook and to include all necessary development packages.