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 ## 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`) ### 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. 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 ### Shared Features
- Full-text search across option names and descriptions - Full-text search across option/package names and descriptions
- Query specific options with type, default, example, and declarations - Query specific options/packages with full metadata
- Index multiple revisions (by git hash or channel name) - Index multiple revisions (by git hash or channel name)
- Fetch module source files - Fetch module source files
- Support for PostgreSQL and SQLite backends - Support for PostgreSQL and SQLite backends
@@ -26,18 +34,18 @@ Search and query Home Manager configuration options across multiple home-manager
```bash ```bash
# Build the packages # 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 nix build git+https://git.t-juice.club/torjus/labmcp#hm-options
# Or run directly # 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 nix run git+https://git.t-juice.club/torjus/labmcp#hm-options -- --help
``` ```
### From Source ### From Source
```bash ```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 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 ```json
{ {
"mcpServers": { "mcpServers": {
"nixos-options": { "nixpkgs-options": {
"command": "nixos-options", "command": "nixpkgs-search",
"args": ["serve"], "args": ["options", "serve"],
"env": { "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": { "hm-options": {
@@ -73,11 +88,18 @@ Alternatively, if you have Nix installed, you can use the flake directly without
```json ```json
{ {
"mcpServers": { "mcpServers": {
"nixos-options": { "nixpkgs-options": {
"command": "nix", "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": { "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": { "hm-options": {
@@ -93,20 +115,21 @@ Alternatively, if you have Nix installed, you can use the flake directly without
### As MCP Server (HTTP) ### 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 ```bash
# Start HTTP server on default address (127.0.0.1:8080) # 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 hm-options serve --transport http
# Custom address and CORS configuration # Custom address and CORS configuration
nixos-options serve --transport http \ nixpkgs-search options serve --transport http \
--http-address 0.0.0.0:8080 \ --http-address 0.0.0.0:8080 \
--allowed-origins https://example.com --allowed-origins https://example.com
# With TLS # With TLS
nixos-options serve --transport http \ nixpkgs-search options serve --transport http \
--tls-cert /path/to/cert.pem \ --tls-cert /path/to/cert.pem \
--tls-key /path/to/key.pem --tls-key /path/to/key.pem
``` ```
@@ -118,53 +141,77 @@ HTTP transport endpoints:
### CLI Examples ### CLI Examples
**Index a revision:** **Index a revision (nixpkgs-search):**
```bash ```bash
# NixOS options - index by channel name # Index both options and packages
nixos-options index nixos-unstable nixpkgs-search index nixos-unstable
# Home Manager options - index by channel name
hm-options index hm-unstable
# Index by git hash # 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) # 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 hm-options index --no-files release-24.11
``` ```
**List indexed revisions:** **List indexed revisions:**
```bash ```bash
nixos-options list nixpkgs-search list
hm-options list hm-options list
``` ```
**Search for options:** **Search for options:**
```bash ```bash
# NixOS options # NixOS options via nixpkgs-search
nixos-options search nginx nixpkgs-search options search nginx
nixos-options search -n 10 postgresql nixpkgs-search options search -n 10 postgresql
# Home Manager options # Home Manager options
hm-options search git hm-options search git
hm-options search -n 10 neovim hm-options search -n 10 neovim
``` ```
**Get option details:** **Search for packages:**
```bash ```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 hm-options get programs.git.enable
``` ```
**Delete an indexed revision:** **Delete an indexed revision:**
```bash ```bash
nixos-options delete nixos-23.11 nixpkgs-search delete nixos-23.11
hm-options delete release-23.11 hm-options delete release-23.11
``` ```
@@ -174,20 +221,21 @@ hm-options delete release-23.11
| Variable | Description | Default | | 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` | | `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 ### Database Connection Strings
**SQLite:** **SQLite:**
```bash ```bash
export NIXOS_OPTIONS_DATABASE="sqlite:///path/to/database.db" export NIXPKGS_SEARCH_DATABASE="sqlite:///path/to/database.db"
export NIXOS_OPTIONS_DATABASE="sqlite://:memory:" # In-memory export NIXPKGS_SEARCH_DATABASE="sqlite://:memory:" # In-memory
``` ```
**PostgreSQL:** **PostgreSQL:**
```bash ```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 ### 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: The database can also be specified via the `-d` or `--database` flag:
```bash ```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 hm-options -d "sqlite://my.db" index hm-unstable
``` ```
## MCP Tools ## MCP Tools
Both servers provide the following tools: ### Options Servers (nixpkgs-search options, hm-options)
| Tool | Description | | Tool | Description |
|------|-------------| |------|-------------|
@@ -212,11 +261,24 @@ Both servers provide the following tools:
| `list_revisions` | List all indexed revisions | | `list_revisions` | List all indexed revisions |
| `delete_revision` | Delete an indexed revision | | `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
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 ```nix
{ {
@@ -226,11 +288,12 @@ NixOS modules are provided for running both MCP servers as systemd services.
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem { nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
system = "x86_64-linux"; system = "x86_64-linux";
modules = [ modules = [
labmcp.nixosModules.nixos-options-mcp labmcp.nixosModules.nixpkgs-search-mcp
{ {
services.nixos-options-mcp = { services.nixpkgs-search = {
enable = true; enable = true;
indexOnStart = [ "nixos-unstable" ]; 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 ### hm-options
```nix ```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 ### 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 | | Option | Type | Default | Description |
|--------|------|---------|-------------| |--------|------|---------|-------------|
@@ -293,18 +420,18 @@ Using `connectionStringFile` (recommended for production with sensitive credenti
```nix ```nix
{ {
services.nixos-options-mcp = { services.nixpkgs-search = {
enable = true; enable = true;
database = { database = {
type = "postgres"; type = "postgres";
# File contains: postgres://user:secret@localhost/nixos_options?sslmode=disable # File contains: postgres://user:secret@localhost/nixpkgs_search?sslmode=disable
connectionStringFile = "/run/secrets/nixos-options-db"; connectionStringFile = "/run/secrets/nixpkgs-search-db";
}; };
indexOnStart = [ "nixos-unstable" ]; indexOnStart = [ "nixos-unstable" ];
}; };
# Example with agenix or sops-nix for secret management # 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/... go test -bench=. ./internal/database/...
# Build # Build
go build ./cmd/nixos-options go build ./cmd/nixpkgs-search
go build ./cmd/hm-options go build ./cmd/hm-options
``` ```