torjus/labmcp
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README for nixpkgs-search as primary server

Browse Source 
- Document nixpkgs-search as the primary MCP server
- Add package search CLI examples and MCP tools
- Update installation and usage examples
- Add nixpkgs-search-mcp NixOS module documentation
- Mark nixos-options as legacy
- Update environment variable documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Torjus Håkestad
2026-02-04 17:30:25 +01:00
parent 3625a8dfc3
commit 75addb5a28
1 changed files with 176 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

225
README.md
View File

@@ -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
```