Torjus Håkestad
9352fd1f6e
- Add installation instructions (nix flakes, go install) - Add MCP server configuration example - Add CLI examples for all commands - Document environment variables and database connection strings - List available MCP tools Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
170 lines
3.3 KiB
Markdown
170 lines
3.3 KiB
Markdown
# LabMCP
|
|
|
|
A collection of Model Context Protocol (MCP) servers written in Go.
|
|
|
|
## NixOS Options MCP Server
|
|
|
|
Search and query NixOS configuration options across multiple nixpkgs revisions. Designed to help Claude (and other MCP clients) answer questions about NixOS configuration.
|
|
|
|
### Features
|
|
|
|
- Full-text search across option names and descriptions
|
|
- Query specific options with type, default, example, and declarations
|
|
- Index multiple nixpkgs revisions (by git hash or channel name)
|
|
- Fetch nixpkgs module source files
|
|
- Support for PostgreSQL and SQLite backends
|
|
|
|
## Installation
|
|
|
|
### Using Nix Flakes
|
|
|
|
```bash
|
|
# Build the package
|
|
nix build github:torjus/labmcp
|
|
|
|
# Or run directly
|
|
nix run github:torjus/labmcp -- --help
|
|
```
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
go install git.t-juice.club/torjus/labmcp/cmd/nixos-options@latest
|
|
```
|
|
|
|
## Usage
|
|
|
|
### As MCP Server
|
|
|
|
Configure in your MCP client (e.g., Claude Desktop):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"nixos-options": {
|
|
"command": "nixos-options",
|
|
"args": ["serve"],
|
|
"env": {
|
|
"NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Then start the server:
|
|
|
|
```bash
|
|
nixos-options serve
|
|
```
|
|
|
|
### CLI Examples
|
|
|
|
**Index a nixpkgs revision:**
|
|
|
|
```bash
|
|
# Index by channel name
|
|
nixos-options index nixos-unstable
|
|
|
|
# Index by git hash
|
|
nixos-options index e6eae2ee2110f3d31110d5c222cd395303343b08
|
|
|
|
# Index with file contents (enables get_file tool, slower)
|
|
nixos-options index --files nixos-unstable
|
|
```
|
|
|
|
**List indexed revisions:**
|
|
|
|
```bash
|
|
nixos-options list
|
|
```
|
|
|
|
**Search for options:**
|
|
|
|
```bash
|
|
# Basic search
|
|
nixos-options search nginx
|
|
|
|
# Limit results
|
|
nixos-options search -n 10 postgresql
|
|
|
|
# Search in specific revision
|
|
nixos-options search -r nixos-unstable firewall
|
|
```
|
|
|
|
**Get option details:**
|
|
|
|
```bash
|
|
nixos-options get services.nginx.enable
|
|
nixos-options get services.postgresql.package
|
|
```
|
|
|
|
**Delete an indexed revision:**
|
|
|
|
```bash
|
|
nixos-options delete nixos-23.11
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `NIXOS_OPTIONS_DATABASE` | Database connection string | `sqlite://nixos-options.db` |
|
|
|
|
### Database Connection Strings
|
|
|
|
**SQLite:**
|
|
```bash
|
|
export NIXOS_OPTIONS_DATABASE="sqlite:///path/to/database.db"
|
|
export NIXOS_OPTIONS_DATABASE="sqlite://:memory:" # In-memory
|
|
```
|
|
|
|
**PostgreSQL:**
|
|
```bash
|
|
export NIXOS_OPTIONS_DATABASE="postgres://user:pass@localhost/nixos_options?sslmode=disable"
|
|
```
|
|
|
|
### Command-Line Flags
|
|
|
|
The database can also be specified via the `-d` or `--database` flag:
|
|
|
|
```bash
|
|
nixos-options -d "postgres://localhost/nixos" serve
|
|
nixos-options -d "sqlite://my.db" index nixos-unstable
|
|
```
|
|
|
|
## MCP Tools
|
|
|
|
When running as an MCP server, the following tools are available:
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `search_options` | Search for options by name or description |
|
|
| `get_option` | Get full details for a specific option |
|
|
| `get_file` | Fetch source file contents from nixpkgs |
|
|
| `index_revision` | Index a nixpkgs revision |
|
|
| `list_revisions` | List all indexed revisions |
|
|
| `delete_revision` | Delete an indexed revision |
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Enter development shell
|
|
nix develop
|
|
|
|
# Run tests
|
|
go test ./...
|
|
|
|
# Run benchmarks
|
|
go test -bench=. ./internal/database/...
|
|
|
|
# Build
|
|
go build ./cmd/nixos-options
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|