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

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

Browse Source 
- 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:
Torjus Håkestad
2026-02-03 23:03:36 +01:00
parent ea2d73d746
commit 11935db702
6 changed files with 181 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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.
## 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
@@ -21,9 +32,9 @@ The first MCP server provides search and query capabilities for NixOS configurat
## Project Status
**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
- NixOS module for deployment
- NixOS modules for deployment
- CLI for manual operations
- Comprehensive test suite
@@ -32,8 +43,10 @@ The first MCP server provides search and query capabilities for NixOS configurat
```
labmcp/
├── cmd/
│ └── nixos-options/
│ └── main.go # CLI entry point
│ ├── nixos-options/
│ │ └── main.go # NixOS options CLI
│ └── hm-options/
│ └── main.go # Home Manager options CLI
├── internal/
│ ├── database/
│ │ ├── interface.go # Store interface
@@ -42,7 +55,7 @@ labmcp/
│ │ ├── sqlite.go # SQLite implementation
│ │ └── *_test.go # Database tests
│ ├── mcp/
│ │ ├── server.go # MCP server core
│ │ ├── server.go # MCP server core + ServerConfig
│ │ ├── handlers.go # Tool implementations
│ │ ├── types.go # Protocol types
│ │ ├── transport.go # Transport interface
@@ -50,14 +63,21 @@ labmcp/
│ │ ├── transport_http.go # HTTP/SSE transport
│ │ ├── session.go # HTTP session management
│ │ └── *_test.go # MCP tests
│ └── nixos/
│ ├── indexer.go # Nixpkgs indexing
│ ├── parser.go # options.json parsing
│ ├── options/
│ │ └── indexer.go # Shared Indexer interface
│ ├── 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
│ └── *_test.go # Indexer tests
├── nix/
│ ├── module.nix # NixOS module
│ └── package.nix # Nix package definition
│ ├── module.nix # NixOS module for nixos-options
│ ├── hm-options-module.nix # NixOS module for hm-options
│ └── package.nix # Parameterized Nix package
├── testdata/
│ └── options-sample.json # Test fixture
├── flake.nix
@@ -70,14 +90,14 @@ labmcp/
## MCP Tools
All tools are implemented and functional:
Both servers provide the same 6 tools:
| Tool | Description |
|------|-------------|
| `search_options` | Full-text search across option names and descriptions |
| `get_option` | Get full details for a specific option with children |
| `get_file` | Fetch source file contents from indexed nixpkgs |
| `index_revision` | Index a nixpkgs revision (by hash or channel name) |
| `get_file` | Fetch source file contents from indexed repository |
| `index_revision` | Index a revision (by hash or channel name) |
| `list_revisions` | List all indexed revisions |
| `delete_revision` | Delete an indexed revision |
@@ -90,7 +110,7 @@ All tools are implemented and functional:
- Batch operations for efficient 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 enabled by default (use `--no-files` to skip)
- Skips already-indexed revisions (use `--force` to re-index)
@@ -116,12 +136,10 @@ All tools are implemented and functional:
## CLI Commands
### nixos-options
```bash
nixos-options serve # Run MCP server on STDIO (default)
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 --force <r> # Force re-index existing revision
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
```
### 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
### Development Workflow
@@ -140,6 +178,21 @@ nixos-options --version # Show version
- **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`
### 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 prefers PostgreSQL over SQLite (has homelab infrastructure)
- User values good test coverage and benchmarking
@@ -155,14 +208,18 @@ nix develop -c go test ./... -v
# 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/homemanager/...
```
### Building
```bash
# Build with nix
nix build
nix build .#nixos-options
nix build .#hm-options
# Run directly
nix run . -- serve
nix run . -- index nixos-unstable
nix run .#nixos-options -- serve
nix run .#hm-options -- serve
nix run .#nixos-options -- index nixos-unstable
nix run .#hm-options -- index hm-unstable
```

139
README.md
View File

@@ -2,16 +2,22 @@
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.
### 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
- Query specific options with type, default, example, and declarations
- Index multiple nixpkgs revisions (by git hash or channel name)
- Fetch nixpkgs module source files
- Index multiple revisions (by git hash or channel name)
- Fetch module source files
- Support for PostgreSQL and SQLite backends
## Installation
@@ -19,17 +25,20 @@ Search and query NixOS configuration options across multiple nixpkgs revisions.
### Using Nix Flakes
```bash
# Build the package
nix build git+https://git.t-juice.club/torjus/labmcp
# 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#hm-options
# 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
```bash
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
@@ -47,40 +56,49 @@ Configure in your MCP client (e.g., Claude Desktop):
"env": {
"NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
}
},
"hm-options": {
"command": "hm-options",
"args": ["serve"],
"env": {
"HM_OPTIONS_DATABASE": "sqlite:///path/to/hm-options.db"
}
}
}
}
```
Alternatively, if you have Nix installed, you can use the flake directly without installing the package:
Alternatively, if you have Nix installed, you can use the flake directly without installing the packages:
```json
{
"mcpServers": {
"nixos-options": {
"command": "nix",
"args": ["run", "git+https://git.t-juice.club/torjus/labmcp", "--", "serve"],
"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"
}
}
}
}
```
Then start the server:
```bash
nixos-options serve
```
### 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
# Start HTTP server on default address (127.0.0.1:8080)
nixos-options serve --transport http
hm-options serve --transport http
# Custom address and CORS configuration
nixos-options serve --transport http \
@@ -100,49 +118,54 @@ HTTP transport endpoints:
### CLI Examples
**Index a nixpkgs revision:**
**Index a revision:**
```bash
# Index by channel name (includes file contents by default)
# NixOS options - index by channel name
nixos-options index nixos-unstable
# Home Manager options - index by channel name
hm-options index hm-unstable
# Index by git hash
nixos-options index e6eae2ee2110f3d31110d5c222cd395303343b08
# Index without file contents (faster, disables get_file tool)
nixos-options index --no-files nixos-unstable
hm-options index --no-files release-24.11
```
**List indexed revisions:**
```bash
nixos-options list
hm-options list
```
**Search for options:**
```bash
# Basic search
# NixOS options
nixos-options search nginx
# Limit results
nixos-options search -n 10 postgresql
# Search in specific revision
nixos-options search -r nixos-unstable firewall
# Home Manager options
hm-options search git
hm-options search -n 10 neovim
```
**Get option details:**
```bash
nixos-options get services.nginx.enable
nixos-options get services.postgresql.package
hm-options get programs.git.enable
```
**Delete an indexed revision:**
```bash
nixos-options delete nixos-23.11
hm-options delete release-23.11
```
## Configuration
@@ -151,7 +174,8 @@ nixos-options delete nixos-23.11
| 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
@@ -172,25 +196,27 @@ The database can also be specified via the `-d` or `--database` flag:
```bash
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
When running as an MCP server, the following tools are available:
Both servers provide the following tools:
| Tool | Description |
|------|-------------|
| `search_options` | Search for options by name or description |
| `get_option` | Get full details for a specific option |
| `get_file` | Fetch source file contents from nixpkgs |
| `index_revision` | Index a nixpkgs revision |
| `get_file` | Fetch source file contents from the repository |
| `index_revision` | Index a revision |
| `list_revisions` | List all indexed revisions |
| `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
{
@@ -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
Both modules have similar options. Shown here for `nixos-options-mcp` (replace with `hm-options-mcp` for Home Manager):
| 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 | `"nixos-options.db"` | SQLite database filename |
| `database.name` | string | `"*.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 |
| `user` | string | `"nixos-options-mcp"` | User to run the service as |
| `group` | string | `"nixos-options-mcp"` | Group to run the service as |
| `dataDir` | path | `/var/lib/nixos-options-mcp` | Directory for data storage |
| `http.address` | string | `"127.0.0.1:8080"` | HTTP listen address |
| `user` | string | `"*-mcp"` | User to run the service as |
| `group` | string | `"*-mcp"` | Group to run the service as |
| `dataDir` | path | `/var/lib/*-mcp` | Directory for data storage |
| `http.address` | string | `"127.0.0.1:808x"` | HTTP listen address |
| `http.endpoint` | string | `"/mcp"` | HTTP endpoint path |
| `http.allowedOrigins` | list of string | `[]` | Allowed CORS origins (empty = localhost only) |
| `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
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):
```nix
@@ -286,6 +322,7 @@ go test -bench=. ./internal/database/...
# Build
go build ./cmd/nixos-options
go build ./cmd/hm-options
```
## License

2
cmd/hm-options/main.go
View File

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

2
cmd/nixos-options/main.go
View File

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

4
internal/mcp/server.go
View File

@@ -28,7 +28,7 @@ type ServerConfig struct {
func DefaultNixOSConfig() ServerConfig {
return ServerConfig{
Name: "nixos-options",
Version: "0.1.0",
Version: "0.1.1",
DefaultChannel: "nixos-stable",
SourceName: "nixpkgs",
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 {
return ServerConfig{
Name: "hm-options",
Version: "0.1.0",
Version: "0.1.1",
DefaultChannel: "hm-stable",
SourceName: "home-manager",
Instructions: `Home Manager Options MCP Server - Search and query Home Manager configuration options.

2
nix/package.nix
View File

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