docs: update README and CLAUDE.md for hm-options, bump version to 0.1.1
- Add hm-options documentation to README.md - Update CLAUDE.md with hm-options info, repository structure - Add note about git-tracking new files before nix build/run - Add version bump rules documentation - Bump version from 0.1.0 to 0.1.1 (patch bump for internal/ changes) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
101
CLAUDE.md
101
CLAUDE.md
@@ -6,9 +6,20 @@ This file provides context for Claude when working on this project.
|
||||
|
||||
**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
|
||||
## MCP Servers
|
||||
|
||||
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.
|
||||
### NixOS Options (`nixos-options`)
|
||||
Search and query NixOS configuration options. Uses nixpkgs as source.
|
||||
|
||||
### Home Manager Options (`hm-options`)
|
||||
Search and query Home Manager configuration options. Uses home-manager repository as source.
|
||||
|
||||
Both servers share the same architecture:
|
||||
- Full-text search across option names and descriptions
|
||||
- Query specific options with type, default, example, and declarations
|
||||
- Index multiple revisions (by git hash or channel name)
|
||||
- Fetch module source files
|
||||
- PostgreSQL and SQLite backends
|
||||
|
||||
## Technology Stack
|
||||
|
||||
@@ -21,9 +32,9 @@ The first MCP server provides search and query capabilities for NixOS configurat
|
||||
## Project Status
|
||||
|
||||
**Complete and maintained** - All core features implemented:
|
||||
- Full MCP server with 6 tools
|
||||
- Full MCP servers with 6 tools each
|
||||
- PostgreSQL and SQLite backends with FTS
|
||||
- NixOS module for deployment
|
||||
- NixOS modules for deployment
|
||||
- CLI for manual operations
|
||||
- Comprehensive test suite
|
||||
|
||||
@@ -32,8 +43,10 @@ The first MCP server provides search and query capabilities for NixOS configurat
|
||||
```
|
||||
labmcp/
|
||||
├── cmd/
|
||||
│ └── nixos-options/
|
||||
│ └── main.go # CLI entry point
|
||||
│ ├── nixos-options/
|
||||
│ │ └── main.go # NixOS options CLI
|
||||
│ └── hm-options/
|
||||
│ └── main.go # Home Manager options CLI
|
||||
├── internal/
|
||||
│ ├── database/
|
||||
│ │ ├── interface.go # Store interface
|
||||
@@ -42,7 +55,7 @@ labmcp/
|
||||
│ │ ├── sqlite.go # SQLite implementation
|
||||
│ │ └── *_test.go # Database tests
|
||||
│ ├── mcp/
|
||||
│ │ ├── server.go # MCP server core
|
||||
│ │ ├── server.go # MCP server core + ServerConfig
|
||||
│ │ ├── handlers.go # Tool implementations
|
||||
│ │ ├── types.go # Protocol types
|
||||
│ │ ├── transport.go # Transport interface
|
||||
@@ -50,14 +63,21 @@ labmcp/
|
||||
│ │ ├── transport_http.go # HTTP/SSE transport
|
||||
│ │ ├── session.go # HTTP session management
|
||||
│ │ └── *_test.go # MCP tests
|
||||
│ └── nixos/
|
||||
│ ├── indexer.go # Nixpkgs indexing
|
||||
│ ├── parser.go # options.json parsing
|
||||
│ ├── options/
|
||||
│ │ └── indexer.go # Shared Indexer interface
|
||||
│ ├── nixos/
|
||||
│ │ ├── indexer.go # Nixpkgs indexing
|
||||
│ │ ├── parser.go # options.json parsing (shared)
|
||||
│ │ ├── types.go # Channel aliases, extensions
|
||||
│ │ └── *_test.go # Indexer tests
|
||||
│ └── homemanager/
|
||||
│ ├── indexer.go # Home Manager indexing
|
||||
│ ├── types.go # Channel aliases, extensions
|
||||
│ └── *_test.go # Indexer tests
|
||||
├── nix/
|
||||
│ ├── module.nix # NixOS module
|
||||
│ └── package.nix # Nix package definition
|
||||
│ ├── module.nix # NixOS module for nixos-options
|
||||
│ ├── hm-options-module.nix # NixOS module for hm-options
|
||||
│ └── package.nix # Parameterized Nix package
|
||||
├── testdata/
|
||||
│ └── options-sample.json # Test fixture
|
||||
├── flake.nix
|
||||
@@ -70,14 +90,14 @@ labmcp/
|
||||
|
||||
## MCP Tools
|
||||
|
||||
All tools are implemented and functional:
|
||||
Both servers provide the same 6 tools:
|
||||
|
||||
| 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) |
|
||||
| `get_file` | Fetch source file contents from indexed repository |
|
||||
| `index_revision` | Index a revision (by hash or channel name) |
|
||||
| `list_revisions` | List all indexed revisions |
|
||||
| `delete_revision` | Delete an indexed revision |
|
||||
|
||||
@@ -90,7 +110,7 @@ All tools are implemented and functional:
|
||||
- Batch operations for efficient indexing
|
||||
|
||||
### Indexing
|
||||
- Uses `nix-build` to evaluate NixOS options from any nixpkgs revision
|
||||
- Uses `nix-build` to evaluate options from any 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)
|
||||
@@ -116,12 +136,10 @@ All tools are implemented and functional:
|
||||
|
||||
## CLI Commands
|
||||
|
||||
### nixos-options
|
||||
```bash
|
||||
nixos-options serve # Run MCP server on STDIO (default)
|
||||
nixos-options serve --transport http # Run MCP server on HTTP
|
||||
nixos-options serve --transport http \
|
||||
--http-address 0.0.0.0:8080 \
|
||||
--allowed-origins https://example.com # HTTP with custom config
|
||||
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
|
||||
@@ -132,6 +150,26 @@ nixos-options delete <revision> # Delete indexed revision
|
||||
nixos-options --version # Show version
|
||||
```
|
||||
|
||||
### hm-options
|
||||
```bash
|
||||
hm-options serve # Run MCP server on STDIO (default)
|
||||
hm-options serve --transport http # Run MCP server on HTTP
|
||||
hm-options index <revision> # Index a home-manager revision
|
||||
hm-options index --force <r> # Force re-index existing revision
|
||||
hm-options index --no-files # Skip file content indexing
|
||||
hm-options list # List indexed revisions
|
||||
hm-options search <query> # Search options
|
||||
hm-options get <option> # Get option details
|
||||
hm-options delete <revision> # Delete indexed revision
|
||||
hm-options --version # Show version
|
||||
```
|
||||
|
||||
### Channel Aliases
|
||||
|
||||
**nixos-options**: `nixos-unstable`, `nixos-stable`, `nixos-24.11`, `nixos-24.05`, etc.
|
||||
|
||||
**hm-options**: `hm-unstable`, `hm-stable`, `master`, `release-24.11`, `release-24.05`, etc.
|
||||
|
||||
## Notes for Claude
|
||||
|
||||
### Development Workflow
|
||||
@@ -140,6 +178,21 @@ nixos-options --version # Show version
|
||||
- **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`
|
||||
|
||||
### Nix Build Requirement
|
||||
**IMPORTANT**: When running `nix build`, `nix run`, or similar commands, new files must be tracked by git first. Nix flakes only see git-tracked files. If you create new files, run `git add <file>` before attempting nix operations.
|
||||
|
||||
### Version Bumping
|
||||
Version bumps should be done once per feature branch, not per commit. Rules:
|
||||
- **Patch bump** (0.1.0 → 0.1.1): Changes to Go code within `internal/` that affect a program
|
||||
- **Minor bump** (0.1.0 → 0.2.0): Changes to Go code outside `internal/` (e.g., `cmd/`)
|
||||
- **Major bump** (0.1.0 → 1.0.0): Breaking changes to CLI usage or MCP protocol
|
||||
|
||||
Version is defined in multiple places that must stay in sync:
|
||||
- `cmd/nixos-options/main.go`
|
||||
- `cmd/hm-options/main.go`
|
||||
- `internal/mcp/server.go` (in `DefaultNixOSConfig` and `DefaultHomeManagerConfig`)
|
||||
- `nix/package.nix`
|
||||
|
||||
### User Preferences
|
||||
- User prefers PostgreSQL over SQLite (has homelab infrastructure)
|
||||
- User values good test coverage and benchmarking
|
||||
@@ -155,14 +208,18 @@ nix develop -c go test ./... -v
|
||||
|
||||
# Run benchmarks (requires nix-build)
|
||||
nix develop -c go test -bench=. -benchtime=1x -timeout=30m ./internal/nixos/...
|
||||
nix develop -c go test -bench=. -benchtime=1x -timeout=30m ./internal/homemanager/...
|
||||
```
|
||||
|
||||
### Building
|
||||
```bash
|
||||
# Build with nix
|
||||
nix build
|
||||
nix build .#nixos-options
|
||||
nix build .#hm-options
|
||||
|
||||
# Run directly
|
||||
nix run . -- serve
|
||||
nix run . -- index nixos-unstable
|
||||
nix run .#nixos-options -- serve
|
||||
nix run .#hm-options -- serve
|
||||
nix run .#nixos-options -- index nixos-unstable
|
||||
nix run .#hm-options -- index hm-unstable
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user