README.md

@@ -4,18 +4,26 @@ A collection of Model Context Protocol (MCP) servers written in Go.
 
 ## MCP Servers
 
-### NixOS Options (`nixos-options`)
+### Nixpkgs Search (`nixpkgs-search`) - Primary
 
-Search and query NixOS configuration options across multiple nixpkgs revisions. Designed to help Claude (and other MCP clients) answer questions about NixOS configuration.
+Combined search for NixOS options and Nix packages from nixpkgs. Provides two separate MCP servers:
+- **Options server**: Search NixOS configuration options (`nixpkgs-search options serve`)
+- **Packages server**: Search Nix packages (`nixpkgs-search packages serve`)
+
+Both servers share the same database, allowing you to index once and serve both.
 
 ### Home Manager Options (`hm-options`)
 
 Search and query Home Manager configuration options across multiple home-manager revisions. Designed to help Claude (and other MCP clients) answer questions about Home Manager configuration.
 
+### NixOS Options (`nixos-options`) - Legacy
+
+Search and query NixOS configuration options. **Note**: Prefer using `nixpkgs-search` instead, which includes this functionality plus package search.
+
 ### Shared Features
 
-- Full-text search across option names and descriptions
-- Query specific options with type, default, example, and declarations
+- Full-text search across option/package names and descriptions
+- Query specific options/packages with full metadata
 - Index multiple revisions (by git hash or channel name)
 - Fetch module source files
 - Support for PostgreSQL and SQLite backends
@@ -26,18 +34,18 @@ Search and query Home Manager configuration options across multiple home-manager
 
 ```bash
 # Build the packages
-nix build git+https://git.t-juice.club/torjus/labmcp#nixos-options
+nix build git+https://git.t-juice.club/torjus/labmcp#nixpkgs-search
 nix build git+https://git.t-juice.club/torjus/labmcp#hm-options
 
 # Or run directly
-nix run git+https://git.t-juice.club/torjus/labmcp#nixos-options -- --help
+nix run git+https://git.t-juice.club/torjus/labmcp#nixpkgs-search -- --help
 nix run git+https://git.t-juice.club/torjus/labmcp#hm-options -- --help
 ```
 
 ### From Source
 
 ```bash
-go install git.t-juice.club/torjus/labmcp/cmd/nixos-options@latest
+go install git.t-juice.club/torjus/labmcp/cmd/nixpkgs-search@latest
 go install git.t-juice.club/torjus/labmcp/cmd/hm-options@latest
 ```
 
