Torjus Håkestad
0b7333844a
The file was still showing "Planning phase" with outdated next steps. Updated to reflect the complete implementation: - Changed status to "Complete and maintained" - Updated repository structure to match actual layout - Documented all 6 MCP tools as implemented - Added key implementation details (database, indexing, security) - Added CLI command reference - Consolidated development notes - Removed obsolete planning sections Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
148 lines
5.3 KiB
Markdown
148 lines
5.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Build with nix
|
|
nix build
|
|
|
|
# Run directly
|
|
nix run . -- serve
|
|
nix run . -- index nixos-unstable
|
|
```
|