Archived

This repository has been archived on 2026-03-10. You can view files and clone it. You cannot open issues or pull requests or push a commit.

Files

Torjus Håkestad 9352fd1f6e

docs: update README with usage instructions

- Add installation instructions (nix flakes, go install)
- Add MCP server configuration example
- Add CLI examples for all commands
- Document environment variables and database connection strings
- List available MCP tools

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-02-03 17:58:02 +01:00

3.3 KiB

Raw Blame History

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 github:torjus/labmcp

# Or run directly
nix run github:torjus/labmcp -- --help

From Source

go install git.t-juice.club/torjus/labmcp/cmd/nixos-options@latest

Usage

As MCP Server

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"
      }
    }
  }
}

Then start the server:

nixos-options serve

CLI Examples

Index a nixpkgs revision:

# Index by channel name
nixos-options index nixos-unstable

# Index by git hash
nixos-options index e6eae2ee2110f3d31110d5c222cd395303343b08

# Index with file contents (enables get_file tool, slower)
nixos-options index --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

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

3.3 KiB Raw Blame History