docs: update README and CLAUDE.md for hm-options, bump version to 0.1.1

- Add hm-options documentation to README.md
- Update CLAUDE.md with hm-options info, repository structure
- Add note about git-tracking new files before nix build/run
- Add version bump rules documentation
- Bump version from 0.1.0 to 0.1.1 (patch bump for internal/ changes)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-02-03 23:03:36 +01:00
parent ea2d73d746
commit 11935db702
6 changed files with 181 additions and 87 deletions

101
CLAUDE.md
View File

@@ -6,9 +6,20 @@ This file provides context for Claude when working on this project.
**LabMCP** is a collection of Model Context Protocol (MCP) servers written in Go, designed to extend Claude's capabilities with custom tools. The repository is structured to be generic and extensible, allowing multiple MCP servers to be added over time. **LabMCP** is a collection of Model Context Protocol (MCP) servers written in Go, designed to extend Claude's capabilities with custom tools. The repository is structured to be generic and extensible, allowing multiple MCP servers to be added over time.
## Current Focus: NixOS Options MCP Server ## MCP Servers
The first MCP server provides search and query capabilities for NixOS configuration options. This addresses the challenge of incomplete or hard-to-find documentation in the Nix ecosystem. ### NixOS Options (`nixos-options`)
Search and query NixOS configuration options. Uses nixpkgs as source.
### 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
- Index multiple revisions (by git hash or channel name)
- Fetch module source files
- PostgreSQL and SQLite backends
## Technology Stack ## Technology Stack
@@ -21,9 +32,9 @@ The first MCP server provides search and query capabilities for NixOS configurat
## Project Status ## Project Status
**Complete and maintained** - All core features implemented: **Complete and maintained** - All core features implemented:
- Full MCP server with 6 tools - Full MCP servers with 6 tools each
- PostgreSQL and SQLite backends with FTS - PostgreSQL and SQLite backends with FTS
- NixOS module for deployment - NixOS modules for deployment
- CLI for manual operations - CLI for manual operations
- Comprehensive test suite - Comprehensive test suite
@@ -32,8 +43,10 @@ The first MCP server provides search and query capabilities for NixOS configurat
``` ```
labmcp/ labmcp/
├── cmd/ ├── cmd/
── nixos-options/ ── nixos-options/
└── main.go # CLI entry point └── main.go # NixOS options CLI
│ └── hm-options/
│ └── main.go # Home Manager options CLI
├── internal/ ├── internal/
│ ├── database/ │ ├── database/
│ │ ├── interface.go # Store interface │ │ ├── interface.go # Store interface
@@ -42,7 +55,7 @@ labmcp/
│ │ ├── sqlite.go # SQLite implementation │ │ ├── sqlite.go # SQLite implementation
│ │ └── *_test.go # Database tests │ │ └── *_test.go # Database tests
│ ├── mcp/ │ ├── mcp/
│ │ ├── server.go # MCP server core │ │ ├── server.go # MCP server core + ServerConfig
│ │ ├── handlers.go # Tool implementations │ │ ├── handlers.go # Tool implementations
│ │ ├── types.go # Protocol types │ │ ├── types.go # Protocol types
│ │ ├── transport.go # Transport interface │ │ ├── transport.go # Transport interface
@@ -50,14 +63,21 @@ labmcp/
│ │ ├── transport_http.go # HTTP/SSE transport │ │ ├── transport_http.go # HTTP/SSE transport
│ │ ├── session.go # HTTP session management │ │ ├── session.go # HTTP session management
│ │ └── *_test.go # MCP tests │ │ └── *_test.go # MCP tests
── nixos/ ── options/
── indexer.go # Nixpkgs indexing ── indexer.go # Shared Indexer interface
├── parser.go # options.json parsing ├── nixos/
│ │ ├── indexer.go # Nixpkgs indexing
│ │ ├── parser.go # options.json parsing (shared)
│ │ ├── types.go # Channel aliases, extensions
│ │ └── *_test.go # Indexer tests
│ └── homemanager/
│ ├── indexer.go # Home Manager indexing
│ ├── types.go # Channel aliases, extensions │ ├── types.go # Channel aliases, extensions
│ └── *_test.go # Indexer tests │ └── *_test.go # Indexer tests
├── nix/ ├── nix/
│ ├── module.nix # NixOS module │ ├── module.nix # NixOS module for nixos-options
── package.nix # Nix package definition ── hm-options-module.nix # NixOS module for hm-options
│ └── package.nix # Parameterized Nix package
├── testdata/ ├── testdata/
│ └── options-sample.json # Test fixture │ └── options-sample.json # Test fixture
├── flake.nix ├── flake.nix
@@ -70,14 +90,14 @@ labmcp/
## MCP Tools ## MCP Tools
All tools are implemented and functional: Both servers provide the same 6 tools:
| Tool | Description | | Tool | Description |
|------|-------------| |------|-------------|
| `search_options` | Full-text search across option names and descriptions | | `search_options` | Full-text search across option names and descriptions |
| `get_option` | Get full details for a specific option with children | | `get_option` | Get full details for a specific option with children |
| `get_file` | Fetch source file contents from indexed nixpkgs | | `get_file` | Fetch source file contents from indexed repository |
| `index_revision` | Index a nixpkgs revision (by hash or channel name) | | `index_revision` | Index a revision (by hash or channel name) |
| `list_revisions` | List all indexed revisions | | `list_revisions` | List all indexed revisions |
| `delete_revision` | Delete an indexed revision | | `delete_revision` | Delete an indexed revision |
@@ -90,7 +110,7 @@ All tools are implemented and functional:
- Batch operations for efficient indexing - Batch operations for efficient indexing
### Indexing ### Indexing
- Uses `nix-build` to evaluate NixOS options from any nixpkgs revision - Uses `nix-build` to evaluate options from any revision
- File indexing downloads tarball and stores allowed extensions (.nix, .json, .md, etc.) - File indexing downloads tarball and stores allowed extensions (.nix, .json, .md, etc.)
- File indexing enabled by default (use `--no-files` to skip) - File indexing enabled by default (use `--no-files` to skip)
- Skips already-indexed revisions (use `--force` to re-index) - Skips already-indexed revisions (use `--force` to re-index)
@@ -116,12 +136,10 @@ All tools are implemented and functional:
## CLI Commands ## CLI Commands
### nixos-options
```bash ```bash
nixos-options serve # Run MCP server on STDIO (default) nixos-options serve # Run MCP server on STDIO (default)
nixos-options serve --transport http # Run MCP server on HTTP nixos-options serve --transport http # Run MCP server on HTTP
nixos-options serve --transport http \
--http-address 0.0.0.0:8080 \
--allowed-origins https://example.com # HTTP with custom config
nixos-options index <revision> # Index a nixpkgs revision nixos-options index <revision> # Index a nixpkgs revision
nixos-options index --force <r> # Force re-index existing revision nixos-options index --force <r> # Force re-index existing revision
nixos-options index --no-files # Skip file content indexing nixos-options index --no-files # Skip file content indexing
@@ -132,6 +150,26 @@ nixos-options delete <revision> # Delete indexed revision
nixos-options --version # Show version nixos-options --version # Show version
``` ```
### hm-options
```bash
hm-options serve # Run MCP server on STDIO (default)
hm-options serve --transport http # Run MCP server on HTTP
hm-options index <revision> # Index a home-manager revision
hm-options index --force <r> # Force re-index existing revision
hm-options index --no-files # Skip file content indexing
hm-options list # List indexed revisions
hm-options search <query> # Search options
hm-options get <option> # Get option details
hm-options delete <revision> # Delete indexed revision
hm-options --version # Show version
```
### Channel Aliases
**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.
## Notes for Claude ## Notes for Claude
### Development Workflow ### Development Workflow
@@ -140,6 +178,21 @@ nixos-options --version # Show version
- **Use `nix run` to run binaries** (e.g., `nix run .#nixos-options -- serve`) - **Use `nix run` to run binaries** (e.g., `nix run .#nixos-options -- serve`)
- File paths in responses should use format `path/to/file.go:123` - File paths in responses should use format `path/to/file.go:123`
### Nix Build Requirement
**IMPORTANT**: When running `nix build`, `nix run`, or similar commands, new files must be tracked by git first. Nix flakes only see git-tracked files. If you create new files, run `git add <file>` before attempting nix operations.
### Version Bumping
Version bumps should be done once per feature branch, not per commit. Rules:
- **Patch bump** (0.1.0 → 0.1.1): Changes to Go code within `internal/` that affect a program
- **Minor bump** (0.1.0 → 0.2.0): Changes to Go code outside `internal/` (e.g., `cmd/`)
- **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/nixos-options/main.go`
- `cmd/hm-options/main.go`
- `internal/mcp/server.go` (in `DefaultNixOSConfig` and `DefaultHomeManagerConfig`)
- `nix/package.nix`
### User Preferences ### User Preferences
- User prefers PostgreSQL over SQLite (has homelab infrastructure) - User prefers PostgreSQL over SQLite (has homelab infrastructure)
- User values good test coverage and benchmarking - User values good test coverage and benchmarking
@@ -155,14 +208,18 @@ nix develop -c go test ./... -v
# Run benchmarks (requires nix-build) # Run benchmarks (requires nix-build)
nix develop -c go test -bench=. -benchtime=1x -timeout=30m ./internal/nixos/... nix develop -c go test -bench=. -benchtime=1x -timeout=30m ./internal/nixos/...
nix develop -c go test -bench=. -benchtime=1x -timeout=30m ./internal/homemanager/...
``` ```
### Building ### Building
```bash ```bash
# Build with nix # Build with nix
nix build nix build .#nixos-options
nix build .#hm-options
# Run directly # Run directly
nix run . -- serve nix run .#nixos-options -- serve
nix run . -- index nixos-unstable nix run .#hm-options -- serve
nix run .#nixos-options -- index nixos-unstable
nix run .#hm-options -- index hm-unstable
``` ```

157
README.md
View File

@@ -2,16 +2,22 @@
A collection of Model Context Protocol (MCP) servers written in Go. A collection of Model Context Protocol (MCP) servers written in Go.
## NixOS Options MCP Server ## MCP Servers
### NixOS Options (`nixos-options`)
Search and query NixOS configuration options across multiple nixpkgs revisions. Designed to help Claude (and other MCP clients) answer questions about NixOS configuration. Search and query NixOS configuration options across multiple nixpkgs revisions. Designed to help Claude (and other MCP clients) answer questions about NixOS configuration.
### Features ### 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.
### Shared Features
- Full-text search across option names and descriptions - Full-text search across option names and descriptions
- Query specific options with type, default, example, and declarations - Query specific options with type, default, example, and declarations
- Index multiple nixpkgs revisions (by git hash or channel name) - Index multiple revisions (by git hash or channel name)
- Fetch nixpkgs module source files - Fetch module source files
- Support for PostgreSQL and SQLite backends - Support for PostgreSQL and SQLite backends
## Installation ## Installation
@@ -19,17 +25,20 @@ Search and query NixOS configuration options across multiple nixpkgs revisions.
### Using Nix Flakes ### Using Nix Flakes
```bash ```bash
# Build the package # Build the packages
nix build git+https://git.t-juice.club/torjus/labmcp nix build git+https://git.t-juice.club/torjus/labmcp#nixos-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 -- --help nix run git+https://git.t-juice.club/torjus/labmcp#nixos-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/nixos-options@latest
go install git.t-juice.club/torjus/labmcp/cmd/hm-options@latest
``` ```
## Usage ## Usage
@@ -47,40 +56,49 @@ Configure in your MCP client (e.g., Claude Desktop):
"env": { "env": {
"NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db" "NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
} }
} },
} "hm-options": {
} "command": "hm-options",
``` "args": ["serve"],
Alternatively, if you have Nix installed, you can use the flake directly without installing the package:
```json
{
"mcpServers": {
"nixos-options": {
"command": "nix",
"args": ["run", "git+https://git.t-juice.club/torjus/labmcp", "--", "serve"],
"env": { "env": {
"NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db" "HM_OPTIONS_DATABASE": "sqlite:///path/to/hm-options.db"
} }
} }
} }
} }
``` ```
Then start the server: Alternatively, if you have Nix installed, you can use the flake directly without installing the packages:
```bash ```json
nixos-options serve {
"mcpServers": {
"nixos-options": {
"command": "nix",
"args": ["run", "git+https://git.t-juice.club/torjus/labmcp#nixos-options", "--", "serve"],
"env": {
"NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
}
},
"hm-options": {
"command": "nix",
"args": ["run", "git+https://git.t-juice.club/torjus/labmcp#hm-options", "--", "serve"],
"env": {
"HM_OPTIONS_DATABASE": "sqlite:///path/to/hm-options.db"
}
}
}
}
``` ```
### As MCP Server (HTTP) ### As MCP Server (HTTP)
The server can also run over HTTP with Server-Sent Events (SSE) for web-based MCP clients: Both 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 nixos-options serve --transport http
hm-options serve --transport http
# Custom address and CORS configuration # Custom address and CORS configuration
nixos-options serve --transport http \ nixos-options serve --transport http \
@@ -100,49 +118,54 @@ HTTP transport endpoints:
### CLI Examples ### CLI Examples
**Index a nixpkgs revision:** **Index a revision:**
```bash ```bash
# Index by channel name (includes file contents by default) # NixOS options - index by channel name
nixos-options index nixos-unstable nixos-options 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 nixos-options index e6eae2ee2110f3d31110d5c222cd395303343b08
# 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 nixos-options index --no-files nixos-unstable
hm-options index --no-files release-24.11
``` ```
**List indexed revisions:** **List indexed revisions:**
```bash ```bash
nixos-options list nixos-options list
hm-options list
``` ```
**Search for options:** **Search for options:**
```bash ```bash
# Basic search # NixOS options
nixos-options search nginx nixos-options search nginx
# Limit results
nixos-options search -n 10 postgresql nixos-options search -n 10 postgresql
# Search in specific revision # Home Manager options
nixos-options search -r nixos-unstable firewall hm-options search git
hm-options search -n 10 neovim
``` ```
**Get option details:** **Get option details:**
```bash ```bash
nixos-options get services.nginx.enable nixos-options get services.nginx.enable
nixos-options get services.postgresql.package hm-options get programs.git.enable
``` ```
**Delete an indexed revision:** **Delete an indexed revision:**
```bash ```bash
nixos-options delete nixos-23.11 nixos-options delete nixos-23.11
hm-options delete release-23.11
``` ```
## Configuration ## Configuration
@@ -151,7 +174,8 @@ nixos-options delete nixos-23.11
| Variable | Description | Default | | Variable | Description | Default |
|----------|-------------|---------| |----------|-------------|---------|
| `NIXOS_OPTIONS_DATABASE` | Database connection string | `sqlite://nixos-options.db` | | `NIXOS_OPTIONS_DATABASE` | Database connection string for nixos-options | `sqlite://nixos-options.db` |
| `HM_OPTIONS_DATABASE` | Database connection string for hm-options | `sqlite://hm-options.db` |
### Database Connection Strings ### Database Connection Strings
@@ -172,25 +196,27 @@ The database can also be specified via the `-d` or `--database` flag:
```bash ```bash
nixos-options -d "postgres://localhost/nixos" serve nixos-options -d "postgres://localhost/nixos" serve
nixos-options -d "sqlite://my.db" index nixos-unstable hm-options -d "sqlite://my.db" index hm-unstable
``` ```
## MCP Tools ## MCP Tools
When running as an MCP server, the following tools are available: Both servers provide the following tools:
| Tool | Description | | Tool | Description |
|------|-------------| |------|-------------|
| `search_options` | Search for options by name or description | | `search_options` | Search for options by name or description |
| `get_option` | Get full details for a specific option | | `get_option` | Get full details for a specific option |
| `get_file` | Fetch source file contents from nixpkgs | | `get_file` | Fetch source file contents from the repository |
| `index_revision` | Index a nixpkgs revision | | `index_revision` | Index a revision |
| `list_revisions` | List all indexed revisions | | `list_revisions` | List all indexed revisions |
| `delete_revision` | Delete an indexed revision | | `delete_revision` | Delete an indexed revision |
## NixOS Module ## NixOS Modules
A NixOS module is provided for running the MCP server as a systemd service. NixOS modules are provided for running both MCP servers as systemd services.
### nixos-options
```nix ```nix
{ {
@@ -213,21 +239,46 @@ A NixOS module is provided for running the MCP server as a systemd service.
} }
``` ```
### hm-options
```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.hm-options-mcp
{
services.hm-options-mcp = {
enable = true;
indexOnStart = [ "hm-unstable" ];
};
}
];
};
};
}
```
### Module Options ### Module Options
Both modules have similar options. Shown here for `nixos-options-mcp` (replace with `hm-options-mcp` for Home Manager):
| Option | Type | Default | Description | | Option | Type | Default | Description |
|--------|------|---------|-------------| |--------|------|---------|-------------|
| `enable` | bool | `false` | Enable the service | | `enable` | bool | `false` | Enable the service |
| `package` | package | from flake | Package to use | | `package` | package | from flake | Package to use |
| `database.type` | enum | `"sqlite"` | `"sqlite"` or `"postgres"` | | `database.type` | enum | `"sqlite"` | `"sqlite"` or `"postgres"` |
| `database.name` | string | `"nixos-options.db"` | SQLite database filename | | `database.name` | string | `"*.db"` | SQLite database filename |
| `database.connectionString` | string | `""` | PostgreSQL connection URL (stored in Nix store) | | `database.connectionString` | string | `""` | PostgreSQL connection URL (stored in Nix store) |
| `database.connectionStringFile` | path | `null` | Path to file with PostgreSQL connection URL (recommended for secrets) | | `database.connectionStringFile` | path | `null` | Path to file with PostgreSQL connection URL (recommended for secrets) |
| `indexOnStart` | list of string | `[]` | Revisions to index on service start | | `indexOnStart` | list of string | `[]` | Revisions to index on service start |
| `user` | string | `"nixos-options-mcp"` | User to run the service as | | `user` | string | `"*-mcp"` | User to run the service as |
| `group` | string | `"nixos-options-mcp"` | Group to run the service as | | `group` | string | `"*-mcp"` | Group to run the service as |
| `dataDir` | path | `/var/lib/nixos-options-mcp` | Directory for data storage | | `dataDir` | path | `/var/lib/*-mcp` | Directory for data storage |
| `http.address` | string | `"127.0.0.1:8080"` | HTTP listen address | | `http.address` | string | `"127.0.0.1:808x"` | HTTP listen address |
| `http.endpoint` | string | `"/mcp"` | HTTP endpoint path | | `http.endpoint` | string | `"/mcp"` | HTTP endpoint path |
| `http.allowedOrigins` | list of string | `[]` | Allowed CORS origins (empty = localhost only) | | `http.allowedOrigins` | list of string | `[]` | Allowed CORS origins (empty = localhost only) |
| `http.sessionTTL` | string | `"30m"` | Session timeout (Go duration format) | | `http.sessionTTL` | string | `"30m"` | Session timeout (Go duration format) |
@@ -238,21 +289,6 @@ A NixOS module is provided for running the MCP server as a systemd service.
### PostgreSQL Example ### PostgreSQL Example
Using `connectionString` (stored in Nix store - suitable for testing or non-sensitive setups):
```nix
{
services.nixos-options-mcp = {
enable = true;
database = {
type = "postgres";
connectionString = "postgres://nixos:nixos@localhost/nixos_options?sslmode=disable";
};
indexOnStart = [ "nixos-unstable" "nixos-24.11" ];
};
}
```
Using `connectionStringFile` (recommended for production with sensitive credentials): Using `connectionStringFile` (recommended for production with sensitive credentials):
```nix ```nix
@@ -286,6 +322,7 @@ go test -bench=. ./internal/database/...
# Build # Build
go build ./cmd/nixos-options go build ./cmd/nixos-options
go build ./cmd/hm-options
``` ```
## License ## License

