feat: add nixpkgs-search binary with package search support
Add a new nixpkgs-search CLI that combines NixOS options search with Nix package search functionality. This provides two MCP servers from a single binary: - `nixpkgs-search options serve` for NixOS options - `nixpkgs-search packages serve` for Nix packages Key changes: - Add packages table to database schema (version 3) - Add Package type and search methods to database layer - Create internal/packages/ with indexer and parser for nix-env JSON - Add MCP server mode (options/packages) with separate tool sets - Add package handlers: search_packages, get_package - Create cmd/nixpkgs-search with combined indexing support - Update flake.nix with nixpkgs-search package (now default) - Bump version to 0.2.0 The index command can index both options and packages together, or use --no-packages/--no-options flags for partial indexing. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
98
CLAUDE.md
98
CLAUDE.md
@@ -8,15 +8,21 @@ This file provides context for Claude when working on this project.
|
||||
|
||||
## MCP Servers
|
||||
|
||||
### NixOS Options (`nixos-options`)
|
||||
### Nixpkgs Search (`nixpkgs-search`) - **Primary**
|
||||
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`)
|
||||
|
||||
### NixOS Options (`nixos-options`) - Legacy
|
||||
Search and query NixOS configuration options. Uses nixpkgs as source.
|
||||
*Note: Prefer using `nixpkgs-search options` instead.*
|
||||
|
||||
### Home Manager Options (`hm-options`)
|
||||
Search and query Home Manager configuration options. Uses home-manager repository as source.
|
||||
|
||||
Both servers share the same architecture:
|
||||
- Full-text search across option names and descriptions
|
||||
- Query specific options with type, default, example, and declarations
|
||||
All servers share the same architecture:
|
||||
- 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
|
||||
- PostgreSQL and SQLite backends
|
||||
@@ -43,20 +49,22 @@ Both servers share the same architecture:
|
||||
```
|
||||
labmcp/
|
||||
├── cmd/
|
||||
│ ├── nixpkgs-search/
|
||||
│ │ └── main.go # Combined options+packages CLI (primary)
|
||||
│ ├── nixos-options/
|
||||
│ │ └── main.go # NixOS options CLI
|
||||
│ │ └── main.go # NixOS options CLI (legacy)
|
||||
│ └── hm-options/
|
||||
│ └── main.go # Home Manager options CLI
|
||||
├── internal/
|
||||
│ ├── database/
|
||||
│ │ ├── interface.go # Store interface
|
||||
│ │ ├── interface.go # Store interface (options + packages)
|
||||
│ │ ├── schema.go # Schema versioning
|
||||
│ │ ├── postgres.go # PostgreSQL implementation
|
||||
│ │ ├── sqlite.go # SQLite implementation
|
||||
│ │ └── *_test.go # Database tests
|
||||
│ ├── mcp/
|
||||
│ │ ├── server.go # MCP server core + ServerConfig
|
||||
│ │ ├── handlers.go # Tool implementations
|
||||
│ │ ├── server.go # MCP server core + ServerConfig + modes
|
||||
│ │ ├── handlers.go # Tool implementations (options + packages)
|
||||
│ │ ├── types.go # Protocol types
|
||||
│ │ ├── transport.go # Transport interface
|
||||
│ │ ├── transport_stdio.go # STDIO transport
|
||||
@@ -66,14 +74,19 @@ labmcp/
|
||||
│ ├── options/
|
||||
│ │ └── indexer.go # Shared Indexer interface
|
||||
│ ├── nixos/
|
||||
│ │ ├── indexer.go # Nixpkgs indexing
|
||||
│ │ ├── parser.go # options.json parsing (shared)
|
||||
│ │ ├── indexer.go # NixOS options indexing
|
||||
│ │ ├── parser.go # options.json parsing
|
||||
│ │ ├── types.go # Channel aliases, extensions
|
||||
│ │ └── *_test.go # Indexer tests
|
||||
│ └── homemanager/
|
||||
│ ├── indexer.go # Home Manager indexing
|
||||
│ ├── types.go # Channel aliases, extensions
|
||||
│ └── *_test.go # Indexer tests
|
||||
│ ├── homemanager/
|
||||
│ │ ├── indexer.go # Home Manager indexing
|
||||
│ │ ├── types.go # Channel aliases, extensions
|
||||
│ │ └── *_test.go # Indexer tests
|
||||
│ └── packages/
|
||||
│ ├── indexer.go # Nix packages indexing
|
||||
│ ├── parser.go # nix-env JSON parsing
|
||||
│ ├── types.go # Package types, channel aliases
|
||||
│ └── *_test.go # Parser tests
|
||||
├── nix/
|
||||
│ ├── module.nix # NixOS module for nixos-options
|
||||
│ ├── hm-options-module.nix # NixOS module for hm-options
|
||||
@@ -90,7 +103,7 @@ labmcp/
|
||||
|
||||
## MCP Tools
|
||||
|
||||
Both servers provide the same 6 tools:
|
||||
### Options Servers (nixpkgs-search options, nixos-options, hm-options)
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
@@ -101,6 +114,16 @@ Both servers provide the same 6 tools:
|
||||
| `list_revisions` | List all indexed revisions |
|
||||
| `delete_revision` | Delete an indexed revision |
|
||||
|
||||
### Packages Server (nixpkgs-search packages)
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `search_packages` | Full-text search across package names and descriptions |
|
||||
| `get_package` | Get full details for a specific package by attr path |
|
||||
| `get_file` | Fetch source file contents from nixpkgs |
|
||||
| `list_revisions` | List all indexed revisions |
|
||||
| `delete_revision` | Delete an indexed revision |
|
||||
|
||||
## Key Implementation Details
|
||||
|
||||
### Database
|
||||
@@ -136,7 +159,32 @@ Both servers provide the same 6 tools:
|
||||
|
||||
## CLI Commands
|
||||
|
||||
### nixos-options
|
||||
### nixpkgs-search (Primary)
|
||||
```bash
|
||||
# Options MCP Server
|
||||
nixpkgs-search options serve # Run options MCP server on STDIO
|
||||
nixpkgs-search options search <query> # Search options
|
||||
nixpkgs-search options get <option> # Get option details
|
||||
|
||||
# Packages MCP Server
|
||||
nixpkgs-search packages serve # Run packages MCP server on STDIO
|
||||
nixpkgs-search packages search <query> # Search packages
|
||||
nixpkgs-search packages get <attr> # Get package details
|
||||
|
||||
# Combined Indexing
|
||||
nixpkgs-search index <revision> # Index options AND packages
|
||||
nixpkgs-search index --no-packages <r> # Index options only (faster)
|
||||
nixpkgs-search index --no-options <r> # Index packages only
|
||||
nixpkgs-search index --no-files <r> # Skip file indexing
|
||||
nixpkgs-search index --force <r> # Force re-index
|
||||
|
||||
# Shared Commands
|
||||
nixpkgs-search list # List indexed revisions
|
||||
nixpkgs-search delete <revision> # Delete indexed revision
|
||||
nixpkgs-search --version # Show version
|
||||
```
|
||||
|
||||
### nixos-options (Legacy)
|
||||
```bash
|
||||
nixos-options serve # Run MCP server on STDIO (default)
|
||||
nixos-options serve --transport http # Run MCP server on HTTP
|
||||
@@ -166,7 +214,7 @@ hm-options --version # Show version
|
||||
|
||||
### Channel Aliases
|
||||
|
||||
**nixos-options**: `nixos-unstable`, `nixos-stable`, `nixos-24.11`, `nixos-24.05`, etc.
|
||||
**nixpkgs-search/nixos-options**: `nixos-unstable`, `nixos-stable`, `nixos-24.11`, `nixos-24.05`, etc.
|
||||
|
||||
**hm-options**: `hm-unstable`, `hm-stable`, `master`, `release-24.11`, `release-24.05`, etc.
|
||||
|
||||
@@ -204,9 +252,10 @@ Version bumps should be done once per feature branch, not per commit. Rules:
|
||||
- **Major bump** (0.1.0 → 1.0.0): Breaking changes to CLI usage or MCP protocol
|
||||
|
||||
Version is defined in multiple places that must stay in sync:
|
||||
- `cmd/nixpkgs-search/main.go`
|
||||
- `cmd/nixos-options/main.go`
|
||||
- `cmd/hm-options/main.go`
|
||||
- `internal/mcp/server.go` (in `DefaultNixOSConfig` and `DefaultHomeManagerConfig`)
|
||||
- `internal/mcp/server.go` (in `DefaultNixOSConfig`, `DefaultHomeManagerConfig`, `DefaultNixpkgsPackagesConfig`)
|
||||
- `nix/package.nix`
|
||||
|
||||
### User Preferences
|
||||
@@ -230,19 +279,24 @@ nix develop -c go test -bench=. -benchtime=1x -timeout=30m ./internal/homemanage
|
||||
### Building
|
||||
```bash
|
||||
# Build with nix
|
||||
nix build .#nixpkgs-search
|
||||
nix build .#nixos-options
|
||||
nix build .#hm-options
|
||||
|
||||
# Run directly
|
||||
nix run .#nixos-options -- serve
|
||||
nix run .#nixpkgs-search -- options serve
|
||||
nix run .#nixpkgs-search -- packages serve
|
||||
nix run .#nixpkgs-search -- index nixos-unstable
|
||||
nix run .#hm-options -- serve
|
||||
nix run .#nixos-options -- index nixos-unstable
|
||||
nix run .#hm-options -- index hm-unstable
|
||||
```
|
||||
|
||||
### Indexing Performance
|
||||
Indexing operations are slow due to Nix evaluation and file downloads. When running index commands, use appropriate timeouts:
|
||||
- **nixos-options**: ~5-6 minutes for `nixos-unstable` (with files)
|
||||
- **nixpkgs-search (full)**: ~15-20 minutes for `nixos-unstable` (options + packages + files)
|
||||
- **nixpkgs-search (options only)**: ~5-6 minutes with `--no-packages`
|
||||
- **nixpkgs-search (packages only)**: ~10-15 minutes with `--no-options`
|
||||
- **hm-options**: ~1-2 minutes for `master` (with files)
|
||||
|
||||
Use `--no-files` flag for faster indexing (~1-2 minutes) if file content lookup isn't needed.
|
||||
Use `--no-files` flag to skip file indexing for faster results.
|
||||
Use `--no-packages` to index only options (matches legacy behavior).
|
||||
|
||||
Reference in New Issue
Block a user