ksp-mods-mcp: Instructions file for Claude Code

ksp-mods-mcp — notes for Claude

Project overview

A uv Python project with two components:

• harvest CLI — downloads and indexes KSP mod metadata from CKAN-meta into a local SQLite DB
• ksp-mods-mcp — stdio MCP server that exposes search/lookup tools over that DB

Architecture

harvester/
  db.py         — SQLite schema, all query/write functions, KSP version logic
  harvest.py    — tar.gz streaming, parsing loop, CLI entry point
  enrichment.py — lazy GitHub/SpaceDock fetchers, cache read/write, TTL logic
  ckan_cache.py — CKAN download cache detection (URL hashing, ZIP scanning)
  parts.py      — KSP part extraction from cached ZIPs (CFG parser, localization)
mcp_server/
  server.py     — FastMCP tool definitions, error handling wrapper
explore_mod.py  — standalone exploration script (not part of the package)

Key design decisions

• Single tar.gz download for Pass 1 — one request gets all ~4000 mods, same approach as CKAN's own C# client. URL: https://github.com/KSP-CKAN/CKAN-meta/archive/refs/heads/master.tar.gz
• ETag-based skip — re-running harvest is a no-op if nothing changed upstream. ETag stored in the meta table.
• Schema versioning — SCHEMA_VERSION constant in db.py. run_harvest() auto-forces a re-harvest when the stored version in meta is stale. Bump SCHEMA_VERSION whenever a schema change requires re-harvest; no manual --force needed.
• mod_versions table — stores every .ckan file as a version row (~29k rows). The mods table stores one row per unique identifier, populated from the latest-by-release_date version entry (accumulated in Python during the tar pass, bulk-inserted after). Version history is used for KSP compatibility filtering.
• max_ksp_version — denormalized onto mods at harvest time. Normalized to major.minor, capped at 1.12 (KSP1 ceiling). Mods with no upper bound or no constraints default to 1.12.
• KSP version filter — prefix-based tuple comparison in Python (identifiers_supporting_ksp), not SQL. Runs against the full mod_versions table then passes a set of identifiers into the WHERE clause.
• Platform-aware DB path — defaults to ~/.local/share/ksp-mods-mcp/ckan.db (Linux) or AppData/Local/ksp-mods-mcp/ckan.db (Windows). CKAN_DB env var overrides.
• Lazy harvest on first tool call — the server triggers run_harvest() on the first tool invocation (not at startup), keeping MCP startup instant. ETag check makes subsequent calls a no-op.
• Error handling in tools — @_tool decorator catches all exceptions and returns them as {"error": "..."} JSON so the model gets a readable message rather than a traceback.
• CKAN download cache detection — ckan_cache.py scans the CKAN downloads directory once per session, builds a set of 8-char URL hashes from ZIP filenames, and answers is_cached(url) in O(1). CKAN hashes the percent-decoded URL (not the raw encoded form). download_url in mods stores all mirror URLs newline-separated so any mirror match counts. Only the latest version's URLs are checked — an older cached ZIP does not set is_cached.
• Part extraction — parts.py opens a cached ZIP, scans GameData/{identifier}/Parts/**/*.cfg, parses KSP's CFG format (brace-depth tracking for MODULE/RESOURCE sub-blocks), and resolves #LOC_... strings from GameData/{identifier}/Localization/en-us.cfg. Bundled deps under other GameData/ subdirectories are ignored.