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.
|
**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
|
## Technology Stack
|
||||||
|
|
||||||
@@ -21,9 +32,9 @@ The first MCP server provides search and query capabilities for NixOS configurat
|
|||||||
## Project Status
|
## Project Status
|
||||||
|
|
||||||
**Complete and maintained** - All core features implemented:
|
**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
|
- PostgreSQL and SQLite backends with FTS
|
||||||
- NixOS module for deployment
|
- NixOS modules for deployment
|
||||||
- CLI for manual operations
|
- CLI for manual operations
|
||||||
- Comprehensive test suite
|
- Comprehensive test suite
|
||||||
|
|
||||||
@@ -32,8 +43,10 @@ The first MCP server provides search and query capabilities for NixOS configurat
|
|||||||
```
|
```
|
||||||
labmcp/
|
labmcp/
|
||||||
├── cmd/
|
├── cmd/
|
||||||
│ └── nixos-options/
|
│ ├── nixos-options/
|
||||||
│ └── main.go # CLI entry point
|
│ │ └── main.go # NixOS options CLI
|
||||||
|
│ └── hm-options/
|
||||||
|
│ └── main.go # Home Manager options CLI
|
||||||
├── internal/
|
├── internal/
|
||||||
│ ├── database/
|
│ ├── database/
|
||||||
│ │ ├── interface.go # Store interface
|
│ │ ├── interface.go # Store interface
|
||||||
@@ -42,7 +55,7 @@ labmcp/
|
|||||||
│ │ ├── sqlite.go # SQLite implementation
|
│ │ ├── sqlite.go # SQLite implementation
|
||||||
│ │ └── *_test.go # Database tests
|
│ │ └── *_test.go # Database tests
|
||||||
│ ├── mcp/
|
│ ├── mcp/
|
||||||
│ │ ├── server.go # MCP server core
|
│ │ ├── server.go # MCP server core + ServerConfig
|
||||||
│ │ ├── handlers.go # Tool implementations
|
│ │ ├── handlers.go # Tool implementations
|
||||||
│ │ ├── types.go # Protocol types
|
│ │ ├── types.go # Protocol types
|
||||||
│ │ ├── transport.go # Transport interface
|
│ │ ├── transport.go # Transport interface
|
||||||
@@ -50,14 +63,21 @@ labmcp/
|
|||||||
│ │ ├── transport_http.go # HTTP/SSE transport
|
│ │ ├── transport_http.go # HTTP/SSE transport
|
||||||
│ │ ├── session.go # HTTP session management
|
│ │ ├── session.go # HTTP session management
|
||||||
│ │ └── *_test.go # MCP tests
|
│ │ └── *_test.go # MCP tests
|
||||||
│ └── nixos/
|
│ ├── options/
|
||||||
│ ├── indexer.go # Nixpkgs indexing
|
│ │ └── indexer.go # Shared Indexer interface
|
||||||
│ ├── parser.go # options.json parsing
|
│ ├── 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
|
│ ├── types.go # Channel aliases, extensions
|
||||||
│ └── *_test.go # Indexer tests
|
│ └── *_test.go # Indexer tests
|
||||||
├── nix/
|
├── nix/
|
||||||
│ ├── module.nix # NixOS module
|
│ ├── module.nix # NixOS module for nixos-options
|
||||||
│ └── package.nix # Nix package definition
|
│ ├── hm-options-module.nix # NixOS module for hm-options
|
||||||
|
│ └── package.nix # Parameterized Nix package
|
||||||
├── testdata/
|
├── testdata/
|
||||||
│ └── options-sample.json # Test fixture
|
│ └── options-sample.json # Test fixture
|
||||||
├── flake.nix
|
├── flake.nix
|
||||||
@@ -70,14 +90,14 @@ labmcp/
|
|||||||
|
|
||||||
## MCP Tools
|
## MCP Tools
|
||||||
|
|
||||||
All tools are implemented and functional:
|
Both servers provide the same 6 tools:
|
||||||
|
|
||||||
| Tool | Description |
|
| Tool | Description |
|
||||||
|------|-------------|
|
|------|-------------|
|
||||||
| `search_options` | Full-text search across option names and descriptions |
|
| `search_options` | Full-text search across option names and descriptions |
|
||||||
| `get_option` | Get full details for a specific option with children |
|
| `get_option` | Get full details for a specific option with children |
|
||||||
| `get_file` | Fetch source file contents from indexed nixpkgs |
|
| `get_file` | Fetch source file contents from indexed repository |
|
||||||
| `index_revision` | Index a nixpkgs revision (by hash or channel name) |
|
| `index_revision` | Index a revision (by hash or channel name) |
|
||||||
| `list_revisions` | List all indexed revisions |
|
| `list_revisions` | List all indexed revisions |
|
||||||
| `delete_revision` | Delete an indexed revision |
|
| `delete_revision` | Delete an indexed revision |
|
||||||
|
|
||||||
@@ -90,7 +110,7 @@ All tools are implemented and functional:
|
|||||||
- Batch operations for efficient indexing
|
- Batch operations for efficient indexing
|
||||||
|
|
||||||
### 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 downloads tarball and stores allowed extensions (.nix, .json, .md, etc.)
|
||||||
- File indexing enabled by default (use `--no-files` to skip)
|
- File indexing enabled by default (use `--no-files` to skip)
|
||||||
- Skips already-indexed revisions (use `--force` to re-index)
|
- Skips already-indexed revisions (use `--force` to re-index)
|
||||||
@@ -116,12 +136,10 @@ All tools are implemented and functional:
|
|||||||
|
|
||||||
## CLI Commands
|
## CLI Commands
|
||||||
|
|
||||||
|
### nixos-options
|
||||||
```bash
|
```bash
|
||||||
nixos-options serve # Run MCP server on STDIO (default)
|
nixos-options serve # Run MCP server on STDIO (default)
|
||||||
nixos-options serve --transport http # Run MCP server on HTTP
|
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 <revision> # Index a nixpkgs revision
|
||||||
nixos-options index --force <r> # Force re-index existing revision
|
nixos-options index --force <r> # Force re-index existing revision
|
||||||
nixos-options index --no-files # Skip file content indexing
|
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
|
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
|
## Notes for Claude
|
||||||
|
|
||||||
### Development Workflow
|
### Development Workflow
|
||||||
@@ -140,6 +178,21 @@ nixos-options --version # Show version
|
|||||||
- **Use `nix run` to run binaries** (e.g., `nix run .#nixos-options -- serve`)
|
- **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`
|
- 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 Preferences
|
||||||
- User prefers PostgreSQL over SQLite (has homelab infrastructure)
|
- User prefers PostgreSQL over SQLite (has homelab infrastructure)
|
||||||
- User values good test coverage and benchmarking
|
- User values good test coverage and benchmarking
|
||||||
@@ -155,14 +208,18 @@ nix develop -c go test ./... -v
|
|||||||
|
|
||||||
# Run benchmarks (requires nix-build)
|
# 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/nixos/...
|
||||||
|
nix develop -c go test -bench=. -benchtime=1x -timeout=30m ./internal/homemanager/...
|
||||||
```
|
```
|
||||||
|
|
||||||
### Building
|
### Building
|
||||||
```bash
|
```bash
|
||||||
# Build with nix
|
# Build with nix
|
||||||
nix build
|
nix build .#nixos-options
|
||||||
|
nix build .#hm-options
|
||||||
|
|
||||||
# Run directly
|
# Run directly
|
||||||
nix run . -- serve
|
nix run .#nixos-options -- serve
|
||||||
nix run . -- index nixos-unstable
|
nix run .#hm-options -- serve
|
||||||
|
nix run .#nixos-options -- index nixos-unstable
|
||||||
|
nix run .#hm-options -- index hm-unstable
|
||||||
```
|
```
|
||||||
|
|||||||
139
README.md
139
README.md
@@ -2,16 +2,22 @@
|
|||||||
|
|
||||||
A collection of Model Context Protocol (MCP) servers written in Go.
|
A collection of Model Context Protocol (MCP) servers written in Go.
|
||||||
|
|
||||||
## NixOS Options MCP Server
|
## MCP Servers
|
||||||
|
|
||||||
|
### NixOS Options (`nixos-options`)
|
||||||
|
|
||||||
Search and query NixOS configuration options across multiple nixpkgs revisions. Designed to help Claude (and other MCP clients) answer questions about NixOS configuration.
|
Search and query NixOS configuration options across multiple nixpkgs revisions. Designed to help Claude (and other MCP clients) answer questions about NixOS configuration.
|
||||||
|
|
||||||
### Features
|
### Home Manager Options (`hm-options`)
|
||||||
|
|
||||||
|
Search and query Home Manager configuration options across multiple home-manager revisions. Designed to help Claude (and other MCP clients) answer questions about Home Manager configuration.
|
||||||
|
|
||||||
|
### Shared Features
|
||||||
|
|
||||||
- Full-text search across option names and descriptions
|
- Full-text search across option names and descriptions
|
||||||
- Query specific options with type, default, example, and declarations
|
- Query specific options with type, default, example, and declarations
|
||||||
- Index multiple nixpkgs revisions (by git hash or channel name)
|
- Index multiple revisions (by git hash or channel name)
|
||||||
- Fetch nixpkgs module source files
|
- Fetch module source files
|
||||||
- Support for PostgreSQL and SQLite backends
|
- Support for PostgreSQL and SQLite backends
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
@@ -19,17 +25,20 @@ Search and query NixOS configuration options across multiple nixpkgs revisions.
|
|||||||
### Using Nix Flakes
|
### Using Nix Flakes
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Build the package
|
# Build the packages
|
||||||
nix build git+https://git.t-juice.club/torjus/labmcp
|
nix build git+https://git.t-juice.club/torjus/labmcp#nixos-options
|
||||||
|
nix build git+https://git.t-juice.club/torjus/labmcp#hm-options
|
||||||
|
|
||||||
# Or run directly
|
# Or run directly
|
||||||
nix run git+https://git.t-juice.club/torjus/labmcp -- --help
|
nix run git+https://git.t-juice.club/torjus/labmcp#nixos-options -- --help
|
||||||
|
nix run git+https://git.t-juice.club/torjus/labmcp#hm-options -- --help
|
||||||
```
|
```
|
||||||
|
|
||||||
### From Source
|
### From Source
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
go install git.t-juice.club/torjus/labmcp/cmd/nixos-options@latest
|
go install git.t-juice.club/torjus/labmcp/cmd/nixos-options@latest
|
||||||
|
go install git.t-juice.club/torjus/labmcp/cmd/hm-options@latest
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
@@ -47,40 +56,49 @@ Configure in your MCP client (e.g., Claude Desktop):
|
|||||||
"env": {
|
"env": {
|
||||||
"NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
|
"NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
|
||||||
}
|
}
|
||||||
|
},
|
||||||
|
"hm-options": {
|
||||||
|
"command": "hm-options",
|
||||||
|
"args": ["serve"],
|
||||||
|
"env": {
|
||||||
|
"HM_OPTIONS_DATABASE": "sqlite:///path/to/hm-options.db"
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Alternatively, if you have Nix installed, you can use the flake directly without installing the package:
|
Alternatively, if you have Nix installed, you can use the flake directly without installing the packages:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"mcpServers": {
|
||||||
"nixos-options": {
|
"nixos-options": {
|
||||||
"command": "nix",
|
"command": "nix",
|
||||||
"args": ["run", "git+https://git.t-juice.club/torjus/labmcp", "--", "serve"],
|
"args": ["run", "git+https://git.t-juice.club/torjus/labmcp#nixos-options", "--", "serve"],
|
||||||
"env": {
|
"env": {
|
||||||
"NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
|
"NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
|
||||||
}
|
}
|
||||||
|
},
|
||||||
|
"hm-options": {
|
||||||
|
"command": "nix",
|
||||||
|
"args": ["run", "git+https://git.t-juice.club/torjus/labmcp#hm-options", "--", "serve"],
|
||||||
|
"env": {
|
||||||
|
"HM_OPTIONS_DATABASE": "sqlite:///path/to/hm-options.db"
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
|
||||||
|
|
||||||
Then start the server:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
nixos-options serve
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### As MCP Server (HTTP)
|
### As MCP Server (HTTP)
|
||||||
|
|
||||||
The server can also run over HTTP with Server-Sent Events (SSE) for web-based MCP clients:
|
Both servers can run over HTTP with Server-Sent Events (SSE) for web-based MCP clients:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Start HTTP server on default address (127.0.0.1:8080)
|
# Start HTTP server on default address (127.0.0.1:8080)
|
||||||
nixos-options serve --transport http
|
nixos-options serve --transport http
|
||||||
|
hm-options serve --transport http
|
||||||
|
|
||||||
# Custom address and CORS configuration
|
# Custom address and CORS configuration
|
||||||
nixos-options serve --transport http \
|
nixos-options serve --transport http \
|
||||||
@@ -100,49 +118,54 @@ HTTP transport endpoints:
|
|||||||
|
|
||||||
### CLI Examples
|
### CLI Examples
|
||||||
|
|
||||||
**Index a nixpkgs revision:**
|
**Index a revision:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Index by channel name (includes file contents by default)
|
# NixOS options - index by channel name
|
||||||
nixos-options index nixos-unstable
|
nixos-options index nixos-unstable
|
||||||
|
|
||||||
|
# Home Manager options - index by channel name
|
||||||
|
hm-options index hm-unstable
|
||||||
|
|
||||||
# Index by git hash
|
# Index by git hash
|
||||||
nixos-options index e6eae2ee2110f3d31110d5c222cd395303343b08
|
nixos-options index e6eae2ee2110f3d31110d5c222cd395303343b08
|
||||||
|
|
||||||
# Index without file contents (faster, disables get_file tool)
|
# Index without file contents (faster, disables get_file tool)
|
||||||
nixos-options index --no-files nixos-unstable
|
nixos-options index --no-files nixos-unstable
|
||||||
|
hm-options index --no-files release-24.11
|
||||||
```
|
```
|
||||||
|
|
||||||
**List indexed revisions:**
|
**List indexed revisions:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
nixos-options list
|
nixos-options list
|
||||||
|
hm-options list
|
||||||
```
|
```
|
||||||
|
|
||||||
**Search for options:**
|
**Search for options:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Basic search
|
# NixOS options
|
||||||
nixos-options search nginx
|
nixos-options search nginx
|
||||||
|
|
||||||
# Limit results
|
|
||||||
nixos-options search -n 10 postgresql
|
nixos-options search -n 10 postgresql
|
||||||
|
|
||||||
# Search in specific revision
|
# Home Manager options
|
||||||
nixos-options search -r nixos-unstable firewall
|
hm-options search git
|
||||||
|
hm-options search -n 10 neovim
|
||||||
```
|
```
|
||||||
|
|
||||||
**Get option details:**
|
**Get option details:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
nixos-options get services.nginx.enable
|
nixos-options get services.nginx.enable
|
||||||
nixos-options get services.postgresql.package
|
hm-options get programs.git.enable
|
||||||
```
|
```
|
||||||
|
|
||||||
**Delete an indexed revision:**
|
**Delete an indexed revision:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
nixos-options delete nixos-23.11
|
nixos-options delete nixos-23.11
|
||||||
|
hm-options delete release-23.11
|
||||||
```
|
```
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
@@ -151,7 +174,8 @@ nixos-options delete nixos-23.11
|
|||||||
|
|
||||||
| Variable | Description | Default |
|
| Variable | Description | Default |
|
||||||
|----------|-------------|---------|
|
|----------|-------------|---------|
|
||||||
| `NIXOS_OPTIONS_DATABASE` | Database connection string | `sqlite://nixos-options.db` |
|
| `NIXOS_OPTIONS_DATABASE` | Database connection string for nixos-options | `sqlite://nixos-options.db` |
|
||||||
|
| `HM_OPTIONS_DATABASE` | Database connection string for hm-options | `sqlite://hm-options.db` |
|
||||||
|
|
||||||
### Database Connection Strings
|
### Database Connection Strings
|
||||||
|
|
||||||
@@ -172,25 +196,27 @@ The database can also be specified via the `-d` or `--database` flag:
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
nixos-options -d "postgres://localhost/nixos" serve
|
nixos-options -d "postgres://localhost/nixos" serve
|
||||||
nixos-options -d "sqlite://my.db" index nixos-unstable
|
hm-options -d "sqlite://my.db" index hm-unstable
|
||||||
```
|
```
|
||||||
|
|
||||||
## MCP Tools
|
## MCP Tools
|
||||||
|
|
||||||
When running as an MCP server, the following tools are available:
|
Both servers provide the following tools:
|
||||||
|
|
||||||
| Tool | Description |
|
| Tool | Description |
|
||||||
|------|-------------|
|
|------|-------------|
|
||||||
| `search_options` | Search for options by name or description |
|
| `search_options` | Search for options by name or description |
|
||||||
| `get_option` | Get full details for a specific option |
|
| `get_option` | Get full details for a specific option |
|
||||||
| `get_file` | Fetch source file contents from nixpkgs |
|
| `get_file` | Fetch source file contents from the repository |
|
||||||
| `index_revision` | Index a nixpkgs revision |
|
| `index_revision` | Index a revision |
|
||||||
| `list_revisions` | List all indexed revisions |
|
| `list_revisions` | List all indexed revisions |
|
||||||
| `delete_revision` | Delete an indexed revision |
|
| `delete_revision` | Delete an indexed revision |
|
||||||
|
|
||||||
## NixOS Module
|
## NixOS Modules
|
||||||
|
|
||||||
A NixOS module is provided for running the MCP server as a systemd service.
|
NixOS modules are provided for running both MCP servers as systemd services.
|
||||||
|
|
||||||
|
### nixos-options
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
{
|
{
|
||||||
@@ -213,21 +239,46 @@ A NixOS module is provided for running the MCP server as a systemd service.
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### hm-options
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{
|
||||||
|
inputs.labmcp.url = "git+https://git.t-juice.club/torjus/labmcp";
|
||||||
|
|
||||||
|
outputs = { self, nixpkgs, labmcp }: {
|
||||||
|
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
|
||||||
|
system = "x86_64-linux";
|
||||||
|
modules = [
|
||||||
|
labmcp.nixosModules.hm-options-mcp
|
||||||
|
{
|
||||||
|
services.hm-options-mcp = {
|
||||||
|
enable = true;
|
||||||
|
indexOnStart = [ "hm-unstable" ];
|
||||||
|
};
|
||||||
|
}
|
||||||
|
];
|
||||||
|
};
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
### Module Options
|
### Module Options
|
||||||
|
|
||||||
|
Both modules have similar options. Shown here for `nixos-options-mcp` (replace with `hm-options-mcp` for Home Manager):
|
||||||
|
|
||||||
| Option | Type | Default | Description |
|
| Option | Type | Default | Description |
|
||||||
|--------|------|---------|-------------|
|
|--------|------|---------|-------------|
|
||||||
| `enable` | bool | `false` | Enable the service |
|
| `enable` | bool | `false` | Enable the service |
|
||||||
| `package` | package | from flake | Package to use |
|
| `package` | package | from flake | Package to use |
|
||||||
| `database.type` | enum | `"sqlite"` | `"sqlite"` or `"postgres"` |
|
| `database.type` | enum | `"sqlite"` | `"sqlite"` or `"postgres"` |
|
||||||
| `database.name` | string | `"nixos-options.db"` | SQLite database filename |
|
| `database.name` | string | `"*.db"` | SQLite database filename |
|
||||||
| `database.connectionString` | string | `""` | PostgreSQL connection URL (stored in Nix store) |
|
| `database.connectionString` | string | `""` | PostgreSQL connection URL (stored in Nix store) |
|
||||||
| `database.connectionStringFile` | path | `null` | Path to file with PostgreSQL connection URL (recommended for secrets) |
|
| `database.connectionStringFile` | path | `null` | Path to file with PostgreSQL connection URL (recommended for secrets) |
|
||||||
| `indexOnStart` | list of string | `[]` | Revisions to index on service start |
|
| `indexOnStart` | list of string | `[]` | Revisions to index on service start |
|
||||||
| `user` | string | `"nixos-options-mcp"` | User to run the service as |
|
| `user` | string | `"*-mcp"` | User to run the service as |
|
||||||
| `group` | string | `"nixos-options-mcp"` | Group to run the service as |
|
| `group` | string | `"*-mcp"` | Group to run the service as |
|
||||||
| `dataDir` | path | `/var/lib/nixos-options-mcp` | Directory for data storage |
|
| `dataDir` | path | `/var/lib/*-mcp` | Directory for data storage |
|
||||||
| `http.address` | string | `"127.0.0.1:8080"` | HTTP listen address |
|
| `http.address` | string | `"127.0.0.1:808x"` | HTTP listen address |
|
||||||
| `http.endpoint` | string | `"/mcp"` | HTTP endpoint path |
|
| `http.endpoint` | string | `"/mcp"` | HTTP endpoint path |
|
||||||
| `http.allowedOrigins` | list of string | `[]` | Allowed CORS origins (empty = localhost only) |
|
| `http.allowedOrigins` | list of string | `[]` | Allowed CORS origins (empty = localhost only) |
|
||||||
| `http.sessionTTL` | string | `"30m"` | Session timeout (Go duration format) |
|
| `http.sessionTTL` | string | `"30m"` | Session timeout (Go duration format) |
|
||||||
@@ -238,21 +289,6 @@ A NixOS module is provided for running the MCP server as a systemd service.
|
|||||||
|
|
||||||
### PostgreSQL Example
|
### 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):
|
Using `connectionStringFile` (recommended for production with sensitive credentials):
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
@@ -286,6 +322,7 @@ go test -bench=. ./internal/database/...
|
|||||||
|
|
||||||
# Build
|
# Build
|
||||||
go build ./cmd/nixos-options
|
go build ./cmd/nixos-options
|
||||||
|
go build ./cmd/hm-options
|
||||||
```
|
```
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|||||||
@@ -20,7 +20,7 @@ import (
|
|||||||
|
|
||||||
const (
|
const (
|
||||||
defaultDatabase = "sqlite://hm-options.db"
|
defaultDatabase = "sqlite://hm-options.db"
|
||||||
version = "0.1.0"
|
version = "0.1.1"
|
||||||
)
|
)
|
||||||
|
|
||||||
func main() {
|
func main() {
|
||||||
|
|||||||
@@ -19,7 +19,7 @@ import (
|
|||||||
|
|
||||||
const (
|
const (
|
||||||
defaultDatabase = "sqlite://nixos-options.db"
|
defaultDatabase = "sqlite://nixos-options.db"
|
||||||
version = "0.1.0"
|
version = "0.1.1"
|
||||||
)
|
)
|
||||||
|
|
||||||
func main() {
|
func main() {
|
||||||
|
|||||||
@@ -28,7 +28,7 @@ type ServerConfig struct {
|
|||||||
func DefaultNixOSConfig() ServerConfig {
|
func DefaultNixOSConfig() ServerConfig {
|
||||||
return ServerConfig{
|
return ServerConfig{
|
||||||
Name: "nixos-options",
|
Name: "nixos-options",
|
||||||
Version: "0.1.0",
|
Version: "0.1.1",
|
||||||
DefaultChannel: "nixos-stable",
|
DefaultChannel: "nixos-stable",
|
||||||
SourceName: "nixpkgs",
|
SourceName: "nixpkgs",
|
||||||
Instructions: `NixOS Options MCP Server - Search and query NixOS configuration options.
|
Instructions: `NixOS Options MCP Server - Search and query NixOS configuration options.
|
||||||
@@ -47,7 +47,7 @@ This ensures option documentation matches the nixpkgs version the project actual
|
|||||||
func DefaultHomeManagerConfig() ServerConfig {
|
func DefaultHomeManagerConfig() ServerConfig {
|
||||||
return ServerConfig{
|
return ServerConfig{
|
||||||
Name: "hm-options",
|
Name: "hm-options",
|
||||||
Version: "0.1.0",
|
Version: "0.1.1",
|
||||||
DefaultChannel: "hm-stable",
|
DefaultChannel: "hm-stable",
|
||||||
SourceName: "home-manager",
|
SourceName: "home-manager",
|
||||||
Instructions: `Home Manager Options MCP Server - Search and query Home Manager configuration options.
|
Instructions: `Home Manager Options MCP Server - Search and query Home Manager configuration options.
|
||||||
|
|||||||
@@ -7,7 +7,7 @@
|
|||||||
|
|
||||||
buildGoModule {
|
buildGoModule {
|
||||||
inherit pname src;
|
inherit pname src;
|
||||||
version = "0.1.0";
|
version = "0.1.1";
|
||||||
|
|
||||||
vendorHash = "sha256-D0KIxQC9ctIAaHBFTvkhBE06uOZwDUcIw8471Ug2doY=";
|
vendorHash = "sha256-D0KIxQC9ctIAaHBFTvkhBE06uOZwDUcIw8471Ug2doY=";
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user