diff --git a/README.md b/README.md index eb993f1..569b4a8 100644 --- a/README.md +++ b/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 ```