View File

@@ -20,7 +20,7 @@ import (
const ( const (
defaultDatabase = "sqlite://hm-options.db" defaultDatabase = "sqlite://hm-options.db"
version = "0.1.0" version = "0.1.1"
) )
func main() { func main() {

View File

@@ -19,7 +19,7 @@ import (
const ( const (
defaultDatabase = "sqlite://nixos-options.db" defaultDatabase = "sqlite://nixos-options.db"
version = "0.1.0" version = "0.1.1"
) )
func main() { func main() {

View File

@@ -28,7 +28,7 @@ type ServerConfig struct {
func DefaultNixOSConfig() ServerConfig { func DefaultNixOSConfig() ServerConfig {
return ServerConfig{ return ServerConfig{
Name: "nixos-options", Name: "nixos-options",
Version: "0.1.0", Version: "0.1.1",
DefaultChannel: "nixos-stable", DefaultChannel: "nixos-stable",
SourceName: "nixpkgs", SourceName: "nixpkgs",
Instructions: `NixOS Options MCP Server - Search and query NixOS configuration options. Instructions: `NixOS Options MCP Server - Search and query NixOS configuration options.
@@ -47,7 +47,7 @@ This ensures option documentation matches the nixpkgs version the project actual
func DefaultHomeManagerConfig() ServerConfig { func DefaultHomeManagerConfig() ServerConfig {
return ServerConfig{ return ServerConfig{
Name: "hm-options", Name: "hm-options",
Version: "0.1.0", Version: "0.1.1",
DefaultChannel: "hm-stable", DefaultChannel: "hm-stable",
SourceName: "home-manager", SourceName: "home-manager",
Instructions: `Home Manager Options MCP Server - Search and query Home Manager configuration options. Instructions: `Home Manager Options MCP Server - Search and query Home Manager configuration options.

View File

@@ -7,7 +7,7 @@
buildGoModule { buildGoModule {
inherit pname src; inherit pname src;
version = "0.1.0"; version = "0.1.1";
vendorHash = "sha256-D0KIxQC9ctIAaHBFTvkhBE06uOZwDUcIw8471Ug2doY="; vendorHash = "sha256-D0KIxQC9ctIAaHBFTvkhBE06uOZwDUcIw8471Ug2doY=";