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.25.5
• Build System: Nix flakes
• Databases: PostgreSQL (primary) and SQLite (lightweight alternative)
• Protocol: MCP (Model Context Protocol) - JSON-RPC over stdio
• Module Path: git.t-juice.club/torjus/labmcp

Key Architectural Decisions

1. Database Support: Both PostgreSQL and SQLite

   • PostgreSQL is preferred for production use (user's preference)
   • SQLite provides lightweight alternative for simpler deployments
   • Use Go's database/sql interface for abstraction

2. File Storage: Store nixpkgs file contents in database during indexing

   • Better performance for the get_file tool
   • PostgreSQL handles large text storage well

3. Revision Management: Support multiple indexed nixpkgs revisions

   • Store git hash, date, channel name, option count
   • Allow querying specific revisions or use defaults
   • Default revision: nixos-stable (configurable)

4. Indexing Approach: Part of MCP server, blocking operation (initially)

   • Allows Claude to read flake.lock and request indexing
   • Can optimize to async later if needed

5. Testing: Aim for >80% test coverage

   • Unit tests for all components
   • Integration tests for full workflows
   • Benchmarks for indexing and query performance

MCP Tools to Implement

Core Search & Query

1. search_options - Fuzzy/partial matching search

   • Parameters: revision, query, optional filters (type, namespace, hasDefault)
   • Returns: matching options with basic metadata

2. get_option - Get full details for specific option

   • Parameters: revision, option_path, optional depth
   • Returns: name, type, default, example, description, file paths
   • Default: direct children only (one level deep)
   • Includes related/nearby options in same namespace

3. get_file - Fetch nixpkgs source file contents

   • Parameters: revision, file_path
   • Returns: file contents
   • Security: validate paths, no traversal, nixpkgs-only

Revision Management

4. index_revision - Index a specific nixpkgs revision

   • Parameters: git_hash (full or short)
   • Process: fetch nixpkgs, extract options.json, populate DB
   • Returns: summary (option count, duration, etc.)

5. list_revisions - List indexed revisions

   • Returns: git hash, date, channel name, option count

6. delete_revision - Prune old/unused revisions

   • Parameters: revision identifier
   • Returns: confirmation of deletion

Channel Support

• Support friendly aliases: nixos-unstable, nixos-24.05, nixos-23.11, etc.
• Can be used in place of git hashes in all tools

Database Schema

Tables:

1. revisions - Indexed nixpkgs versions

   • id, git_hash (unique), channel_name, commit_date, indexed_at, option_count

2. options - NixOS options with hierarchy support

   • id, revision_id (FK), name, parent_path, type, default_value (JSON text), example (JSON text), description, read_only
   • parent_path enables efficient "list children" queries (derived from name)

3. declarations - File paths where options are declared

   • id, option_id (FK), file_path, line_number

4. files - Cached file contents

   • id, revision_id (FK), file_path, extension, content
   • Configurable whitelist of extensions (default: .nix, .json, .md, .txt, .toml, .yaml, .yml)

Indexes:

• Full-text search: PostgreSQL (tsvector/GIN), SQLite (FTS5)
• B-tree on (revision_id, name) and (revision_id, parent_path)
• B-tree on (revision_id, file_path) for file lookups

Cross-DB Compatibility:

• JSON stored as TEXT (not JSONB) for SQLite compatibility
• Separate FTS implementations per database engine

Repository Structure (Planned)

labmcp/
├── cmd/
│   └── nixos-options/          # MCP server binary
│       └── main.go
├── internal/
│   ├── mcp/                    # MCP protocol implementation
│   │   ├── server.go
│   │   └── types.go
│   ├── database/               # Database abstraction
│   │   ├── interface.go
│   │   ├── postgres.go
│   │   └── sqlite.go
│   └── nixos/                  # NixOS options specific logic
│       ├── search.go
│       └── types.go
├── scripts/
│   └── populate-db.go          # Tool to populate database
├── schema/
│   └── schema.sql              # Database schema
├── flake.nix                   # Nix build configuration
├── go.mod
├── TODO.md                     # Detailed task list
├── CLAUDE.md                   # This file
└── README.md

Use Cases

Primary Use Case: Claude can help users find and understand NixOS options

• "What options are available for nginx?"
• "Show me the services.caddy.* options"
• "What's the default value for services.postgresql.enable?"
• User shares a flake.lock → Claude indexes that nixpkgs version → answers questions about options in that specific version

Secondary Use Case: Explore module implementations

• If option description is unclear, fetch the actual module source
• Understand how complex options are structured

Testing Strategy

• Unit Tests: All components with mocks where appropriate
• Integration Tests: Full indexing pipeline, MCP tool invocations
• Benchmarks: Indexing time, query performance, memory usage
• Test Fixtures: Sample options.json, mock repositories
• Coverage Goal: >80% on core logic, 100% on database operations

Open Questions

1. Should index_revision be blocking or async? (Currently: blocking, optimize later)
2. Should we auto-update channel aliases or manual only?

Current Status

Planning phase - architecture and features defined, ready to begin implementation.

Next Steps

1. Design and implement database schema
2. Set up project structure (directories, Go modules)
3. Implement database abstraction layer
4. Implement MCP protocol basics
5. Build indexing logic
6. Implement MCP tools
7. Create Nix package in flake.nix
8. Write tests and benchmarks

Notes for Claude

• User prefers PostgreSQL over SQLite (has homelab infrastructure)
• User values good test coverage and benchmarking
• Project should remain generic to support future MCP servers
• Nix flake must provide importable packages for other repos
• Use database/sql interface for database abstraction
• File paths in responses should use format path/to/file.go:123
• Always run go fmt ./... before committing Go code