# NixOS MCP Server

A Model Context Protocol (MCP) server that enables searching NixOS configuration options directly from Claude Code.

## Features

- Search NixOS configuration options by keyword or phrase
- Returns option names, types, default values, and descriptions
- Pagination support for large result sets
- Built with TypeScript and compatible with Node 24+

## Requirements

- Node.js 24 or later (for native TypeScript support)
- npm or yarn

## Installation

1. Clone the repository:
```bash
cd /path/to/nixos-mcp
npm install
```

## Configuration for Claude Code

To use this MCP server with Claude Code, you need to configure it in Claude Code's configuration file.

### Linux/macOS

Edit `~/.config/claude/claude_code_config.json`:

```json
{
  "mcpServers": {
    "nixos-search": {
      "command": "node",
      "args": [
        "/absolute/path/to/nixos-mcp/src/index.ts"
      ]
    }
  }
}
```

### Windows

Edit `%APPDATA%\claude\claude_code_config.json`:

```json
{
  "mcpServers": {
    "nixos-search": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\nixos-mcp\\src\\index.ts"
      ]
    }
  }
}
```

### Restart Claude Code

After adding the configuration, restart Claude Code for the MCP server to be loaded.

## Usage

Once configured, you can search NixOS options directly from Claude Code. Here are some example queries:

- "Search for nginx options in NixOS"
- "Find networking firewall configuration options"
- "What NixOS options are available for SSH?"
- "Search for services.postgresql options"

## Available Tool

### `search_nixos_options`

Searches NixOS configuration options.

**Parameters:**

- `query` (string, required): Search query for NixOS options
  - Examples: "nginx", "networking firewall", "services.postgresql"

- `from` (number, optional): Starting index for pagination
  - Default: 0
  - Use this to fetch subsequent pages of results

- `size` (number, optional): Number of results per page
  - Default: 20
  - Range: 1-50

**Example:**

```
search_nixos_options {
  query: "nginx services",
  size: 10
}
```

**Response Format:**

```
Found X results for "query":

1. option.name.here
   Type: string
   Default: "default value"
   Description: Description of the option...

2. another.option.name
   Type: boolean
   Default: false
   Description: Another option description...

---
Showing results 1-10 of X total
```

## Development

### Run the Server Locally

To test the server without configuring Claude Code:

```bash
npm start
```

### Code Quality

Format code:
```bash
npm run format
```

Type check:
```bash
npm run typecheck
```

## Features

- **Efficient Search**: Uses the official NixOS search API endpoint
- **NixOS 25.11**: Searches against the latest NixOS channel (25.11)
- **Type-Safe**: Full TypeScript type definitions
- **Validated Input**: Zod schema validation for all inputs
- **Error Handling**: Graceful error messages for invalid queries or API issues
- **Pagination Support**: Handle large result sets efficiently

## Architecture

```
src/
├── index.ts              # MCP server entry point
├── types.ts              # TypeScript type definitions
├── nixos-client.ts       # NixOS API client
└── tools/
    └── search-options.ts # Search tool implementation
```

## Troubleshooting

### Server won't start

- Ensure you have Node 24 or later: `node --version`
- Check that the path to `src/index.ts` is correct in the configuration
- Look for error messages in Claude Code's MCP server logs

### No results found

- Try more specific search terms
- Use common NixOS option names or prefixes (e.g., "services.nginx", "networking")
- Check the [NixOS search portal](https://search.nixos.org) for reference

### Connection issues

- Make sure the config file syntax is valid JSON
- Verify the absolute path is correct
- Restart Claude Code after updating the configuration

## API Details

This server uses the official NixOS search API:
- **Endpoint**: `https://search.nixos.org/backend/latest-44-nixos-25.11/_search`
- **Channel**: NixOS 25.11
- **Type**: Only searches configuration options (not packages)

## License

ISC