# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
NixOS MCP (Model Context Protocol) Server is a tool that exposes NixOS configuration options search functionality as an MCP server. This allows Claude Code to search NixOS options directly through the `search_nixos_options` tool.
The server communicates with the official NixOS search API (elasticsearch backend) and formats results for display.
## Development Commands
- `npm start` - Start the MCP server locally
- `npm test` - Run all tests (matches `src/**/*.test.ts`)
- `npm run format` - Format code with Prettier
- `npm run typecheck` - Type-check the project with TypeScript
To run a single test file:
```bash
node --test src/nixos-client.test.ts
```
## Architecture
### Core Components
1. **MCP Server** (`src/index.ts`)
- Initializes the Model Context Protocol server using `@modelcontextprotocol/sdk`
- Registers the `search_nixos_options` tool with Zod input validation
- Uses stdio transport for JSON-RPC communication
- Validates input and handles errors, returning formatted responses
2. **NixOS Client** (`src/nixos-client.ts`)
- Makes authenticated HTTP requests to the NixOS search API
- Builds complex Elasticsearch query structures with multi-word support
- Handles wildcard queries for flexible searching
- Implements retry logic (2 retries) for failed requests with 30-second timeout
- Uses basic auth with a static token for API access
3. **Search Options Tool** (`src/tools/search-options.ts`)
- Implements the `search_nixos_options` tool handler
- Zod schema validates: `query` (required, non-empty string), `from` (0-based index for pagination), `size` (1-50 results)
- Formats results with type, default value, and wrapped descriptions
- Handles complex value types (strings, booleans, arrays, objects) with readable formatting
4. **Type Definitions** (`src/types.ts`)
- Defines the NixOS API response structure (elasticsearch format)
- Defines the search request body structure with bool queries
- Defines the search input schema and formatted result structure
### Data Flow
1. Claude Code calls `search_nixos_options` with a query string
2. Input validation with Zod schema in `index.ts`
3. `handleSearchOptions` in `search-options.ts` receives validated input
4. `NixOSClient.searchOptions()` builds an Elasticsearch query with:
- Multi-match queries against `option_name` and `option_description` fields
- Wildcard queries for partial word matching
- Results filtered to only "option" type documents
5. Results are formatted into human-readable text with pagination info
6. Response returned through MCP protocol
### Key Design Decisions
- **Elasticsearch Queries**: Uses complex bool queries with dis_max combining multi_match and wildcard queries. This provides flexible searching that handles both phrase matching and partial word matching.
- **Field Boosting**: option_name is heavily boosted (6x) relative to descriptions (1x) to prioritize exact option names
- **Pagination**: Implemented via `from`/`size` parameters to handle large result sets efficiently
- **Retry Logic**: Automatic retries on network issues (408, 429, 500, 502, 503, 504) with 2-retry limit
- **Text Wrapping**: Descriptions wrap at 80 characters for better readability in Claude's interface
- **Value Formatting**: Complex types are simplified for display (arrays shown inline, objects truncated)
## API Details
- **Endpoint**: `https://search.nixos.org/backend/latest-44-nixos-25.11/_search`
- **Channel**: NixOS 25.11 (latest available options)
- **Search Type**: Configuration options only (not packages)
- **Authentication**: Basic auth token included in requests
## Testing
Tests in `nixos-client.test.ts` validate:
1. Basic search functionality with "nginx" query
2. Pagination works correctly (different pages return different results)
3. Multi-word queries like "firewall networking" work as expected
Run tests with `npm test`. Tests make real API calls to the NixOS backend.
## Node.js & TypeScript
**Node.js 24+**: This project requires Node 24 or later, which has native support for:
- **Direct TypeScript Execution**: `.ts` files can be run directly without compilation (`node src/index.ts`)
- **Native Test Runner**: Built-in `node --test` command for running tests
- **Top-Level Await**: Async code can be executed at module level without wrapping in an async function
**TypeScript Configuration**: The project uses strict TypeScript settings (`strict: true`) with Node-specific module resolution. Import extensions (.ts) are required in source files due to `verbatimModuleSyntax: true`. No build step is needed; Node 24 handles TypeScript compilation automatically.
## MCP Protocol Notes
- The server uses stdio transport (stdin/stdout for JSON-RPC 2.0)
- Server name: "nixos-search", version: "1.0.0"
- All logging goes to stderr to avoid interfering with JSON-RPC communication on stdout
- Input validation errors are caught and returned as error responses within the MCP protocol
