labmcp/README.md

LabMCP

A collection of Model Context Protocol (MCP) servers written in Go.

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.

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 revisions (by git hash or channel name)
• Fetch module source files
• Support for PostgreSQL and SQLite backends

Installation

Using Nix Flakes

# 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#nixos-options -- --help
nix run git+https://git.t-juice.club/torjus/labmcp#hm-options -- --help

From Source

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

As MCP Server (STDIO)

Configure in your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "nixos-options": {
      "command": "nixos-options",
      "args": ["serve"],
      "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 packages:

{
  "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)

Both servers can run over HTTP with Server-Sent Events (SSE) for web-based MCP clients:

# 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 \
  --http-address 0.0.0.0:8080 \
  --allowed-origins https://example.com

# With TLS
nixos-options serve --transport http \
  --tls-cert /path/to/cert.pem \
  --tls-key /path/to/key.pem

HTTP transport endpoints:

• POST /mcp - JSON-RPC requests (returns Mcp-Session-Id header on initialize)
• GET /mcp - SSE stream for server notifications (requires Mcp-Session-Id header)
• DELETE /mcp - Terminate session

CLI Examples

Index a revision:

# 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:

nixos-options list
hm-options list

Search for options:

# NixOS options
nixos-options search nginx
nixos-options search -n 10 postgresql

# Home Manager options
hm-options search git
hm-options search -n 10 neovim

Get option details:

nixos-options get services.nginx.enable
hm-options get programs.git.enable

Delete an indexed revision:

nixos-options delete nixos-23.11
hm-options delete release-23.11

Configuration

Environment Variables

Variable	Description	Default
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

SQLite:

export NIXOS_OPTIONS_DATABASE="sqlite:///path/to/database.db"
export NIXOS_OPTIONS_DATABASE="sqlite://:memory:"  # In-memory

PostgreSQL:

export NIXOS_OPTIONS_DATABASE="postgres://user:pass@localhost/nixos_options?sslmode=disable"

Command-Line Flags

The database can also be specified via the -d or --database flag:

nixos-options -d "postgres://localhost/nixos" serve
hm-options -d "sqlite://my.db" index hm-unstable

MCP Tools

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 the repository
index_revision	Index a revision
list_revisions	List all indexed revisions
delete_revision	Delete an indexed revision

NixOS Modules

NixOS modules are provided for running both MCP servers as systemd services.

nixos-options

{
  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" ];
          };
        }
      ];
    };
  };
}

hm-options

{
  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	"*.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	"*-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)
http.tls.enable	bool	false	Enable TLS
http.tls.certFile	path	null	TLS certificate file
http.tls.keyFile	path	null	TLS private key file
openFirewall	bool	false	Open firewall for HTTP port

PostgreSQL Example

Using connectionStringFile (recommended for production with sensitive credentials):

{
  services.nixos-options-mcp = {
    enable = true;
    database = {
      type = "postgres";
      # File contains: postgres://user:secret@localhost/nixos_options?sslmode=disable
      connectionStringFile = "/run/secrets/nixos-options-db";
    };
    indexOnStart = [ "nixos-unstable" ];
  };

  # Example with agenix or sops-nix for secret management
  # age.secrets.nixos-options-db.file = ./secrets/nixos-options-db.age;
}

Development

# Enter development shell
nix develop

# Run tests
go test ./...

# Run benchmarks
go test -bench=. ./internal/database/...

# Build
go build ./cmd/nixos-options
go build ./cmd/hm-options

License

MIT