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

157
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"
}
}
}
}
```
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"],
},
"hm-options": {
"command": "hm-options",
"args": ["serve"],
"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
nixos-options serve
```json
{
"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)
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