mcp-launchbox CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Run

npm install      # Install dependencies (also runs tsc via prepare)
npm run build    # Compile TypeScript (tsc)
npm start        # Run server (node dist/index.js)

Unit tests via node:test (built-in), linting via Biome:

npm test            # Build + run tests
npm run test:only   # Run tests without rebuilding
npm run lint        # Check for issues
npm run lint:fix    # Auto-fix issues

Environment

• LAUNCHBOX_PLATFORMS_PATH — Required. Path to the directory containing platform XML files (e.g. /mnt/d/LaunchBox/Data/Platforms).

Manual Testing

Pipe JSON-RPC messages to stdin:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize"}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n' | LAUNCHBOX_PLATFORMS_PATH=/mnt/d/LaunchBox/Data/Platforms node dist/index.js

Architecture

This is a Model Context Protocol (MCP) server that wraps a local LaunchBox game library. It communicates over stdin/stdout using JSON-RPC 2.0 — there is no HTTP server or MCP SDK dependency.

Source files:

• src/index.ts — Entrypoint: JSON-RPC error code constants, I/O helpers (send, reply, textReply, errorReply, error), env var check, library loading, reload concurrency guard, request dispatch with structural validation, readline listener, stdout error handler
• src/handlers.ts — matchesPlatform helper, applyFilters shared filter logic (platform, installed, favorite, status), createHandlers(state, reload) factory returning Record<ToolName, ToolHandler>; all 9 tool handler functions (sync except handleReloadLibrary)
• src/utils.ts — Pure helpers: result constructors (ok, fail), argument validation (parseLimit, asString, requireString), search helpers (fuseConfidence(score: number), normaliseTitle, compactResult, sortedPlatformCounts), response formatting (formatPlayTime, emptyToNull)
• src/tools.ts — Tool schema definitions with MCP annotations (as const satisfies MCPToolDefinition[]); derives ToolName union type for type-safe handler map; buildToolDefinitions(statusValues) returns dynamic tool schemas with status values injected into list_games description
• src/loader.ts — XML parsing with htmlEntities, game extraction, string interning (loadGames); AdditionalApplication parsing for game versions/storefronts (extractVersion); Fuse.js index building (full + per-platform + title-only variants), gamesByTitle (lowercase) and gamesByNormalisedTitle maps for fast-path lookups, normalisingGetFn custom Fuse getter for punctuation-normalised matching, precomputed platformCounts and duplicateGroups (buildLibrary); exports FUSE_OPTIONS and FUSE_TITLE_ONLY_OPTIONS
• src/types.ts — All type definitions: Game, GameVersion, RequestId, ToolResult, ToolHandler, MCPToolAnnotations, MCP interfaces