@@ -50,11 +58,18 @@ Configure in your MCP client (e.g., Claude Desktop):
 ```json
 {
   "mcpServers": {
-    "nixos-options": {
-      "command": "nixos-options",
-      "args": ["serve"],
+    "nixpkgs-options": {
+      "command": "nixpkgs-search",
+      "args": ["options", "serve"],
       "env": {
-        "NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
+        "NIXPKGS_SEARCH_DATABASE": "sqlite:///path/to/nixpkgs-search.db"
+      }
+    },
+    "nixpkgs-packages": {
+      "command": "nixpkgs-search",
+      "args": ["packages", "serve"],
+      "env": {
+        "NIXPKGS_SEARCH_DATABASE": "sqlite:///path/to/nixpkgs-search.db"
       }
     },
     "hm-options": {
@@ -73,11 +88,18 @@ Alternatively, if you have Nix installed, you can use the flake directly without
 ```json
 {
   "mcpServers": {
-    "nixos-options": {
+    "nixpkgs-options": {
       "command": "nix",
-      "args": ["run", "git+https://git.t-juice.club/torjus/labmcp#nixos-options", "--", "serve"],
+      "args": ["run", "git+https://git.t-juice.club/torjus/labmcp#nixpkgs-search", "--", "options", "serve"],
       "env": {
-        "NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
+        "NIXPKGS_SEARCH_DATABASE": "sqlite:///path/to/nixpkgs-search.db"
+      }
+    },
+    "nixpkgs-packages": {
+      "command": "nix",
+      "args": ["run", "git+https://git.t-juice.club/torjus/labmcp#nixpkgs-search", "--", "packages", "serve"],
+      "env": {
+        "NIXPKGS_SEARCH_DATABASE": "sqlite:///path/to/nixpkgs-search.db"
       }
     },
     "hm-options": {
@@ -93,20 +115,21 @@ Alternatively, if you have Nix installed, you can use the flake directly without
 
 ### As MCP Server (HTTP)
 
-Both servers can run over HTTP with Server-Sent Events (SSE) for web-based MCP clients:
+All servers can run over HTTP with Server-Sent Events (SSE) for web-based MCP clients:
 
 ```bash
 # Start HTTP server on default address (127.0.0.1:8080)
-nixos-options serve --transport http
+nixpkgs-search options serve --transport http
+nixpkgs-search packages serve --transport http
 hm-options serve --transport http
 
 # Custom address and CORS configuration
-nixos-options serve --transport http \
+nixpkgs-search options serve --transport http \
   --http-address 0.0.0.0:8080 \
   --allowed-origins https://example.com
 
 # With TLS
-nixos-options serve --transport http \
+nixpkgs-search options serve --transport http \
   --tls-cert /path/to/cert.pem \
   --tls-key /path/to/key.pem
 ```
@@ -118,53 +141,77 @@ HTTP transport endpoints:
 
 ### CLI Examples
 
-**Index a revision:**
+**Index a revision (nixpkgs-search):**
 
 ```bash
-# NixOS options - index by channel name
-nixos-options index nixos-unstable
-
-# Home Manager options - index by channel name
-hm-options index hm-unstable
+# Index both options and packages
+nixpkgs-search index nixos-unstable
 
 # Index by git hash
-nixos-options index e6eae2ee2110f3d31110d5c222cd395303343b08
+nixpkgs-search index e6eae2ee2110f3d31110d5c222cd395303343b08
+
+# Index options only (faster, skip packages)
+nixpkgs-search index --no-packages nixos-unstable
+
+# Index packages only (skip options)
+nixpkgs-search index --no-options nixos-unstable
 
 # Index without file contents (faster, disables get_file tool)
-nixos-options index --no-files nixos-unstable
+nixpkgs-search index --no-files nixos-unstable
+```
+
+**Index a revision (hm-options):**
+
+```bash
+# Index by channel name
+hm-options index hm-unstable
+
+# Index without file contents
 hm-options index --no-files release-24.11
 ```
 
 **List indexed revisions:**
 
 ```bash
-nixos-options list
+nixpkgs-search list
 hm-options list
 ```
 
 **Search for options:**
 
 ```bash
-# NixOS options
-nixos-options search nginx
-nixos-options search -n 10 postgresql
+# NixOS options via nixpkgs-search
+nixpkgs-search options search nginx
+nixpkgs-search options search -n 10 postgresql
 
 # Home Manager options
 hm-options search git
 hm-options search -n 10 neovim
 ```
 
-**Get option details:**
+**Search for packages:**
 
 ```bash
-nixos-options get services.nginx.enable
+nixpkgs-search packages search firefox
+nixpkgs-search packages search -n 10 python
+
+# Filter by status
+nixpkgs-search packages search --unfree nvidia
+nixpkgs-search packages search --broken deprecated-package
+```
+
+**Get option/package details:**
+
+```bash
+nixpkgs-search options get services.nginx.enable
+nixpkgs-search packages get firefox
 hm-options get programs.git.enable
 ```
 
 **Delete an indexed revision:**
 
 ```bash
-nixos-options delete nixos-23.11
+nixpkgs-search delete nixos-23.11
 hm-options delete release-23.11
 ```
 
@@ -174,20 +221,21 @@ hm-options delete release-23.11
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `NIXOS_OPTIONS_DATABASE` | Database connection string for nixos-options | `sqlite://nixos-options.db` |
+| `NIXPKGS_SEARCH_DATABASE` | Database connection string for nixpkgs-search | `sqlite://nixpkgs-search.db` |
 | `HM_OPTIONS_DATABASE` | Database connection string for hm-options | `sqlite://hm-options.db` |
+| `NIXOS_OPTIONS_DATABASE` | Database connection string for nixos-options (legacy) | `sqlite://nixos-options.db` |
 
 ### Database Connection Strings
 
 **SQLite:**
 ```bash
-export NIXOS_OPTIONS_DATABASE="sqlite:///path/to/database.db"
-export NIXOS_OPTIONS_DATABASE="sqlite://:memory:"  # In-memory
+export NIXPKGS_SEARCH_DATABASE="sqlite:///path/to/database.db"
+export NIXPKGS_SEARCH_DATABASE="sqlite://:memory:"  # In-memory
 ```
 
 **PostgreSQL:**
 ```bash
-export NIXOS_OPTIONS_DATABASE="postgres://user:pass@localhost/nixos_options?sslmode=disable"
+export NIXPKGS_SEARCH_DATABASE="postgres://user:pass@localhost/nixpkgs_search?sslmode=disable"
 ```
 
 ### Command-Line Flags
@@ -195,13 +243,14 @@ export NIXOS_OPTIONS_DATABASE="postgres://user:pass@localhost/nixos_options?sslm
 The database can also be specified via the `-d` or `--database` flag:
 
 ```bash
-nixos-options -d "postgres://localhost/nixos" serve
+nixpkgs-search -d "postgres://localhost/nixpkgs" options serve
+nixpkgs-search -d "sqlite://my.db" index nixos-unstable
 hm-options -d "sqlite://my.db" index hm-unstable
 ```
 
 ## MCP Tools
 
-Both servers provide the following tools:
+### Options Servers (nixpkgs-search options, hm-options)
 
 | Tool | Description |
 |------|-------------|
@@ -212,11 +261,24 @@ Both servers provide the following tools:
 | `list_revisions` | List all indexed revisions |
 | `delete_revision` | Delete an indexed revision |
 
+### Packages Server (nixpkgs-search packages)
+
+| Tool | Description |
+|------|-------------|
+| `search_packages` | Search for packages by name or description |
+| `get_package` | Get full details for a specific package |
+| `get_file` | Fetch source file contents from nixpkgs |
+| `index_revision` | Index a revision |
+| `list_revisions` | List all indexed revisions |
+| `delete_revision` | Delete an indexed revision |
+
 ## NixOS Modules
 
-NixOS modules are provided for running both MCP servers as systemd services.
+NixOS modules are provided for running the MCP servers as systemd services.
 
-### nixos-options
+### nixpkgs-search (Recommended)
+
+The `nixpkgs-search` module runs two separate MCP servers (options and packages) that share a database:
 
 ```nix
 {
@@ -226,11 +288,12 @@ NixOS modules are provided for running both MCP servers as systemd services.
     nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
       system = "x86_64-linux";
       modules = [
-        labmcp.nixosModules.nixos-options-mcp
+        labmcp.nixosModules.nixpkgs-search-mcp
         {
-          services.nixos-options-mcp = {
+          services.nixpkgs-search = {
             enable = true;
             indexOnStart = [ "nixos-unstable" ];
+            # Both options and packages servers are enabled by default
           };
         }
       ];
@@ -239,6 +302,19 @@ NixOS modules are provided for running both MCP servers as systemd services.
 }
 ```
 
+**Options-only configuration:**
+
+```nix
+{
+  services.nixpkgs-search = {
+    enable = true;
+    indexOnStart = [ "nixos-unstable" ];
+    indexFlags = [ "--no-packages" ];  # Faster indexing
+    packages.enable = false;  # Don't run packages server
+  };
+}
+```
+
 ### hm-options
 
 ```nix
@@ -262,9 +338,60 @@ NixOS modules are provided for running both MCP servers as systemd services.
 }
 ```
 
+### nixos-options (Legacy)
+
+```nix
+{
+  inputs.labmcp.url = "git+https://git.t-juice.club/torjus/labmcp";
+
+  outputs = { self, nixpkgs, labmcp }: {
+    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        labmcp.nixosModules.nixos-options-mcp
+        {
+          services.nixos-options-mcp = {
+            enable = true;
+            indexOnStart = [ "nixos-unstable" ];
+          };
+        }
+      ];
+    };
+  };
+}
+```
+
 ### Module Options
 
-Both modules have similar options. Shown here for `nixos-options-mcp` (replace with `hm-options-mcp` for Home Manager):
+#### nixpkgs-search
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enable` | bool | `false` | Enable the service |
+| `package` | package | from flake | Package to use |
+| `database.type` | enum | `"sqlite"` | `"sqlite"` or `"postgres"` |
+| `database.name` | string | `"nixpkgs-search.db"` | SQLite database filename |
+| `database.connectionString` | string | `""` | PostgreSQL connection URL (stored in Nix store) |
+| `database.connectionStringFile` | path | `null` | Path to file with PostgreSQL connection URL (recommended for secrets) |
+| `indexOnStart` | list of string | `[]` | Revisions to index on service start |
+| `indexFlags` | list of string | `[]` | Additional flags for indexing (e.g., `["--no-packages"]`) |
+| `user` | string | `"nixpkgs-search"` | User to run the service as |
+| `group` | string | `"nixpkgs-search"` | Group to run the service as |
+| `dataDir` | path | `/var/lib/nixpkgs-search` | Directory for data storage |
+| `options.enable` | bool | `true` | Enable the options MCP server |
+| `options.http.address` | string | `"127.0.0.1:8082"` | HTTP listen address for options server |
+| `options.openFirewall` | bool | `false` | Open firewall for options HTTP port |
+| `packages.enable` | bool | `true` | Enable the packages MCP server |
+| `packages.http.address` | string | `"127.0.0.1:8083"` | HTTP listen address for packages server |
+| `packages.openFirewall` | bool | `false` | Open firewall for packages HTTP port |
+
+Both `options.http` and `packages.http` also support:
+- `endpoint` (default: `"/mcp"`)
+- `allowedOrigins` (default: `[]`)
+- `sessionTTL` (default: `"30m"`)
+- `tls.enable`, `tls.certFile`, `tls.keyFile`
+
+#### hm-options-mcp / nixos-options-mcp (Legacy)
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
@@ -293,18 +420,18 @@ Using `connectionStringFile` (recommended for production with sensitive credenti
 
 ```nix
 {
-  services.nixos-options-mcp = {
+  services.nixpkgs-search = {
     enable = true;
     database = {
       type = "postgres";
-      # File contains: postgres://user:secret@localhost/nixos_options?sslmode=disable
-      connectionStringFile = "/run/secrets/nixos-options-db";
+      # File contains: postgres://user:secret@localhost/nixpkgs_search?sslmode=disable
+      connectionStringFile = "/run/secrets/nixpkgs-search-db";
     };
     indexOnStart = [ "nixos-unstable" ];
   };
 
   # Example with agenix or sops-nix for secret management
-  # age.secrets.nixos-options-db.file = ./secrets/nixos-options-db.age;
+  # age.secrets.nixpkgs-search-db.file = ./secrets/nixpkgs-search-db.age;
 }
 ```
 
@@ -321,7 +448,7 @@ go test ./...
 go test -bench=. ./internal/database/...
 
 # Build
-go build ./cmd/nixos-options
+go build ./cmd/nixpkgs-search
 go build ./cmd/hm-options
 ```