labmcp/README.md

LabMCP

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

NixOS Options MCP Server

Search and query NixOS configuration options across multiple nixpkgs revisions. Designed to help Claude (and other MCP clients) answer questions about NixOS configuration.

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
• Support for PostgreSQL and SQLite backends

Installation

Using Nix Flakes

# Build the package
nix build git+https://git.t-juice.club/torjus/labmcp

# Or run directly
nix run git+https://git.t-juice.club/torjus/labmcp -- --help

From Source

go install git.t-juice.club/torjus/labmcp/cmd/nixos-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"
      }
    }
  }
}

Alternatively, if you have Nix installed, you can use the flake directly without installing the package:

{
  "mcpServers": {
    "nixos-options": {
      "command": "nix",
      "args": ["run", "git+https://git.t-juice.club/torjus/labmcp", "--", "serve"],
      "env": {
        "NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
      }
    }
  }
}

Then start the server:

nixos-options serve

As MCP Server (HTTP)

The server can also 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

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

# Index by channel name (includes file contents by default)
nixos-options index nixos-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

List indexed revisions:

nixos-options list

Search for options:

# Basic search
nixos-options search nginx

# Limit results
nixos-options search -n 10 postgresql

# Search in specific revision
nixos-options search -r nixos-unstable firewall

Get option details:

nixos-options get services.nginx.enable
nixos-options get services.postgresql.package

Delete an indexed revision:

nixos-options delete nixos-23.11

Configuration

Environment Variables

Variable	Description	Default
NIXOS_OPTIONS_DATABASE	Database connection string	sqlite://nixos-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
nixos-options -d "sqlite://my.db" index nixos-unstable

MCP Tools

When running as an MCP server, the following tools are available:

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
list_revisions	List all indexed revisions
delete_revision	Delete an indexed revision

NixOS Module

A NixOS module is provided for running the MCP server as a systemd service.

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

Module Options

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.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
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 connectionString (stored in Nix store - suitable for testing or non-sensitive setups):

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

{
  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

License

MIT