---
phase: 11-frame-repository-and-subset-grid-compilation
plan: 03
subsystem: api
tags: [mcp, grid-compilation, frame-query, pixel-compare, sharp, repository]

requires:
  - phase: 11-01
    provides: "RepositoryManager, frame-query module (applyQuery, sampleFrames), repository-types"
  - phase: 11-02
    provides: "start_repository_capture, list_repository_sessions, delete_repository_session, get_capture_status repository fallback"
provides:
  - "list_repository_frames MCP tool with change metrics and change_summary"
  - "compile_subset_grid MCP tool with label overlay, diagnostics, and metadata"
  - "escapeXml utility for SVG injection prevention"
affects: [verification, integration-tests]

tech-stack:
  added: []
  patterns: [multi-content-block MCP responses (image + text metadata), SVG label overlay via sharp composite]

key-files:
  created: []
  modified: [src/server.ts]

key-decisions:
  - "Used single 'session' param accepting ID or name (matching delete_repository_session pattern) rather than separate session_id/session_name"
  - "change_summary computed from timing gaps only (no pixel loading) for performance -- longestIdleMs and densest 5s window"
  - "Label overlay uses SVG text composited at top of grid via sharp, with escapeXml for injection prevention"
  - "Both tools committed atomically since they share imports and the same file"

patterns-established:
  - "Multi-content-block tool responses: image block first (for LLM vision), text metadata block second"
  - "escapeXml helper for any user-provided text embedded in SVG"

requirements-completed: [D-14, D-15, D-16, D-17, D-19, D-20, D-21, D-22, D-25]

duration: 2min
completed: 2026-04-13
---

# Phase 11 Plan 03: Query and Compilation MCP Tools Summary

**list_repository_frames and compile_subset_grid MCP tools enabling frame inspection with change metrics and on-demand subset grid compilation with label overlay**

## Performance

- **Duration:** 2 min
- **Started:** 2026-04-13T13:00:02Z
- **Completed:** 2026-04-13T13:02:32Z
- **Tasks:** 2
- **Files modified:** 1

## Accomplishments
- Registered list_repository_frames tool with query filtering, optional per-frame pixel change metrics, and timing-based change_summary
- Registered compile_subset_grid tool that loads frames from disk, compiles via existing compileGrid(), supports label overlay, per-compilation diagnostics (delta_highlight, compress_idle, jpeg_quality), and returns base64 JPEG image with metadata
- Added escapeXml helper to prevent SVG injection in label overlays (T-11-09)
- Both tools support session resolution by ID or name and echo back query params

## Task Commits

Each task was committed atomically:

1. **Task 1: Register list_repository_frames tool** - `0cf6b75` (feat) -- includes Task 2 changes as both tools share the same file and imports
2. **Task 2: Register compile_subset_grid tool** - included in `0cf6b75` (same commit, same file)

## Files Created/Modified
- `src/server.ts` - Added list_repository_frames and compile_subset_grid MCP tools, imports for applyQuery, pixel-compare, readFile, sharp, and escapeXml helper

## Decisions Made
- Used single `session` param (ID or name) matching existing delete_repository_session pattern rather than separate session_id/session_name fields
- change_summary uses timing-based analysis (gap detection, sliding window density) rather than loading pixel data for the full session, since pixel comparison of all frames would be too expensive
- Label overlay height fixed at 28px with semi-transparent black background, matching common overlay patterns
- Combined both tasks into a single commit since they share the same file, same imports, and are logically coupled

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered
- Pre-existing vitest type errors in test files (not related to this plan's changes) -- ignored as out of scope

## User Setup Required
None - no external service configuration required.

## Next Phase Readiness
- All 6 repository tools now registered: start_repository_capture, get_capture_status (extended), list_repository_sessions, list_repository_frames, delete_repository_session, compile_subset_grid
- Full repository feature set complete: capture, inspect, query, compile, delete
- Ready for integration testing and verification

---
*Phase: 11-frame-repository-and-subset-grid-compilation*
*Completed: 2026-04-13*