build: ✨ test-mcp.py

Automated testing with server management

```bash
# Inside the Nix development environment
-   test
+   run-tests

# Or using Python directly (works even without pytest installed)
python test_mcp.py
```

dry-run testing (no server required)

```bash
# Inside the Nix development environment
-   test-dry
+   run-tests-dry

# Or using Python directly
python test_mcp.py --dry-run
```

testing with an existing server

```bash
# Test MCP package resource
curl -X GET "http://localhost:8000/mcp/resource?uri=nixos://package/python"
# Test MCP option resource
curl -X GET "http://localhost:8000/mcp/resource?uri=nixos://option/services.nginx"
```

testing with the MCP UI (available in 11.4 and later)
- Open your browser to: http://localhost:8000/mcp
- This provides a UI to explore MCP resources and tools

### Available Tools
The MCP server provides the following tools for AI models:
-
-- `search_packages(query, channel, limit)` - Search for NixOS packages
-- `search_options(query, channel, limit)` - Search for NixOS options
-- `get_resource_context(packages, options, max_entries, format_type)` - Generate formatted context
-Note: Currently only package and option resource endpoints are implemented. Tools will be added in future updates.
+Note: Currently only package and option resource endpoints are implemented. MCP tool endpoints will be added in future updates.

### Using with Claude
Available resources:

