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

```bash
# Build the package
nix build github:torjus/labmcp

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

### From Source

```bash
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):

```json
{
  "mcpServers": {
    "nixos-options": {
      "command": "nixos-options",
      "args": ["serve"],
      "env": {
        "NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-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:

```bash
# 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:**

```bash
# 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:**

```bash
nixos-options list
```

**Search for options:**

```bash
# 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:**

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

**Delete an indexed revision:**

```bash
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:**
```bash
export NIXOS_OPTIONS_DATABASE="sqlite:///path/to/database.db"
export NIXOS_OPTIONS_DATABASE="sqlite://:memory:"  # In-memory
```

**PostgreSQL:**
```bash
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:

```bash
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.

```nix
{
  inputs.labmcp.url = "github: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):

```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
{
  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

```bash
# Enter development shell
nix develop

# Run tests
go test ./...

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

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

## License

MIT