labmcp/CLAUDE.md

CLAUDE.md - Project Context

This file provides context for Claude when working on this project.

Project Overview

LabMCP is a collection of Model Context Protocol (MCP) servers written in Go, designed to extend Claude's capabilities with custom tools. The repository is structured to be generic and extensible, allowing multiple MCP servers to be added over time.

Current Focus: NixOS Options MCP Server

The first MCP server provides search and query capabilities for NixOS configuration options. This addresses the challenge of incomplete or hard-to-find documentation in the Nix ecosystem.

Technology Stack

• Language: Go 1.24+
• Build System: Nix flakes
• Databases: PostgreSQL and SQLite (both fully supported)
• Protocol: MCP (Model Context Protocol) - JSON-RPC over stdio
• Module Path: git.t-juice.club/torjus/labmcp

Project Status

Complete and maintained - All core features implemented:

• Full MCP server with 6 tools
• PostgreSQL and SQLite backends with FTS
• NixOS module for deployment
• CLI for manual operations
• Comprehensive test suite

Repository Structure

labmcp/
├── cmd/
│   └── nixos-options/
│       └── main.go             # CLI entry point
├── internal/
│   ├── database/
│   │   ├── interface.go        # Store interface
│   │   ├── schema.go           # Schema versioning
│   │   ├── postgres.go         # PostgreSQL implementation
│   │   ├── sqlite.go           # SQLite implementation
│   │   └── *_test.go           # Database tests
│   ├── mcp/
│   │   ├── server.go           # MCP server loop
│   │   ├── handlers.go         # Tool implementations
│   │   ├── types.go            # Protocol types
│   │   └── server_test.go      # MCP tests
│   └── nixos/
│       ├── indexer.go          # Nixpkgs indexing
│       ├── parser.go           # options.json parsing
│       ├── types.go            # Channel aliases, extensions
│       └── *_test.go           # Indexer tests
├── nix/
│   ├── module.nix              # NixOS module
│   └── package.nix             # Nix package definition
├── testdata/
│   └── options-sample.json     # Test fixture
├── flake.nix
├── go.mod
├── .mcp.json                   # MCP client configuration
├── CLAUDE.md                   # This file
├── README.md
└── TODO.md                     # Future improvements

MCP Tools

All tools are implemented and functional:

Tool	Description
search_options	Full-text search across option names and descriptions
get_option	Get full details for a specific option with children
get_file	Fetch source file contents from indexed nixpkgs
index_revision	Index a nixpkgs revision (by hash or channel name)
list_revisions	List all indexed revisions
delete_revision	Delete an indexed revision

Key Implementation Details

Database

• Schema versioning with automatic recreation on version mismatch
• Full-text search: SQLite FTS5, PostgreSQL tsvector/GIN
• Path-based queries use LIKE for exact prefix matching
• Batch operations for efficient indexing

Indexing

• Uses nix-build to evaluate NixOS options from any nixpkgs revision
• File indexing downloads tarball and stores allowed extensions (.nix, .json, .md, etc.)
• File indexing enabled by default (use --no-files to skip)
• Skips already-indexed revisions (use --force to re-index)

Security

• Revision parameter validated against strict regex to prevent Nix injection
• Path traversal protection using filepath.Clean() and filepath.IsAbs()
• NixOS module supports connectionStringFile for PostgreSQL secrets
• Systemd service runs with extensive hardening options

CLI Commands

nixos-options serve              # Run MCP server on stdio
nixos-options index <revision>   # Index a nixpkgs revision
nixos-options index --force <r>  # Force re-index existing revision
nixos-options index --no-files   # Skip file content indexing
nixos-options list               # List indexed revisions
nixos-options search <query>     # Search options
nixos-options get <option>       # Get option details
nixos-options delete <revision>  # Delete indexed revision
nixos-options --version          # Show version

Notes for Claude

Development Workflow

• Always run go fmt ./... before committing Go code
• Run Go commands using nix develop -c (e.g., nix develop -c go test ./...)
• Use nix run to run binaries (e.g., nix run .#nixos-options -- serve)
• File paths in responses should use format path/to/file.go:123

User Preferences

• User prefers PostgreSQL over SQLite (has homelab infrastructure)
• User values good test coverage and benchmarking
• Project should remain generic to support future MCP servers

Testing

# Run all tests
nix develop -c go test ./... -short

# Run with verbose output
nix develop -c go test ./... -v

# Run benchmarks (requires nix-build)
nix develop -c go test -bench=. -benchtime=1x -timeout=30m ./internal/nixos/...

Building

# Build with nix
nix build

# Run directly
nix run . -- serve
nix run . -- index nixos-unstable