diff --git a/pyproject.toml b/pyproject.toml
index 4b91037..89892c7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,14 +6,12 @@ readme = "README.md"
authors = [
    {name =

Author: jamesbrink

.cursorrules

@@ -16,7 +16,10 @@ When updating rules:
 ### Using Nix Develop (Recommended)
 - Development environment: `nix develop`
 - Run server: `run`
-- Run tests: `test`
+- Run tests (automatically manages server): `run-tests`
+  - Run tests with existing server: `run-tests-with-server`
+  - Run test mocks (no server needed): `run-tests-dry`
+  - Run tests in debug mode: `run-tests-debug`
 - List all commands: `menu`
 - Development commands:
   - `setup`: Set up Python environment
@@ -33,10 +36,13 @@ When updating rules:
 - Do not create unnecessary wrapper scripts; prefer using existing tools directly
 - Use README.md to document common commands rather than creating separate scripts
 - Keep all Python code in properly structured modules
-- Test files should be placed in a tests directory and follow pytest naming conventions
+- Test files can use pytest for automatic test discovery
+- The main test_mcp.py file uses pytest fixtures for server management
+- Tests are designed to work in any environment, with or without Nix packages
+- Server is started/stopped automatically during tests
 
 ## Code Style Guidelines
-- Python 3.9+ with type hints required
+- Python 3.11+ with type hints required
 - Use consistent 4-space indentation
 - Follow PEP 8 naming conventions:
   - snake_case for functions and variables

.goosehints

@@ -16,7 +16,10 @@ When updating rules:
 ### Using Nix Develop (Recommended)
 - Development environment: `nix develop`
 - Run server: `run`
-- Run tests: `test`
+- Run tests (automatically manages server): `run-tests`
+  - Run tests with existing server: `run-tests-with-server`
+  - Run test mocks (no server needed): `run-tests-dry`
+  - Run tests in debug mode: `run-tests-debug`
 - List all commands: `menu`
 - Development commands:
   - `setup`: Set up Python environment
@@ -33,10 +36,13 @@ When updating rules:
 - Do not create unnecessary wrapper scripts; prefer using existing tools directly
 - Use README.md to document common commands rather than creating separate scripts
 - Keep all Python code in properly structured modules
-- Test files should be placed in a tests directory and follow pytest naming conventions
+- Test files can use pytest for automatic test discovery
+- The main test_mcp.py file uses pytest fixtures for server management
+- Tests are designed to work in any environment, with or without Nix packages
+- Server is started/stopped automatically during tests
 
 ## Code Style Guidelines
-- Python 3.9+ with type hints required
+- Python 3.11+ with type hints required
 - Use consistent 4-space indentation
 - Follow PEP 8 naming conventions:
   - snake_case for functions and variables

.windsurfrules

@@ -16,7 +16,10 @@ When updating rules:
 ### Using Nix Develop (Recommended)
 - Development environment: `nix develop`
 - Run server: `run`
-- Run tests: `test`
+- Run tests (automatically manages server): `run-tests`
+  - Run tests with existing server: `run-tests-with-server`
+  - Run test mocks (no server needed): `run-tests-dry`
+  - Run tests in debug mode: `run-tests-debug`
 - List all commands: `menu`
 - Development commands:
   - `setup`: Set up Python environment
@@ -33,10 +36,13 @@ When updating rules:
 - Do not create unnecessary wrapper scripts; prefer using existing tools directly
 - Use README.md to document common commands rather than creating separate scripts
 - Keep all Python code in properly structured modules
-- Test files should be placed in a tests directory and follow pytest naming conventions
+- Test files can use pytest for automatic test discovery
+- The main test_mcp.py file uses pytest fixtures for server management
+- Tests are designed to work in any environment, with or without Nix packages
+- Server is started/stopped automatically during tests
 
 ## Code Style Guidelines
-- Python 3.9+ with type hints required
+- Python 3.11+ with type hints required
 - Use consistent 4-space indentation
 - Follow PEP 8 naming conventions:
   - snake_case for functions and variables

CLAUDE.md

@@ -42,7 +42,7 @@ When updating rules:
 - Server is started/stopped automatically during tests
 
 ## Code Style Guidelines
-- Python 3.9+ with type hints required
+- Python 3.11+ with type hints required
 - Use consistent 4-space indentation
 - Follow PEP 8 naming conventions:
   - snake_case for functions and variables

README.md

@@ -31,7 +31,7 @@ menu
 run
 
 # Run tests (automatically handles server startup/shutdown)
-test
+run-tests
 
 # Format and check code
 lint
@@ -60,6 +60,9 @@ nix develop .#legacy
 python server.py
 
 # Run tests (automatically handles server startup/shutdown)
+# Using pytest with server management
+python -m pytest -xvs test_mcp.py
+# OR using the test script directly which works even without pytest
 python test_mcp.py
 ```
 
@@ -80,7 +83,7 @@ The project includes comprehensive test coverage that can be run in several ways
 1. **Automated Testing with Server Management:**
    ```bash
    # Inside the Nix development environment
-   test
+   run-tests
 
    # Or using Python directly (works even without pytest installed)
    python test_mcp.py
@@ -90,7 +93,7 @@ The project includes comprehensive test coverage that can be run in several ways
 2. **Dry Run Testing (No Server Required):**
    ```bash
    # Inside the Nix development environment
-   test-dry
+   run-tests-dry
 
    # Or using Python directly
    python test_mcp.py --dry-run
@@ -100,7 +103,7 @@ The project includes comprehensive test coverage that can be run in several ways
 3. **Testing with an Existing Server:**
    ```bash
    # Inside the Nix development environment (requires server running)
-   test-with-server
+   run-tests-with-server
 
    # Or using pytest directly
    python -m pytest -xvs test_mcp.py
@@ -119,7 +122,7 @@ The project includes comprehensive test coverage that can be run in several ways
 5. **Debug Testing:**
    ```bash
    # Inside the Nix development environment
-   test-debug
+   run-tests-debug
 
    # Or using Python directly
    python test_mcp.py --debug
@@ -145,13 +148,7 @@ Example resource URLs:
 
 ### Available Tools
 
-The MCP server provides the following tools for AI models:
-
-- `search_packages(query, channel, limit)` - Search for NixOS packages
-- `search_options(query, channel, limit)` - Search for NixOS options
-- `get_resource_context(packages, options, max_entries, format_type)` - Generate formatted context
-
-Note: Currently only package and option resource endpoints are implemented. Tools will be added in future updates.
+Note: Currently only package and option resource endpoints are implemented. MCP tool endpoints will be added in future updates.
 
 ### Using with Claude
 

pyproject.toml

@@ -6,14 +6,12 @@ readme = "README.md"
 authors = [
     {name = "James Brink", email = "[email protected]"},
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.11"
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
 ]
 dependencies = [