chore: initial commit
This commit is contained in:
170
CLAUDE.md
Normal file
170
CLAUDE.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# CLAUDE.md - Project Context
|
||||
|
||||
This file provides context for Claude when working on this project.
|
||||
|
||||
## Project Overview
|
||||
|
||||
**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
|
||||
|
||||
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.
|
||||
|
||||
## Technology Stack
|
||||
|
||||
- **Language**: Go 1.25.5
|
||||
- **Build System**: Nix flakes
|
||||
- **Databases**: PostgreSQL (primary) and SQLite (lightweight alternative)
|
||||
- **Protocol**: MCP (Model Context Protocol) - JSON-RPC over stdio
|
||||
- **Module Path**: `git.t-juice.club/torjus/labmcp`
|
||||
|
||||
## Key Architectural Decisions
|
||||
|
||||
1. **Database Support**: Both PostgreSQL and SQLite
|
||||
- PostgreSQL is preferred for production use (user's preference)
|
||||
- SQLite provides lightweight alternative for simpler deployments
|
||||
- Use Go's `database/sql` interface for abstraction
|
||||
|
||||
2. **File Storage**: Store nixpkgs file contents in database during indexing
|
||||
- Better performance for the `get_file` tool
|
||||
- PostgreSQL handles large text storage well
|
||||
|
||||
3. **Revision Management**: Support multiple indexed nixpkgs revisions
|
||||
- Store git hash, date, channel name, option count
|
||||
- Allow querying specific revisions or use defaults
|
||||
- Default revision: nixos-stable (configurable)
|
||||
|
||||
4. **Indexing Approach**: Part of MCP server, blocking operation (initially)
|
||||
- Allows Claude to read flake.lock and request indexing
|
||||
- Can optimize to async later if needed
|
||||
|
||||
5. **Testing**: Aim for >80% test coverage
|
||||
- Unit tests for all components
|
||||
- Integration tests for full workflows
|
||||
- Benchmarks for indexing and query performance
|
||||
|
||||
## MCP Tools to Implement
|
||||
|
||||
### Core Search & Query
|
||||
1. **`search_options`** - Fuzzy/partial matching search
|
||||
- Parameters: revision, query, optional filters (type, namespace, hasDefault)
|
||||
- Returns: matching options with basic metadata
|
||||
|
||||
2. **`get_option`** - Get full details for specific option
|
||||
- Parameters: revision, option_path, optional depth
|
||||
- Returns: name, type, default, example, description, file paths
|
||||
- Default: direct children only (one level deep)
|
||||
- Includes related/nearby options in same namespace
|
||||
|
||||
3. **`get_file`** - Fetch nixpkgs source file contents
|
||||
- Parameters: revision, file_path
|
||||
- Returns: file contents
|
||||
- Security: validate paths, no traversal, nixpkgs-only
|
||||
|
||||
### Revision Management
|
||||
4. **`index_revision`** - Index a specific nixpkgs revision
|
||||
- Parameters: git_hash (full or short)
|
||||
- Process: fetch nixpkgs, extract options.json, populate DB
|
||||
- Returns: summary (option count, duration, etc.)
|
||||
|
||||
5. **`list_revisions`** - List indexed revisions
|
||||
- Returns: git hash, date, channel name, option count
|
||||
|
||||
6. **`delete_revision`** - Prune old/unused revisions
|
||||
- Parameters: revision identifier
|
||||
- Returns: confirmation of deletion
|
||||
|
||||
### Channel Support
|
||||
- Support friendly aliases: `nixos-unstable`, `nixos-24.05`, `nixos-23.11`, etc.
|
||||
- Can be used in place of git hashes in all tools
|
||||
|
||||
## Database Schema (Planned)
|
||||
|
||||
**Tables:**
|
||||
- `revisions` - nixpkgs git hash, date, channel name, metadata
|
||||
- `options` - per revision: name, type, default, example, description
|
||||
- `declarations` - file paths where options are declared
|
||||
- `files` - cached nixpkgs file contents for `get_file` tool
|
||||
|
||||
**Indexes:**
|
||||
- Full-text search on option names and descriptions
|
||||
- B-tree indexes on revision + option name
|
||||
- Namespace prefix indexes for category filtering
|
||||
|
||||
## Repository Structure (Planned)
|
||||
|
||||
```
|
||||
labmcp/
|
||||
├── cmd/
|
||||
│ └── nixos-options/ # MCP server binary
|
||||
│ └── main.go
|
||||
├── internal/
|
||||
│ ├── mcp/ # MCP protocol implementation
|
||||
│ │ ├── server.go
|
||||
│ │ └── types.go
|
||||
│ ├── database/ # Database abstraction
|
||||
│ │ ├── interface.go
|
||||
│ │ ├── postgres.go
|
||||
│ │ └── sqlite.go
|
||||
│ └── nixos/ # NixOS options specific logic
|
||||
│ ├── search.go
|
||||
│ └── types.go
|
||||
├── scripts/
|
||||
│ └── populate-db.go # Tool to populate database
|
||||
├── schema/
|
||||
│ └── schema.sql # Database schema
|
||||
├── flake.nix # Nix build configuration
|
||||
├── go.mod
|
||||
├── TODO.md # Detailed task list
|
||||
├── CLAUDE.md # This file
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
**Primary Use Case**: Claude can help users find and understand NixOS options
|
||||
- "What options are available for nginx?"
|
||||
- "Show me the services.caddy.* options"
|
||||
- "What's the default value for services.postgresql.enable?"
|
||||
- User shares a flake.lock → Claude indexes that nixpkgs version → answers questions about options in that specific version
|
||||
|
||||
**Secondary Use Case**: Explore module implementations
|
||||
- If option description is unclear, fetch the actual module source
|
||||
- Understand how complex options are structured
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- **Unit Tests**: All components with mocks where appropriate
|
||||
- **Integration Tests**: Full indexing pipeline, MCP tool invocations
|
||||
- **Benchmarks**: Indexing time, query performance, memory usage
|
||||
- **Test Fixtures**: Sample options.json, mock repositories
|
||||
- **Coverage Goal**: >80% on core logic, 100% on database operations
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Should `index_revision` be blocking or async? (Currently: blocking, optimize later)
|
||||
2. Should we auto-update channel aliases or manual only?
|
||||
|
||||
## Current Status
|
||||
|
||||
**Planning phase** - architecture and features defined, ready to begin implementation.
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Design and implement database schema
|
||||
2. Set up project structure (directories, Go modules)
|
||||
3. Implement database abstraction layer
|
||||
4. Implement MCP protocol basics
|
||||
5. Build indexing logic
|
||||
6. Implement MCP tools
|
||||
7. Create Nix package in flake.nix
|
||||
8. Write tests and benchmarks
|
||||
|
||||
## Notes for Claude
|
||||
|
||||
- User prefers PostgreSQL over SQLite (has homelab infrastructure)
|
||||
- User values good test coverage and benchmarking
|
||||
- Project should remain generic to support future MCP servers
|
||||
- Nix flake must provide importable packages for other repos
|
||||
- Use `database/sql` interface for database abstraction
|
||||
- File paths in responses should use format `path/to/file.go:123`
|
||||
Reference in New Issue
Block a user