LoreKeeper MCP

# cache-builder-cli Specification **Spec ID**: `cache-builder-cli` **Change**: `implement-build-cache-flag` **Status**: Proposed ## Purpose Add CLI argument parsing to the MCP server main entry point to support a `--build-cache` flag that triggers upfront cache population mode instead of starting the MCP server. ## ADDED Requirements ### Requirement: CLI argument parsing for --build-cache flag The system SHALL support a `--build-cache` command-line flag to trigger cache building mode. **Rationale**: Provide explicit opt-in mechanism for pre-populating cache without starting the server, enabling offline usage and testing scenarios. #### Scenario: Start server in normal mode (default behavior) **Given** no command-line arguments are provided **When** `uv run lorekeeper-mcp` is executed **Then** the MCP server starts normally using `mcp.run()` **And** no cache building occurs upfront **And** cache populates lazily as requests arrive #### Scenario: Build cache with --build-cache flag **Given** the `--build-cache` flag is provided **When** `uv run lorekeeper-mcp --build-cache` is executed **Then** the cache builder is invoked instead of starting the server **And** all entities are fetched from APIs **And** entities are indexed to Marqo **And** the process exits after cache build completes **And** the MCP server does NOT start #### Scenario: Display help message **Given** the `--help` flag is provided **When** `uv run lorekeeper-mcp --help` is executed **Then** usage information is displayed including: - Script name and version - Description of the MCP server - `--build-cache` flag documentation - Exit code 0 --- ### Requirement: Exit code signaling The system SHALL exit with appropriate status codes to signal success or failure. **Rationale**: Enable automation, CI/CD, and scripting by providing standard Unix exit codes. #### Scenario: Successful cache build exits with code 0 **Given** `--build-cache` flag is used **And** cache building completes successfully **When** the process exits **Then** the exit code is `0` **And** a success message is logged #### Scenario: Critical failure exits with code 1 **Given** `--build-cache` flag is used **And** Marqo is unavailable **When** the cache builder attempts to connect **Then** an error is logged **And** the process exits with code `1` #### Scenario: Invalid arguments exit with code 2 **Given** an unknown flag `--invalid` is provided **When** `uv run lorekeeper-mcp --invalid` is executed **Then** an error message is displayed **And** the process exits with code `2` --- ### Requirement: Argparse integration The system SHALL use Python's `argparse` module for CLI argument parsing. **Rationale**: Standard library solution, self-documenting, handles edge cases, generates help text automatically. #### Scenario: Parse arguments in __main__.py **Given** command-line arguments are provided **When** the main module executes **Then** `argparse.ArgumentParser` is used to parse arguments **And** the parser is configured with: - Program name: "lorekeeper-mcp" - Description: "D&D 5e MCP Server" - `--build-cache` flag as a boolean action #### Scenario: Validate mutually exclusive modes **Given** future CLI flags may be added **When** argument parser is configured **Then** the design allows for future extension **And** argument validation is performed before mode selection --- ### Requirement: Async context handling for cache builder The system SHALL properly initialize and tear down async resources for cache building. **Rationale**: Cache builder uses async API clients and Marqo connections requiring proper lifecycle management. #### Scenario: Initialize async resources for cache build **Given** `--build-cache` flag is used **When** cache builder starts **Then** async event loop is created **And** API clients are initialized **And** Marqo client is initialized #### Scenario: Clean up async resources after cache build **Given** cache building completes **When** the process exits **Then** all API client connections are closed **And** Marqo client connection is closed **And** async event loop is shut down gracefully --- ## MODIFIED Requirements None - this is a new feature. --- ## REMOVED Requirements None - no existing functionality is removed. --- ## Cross-References - Related Spec: `cache-builder-orchestration` - Implements the actual cache building logic invoked by this CLI - Related Spec: `cache-builder-progress` - Progress reporting during cache build --- ## Notes - The `--build-cache` flag is mutually exclusive with normal server startup - Future flags can be added (e.g., `--validate-cache`, `--clear-cache`) without conflicts - Exit codes follow Unix conventions (0=success, 1=error, 2=invalid usage) - Help text is auto-generated by argparse for consistency