yashsindya2014-hash/frame-trace-mcp

FrameHarbor is an ambient, always-on visual journal for software quality workflows. Where traditional QA tools capture a single screenshot at a moment of failure, FrameHarbor continuously weaves a rolling tapestry of frames from your desktop or device viewport, then exposes that tapestry to AI assistants through the Model Context Protocol (MCP). Think of it as a lighthouse keeper for your screen: it never sleeps, it remembers the shape of every wave, and when the storm hits, the beam of evidence is already waiting.

Built for teams who treat quality assurance as an observational science rather than a reactionary chore, FrameHarbor transforms passive screen time into structured, searchable, context-rich artifacts. Each frame is a breadcrumb; each session is a trail; each investigation is a story you can replay frame by frame alongside an AI collaborator.

Most observability stacks were designed for servers, not for the messy, human, pixel-driven world of front-end behavior. A backend trace tells you a function took 340ms; it will not tell you that the toast notification appeared underneath the modal, that the spinner froze at 87%, or that the cursor visibly crossed into a dead zone. FrameHarbor was born from the conviction that visual memory is a first-class debugging primitive.

The metaphor is a harbor. Ships (events) come and go, but the harbor itself persists — logging tides, weather, and the shape of every hull that passed. FrameHarbor is that harbor for your viewport. It runs quietly in the background, discards what ages out of relevance, and preserves a rolling window of frames that any MCP-aware assistant can later query with natural language.

• Core Capabilities
• Architectural Overview
• MCP Surface Area
• Feature Highlights
• Responsive and Adaptive Interface
• Multilingual Reach
• Availability and Assistance
• Use Cases and Stories
• Search and Retrieval Semantics
• Privacy, Consent, and Boundaries
• Performance Envelope
• Extensibility
• Roadmap for 2026
• Frequently Asked Questions
• Contribution Culture
• License
• Disclaimer

FrameHarbor is not a screenshot tool with delusions of grandeur. It is a temporal evidence pipeline. Its capabilities stack like sediment:

• Ambient Capture Loop — A lightweight recorder samples the viewport at configurable cadence, holding a bounded ring buffer so memory stays predictable even across twelve-hour sessions.
• Frame Fingerprinting — Every frame receives perceptual hashes plus structural metadata, enabling near-duplicate collapse so you are not drowning in identical stills of an idle browser tab.
• Semantic Labeling — Optional lightweight classifiers tag frames with plain-language descriptors (loading state, error banner, form focus, navigation transition) so retrieval feels like conversation rather than grep.
• Session Chapters — Long recordings are automatically segmented into chapters based on visual novelty, producing a table of contents an assistant can skim.
• Evidence Packs — Export a curated sequence as a portable evidence pack: a container holding frames, timestamps, annotations, and a human-readable manifest.
• Live Query Bridge — Exposes the buffer through MCP so assistants can ask for "the moment right before the layout shifted."
• Retention Policies — Declarative rules govern what persists, what decays, and what must never leave the device.

FrameHarbor is organized into four cooperating strata. Picture a lighthouse: the lamp room, the stairwell, the keeper's quarters, and the dock.

1. Capture Stratum — Native hooks into compositor output, cross-platform, with graceful degradation when permissions are constrained. Operating system selection of capture backends is automatic.
2. Index Stratum — Combined perceptual hashing, timestamp geometry, and descriptor vectors form the retrieval substrate. Everything is local-first; there is no mandatory cloud leg.
3. Exchange Stratum — The MCP server surfaces tools, resources, and prompts. Assistants can list sessions, request frames by semantic description, and pull evidence packs.
4. Presentation Stratum — A responsive viewer with timeline scrubbing, chapter navigation, side-by-side comparison, and annotation overlays.

Each stratum communicates through a typed internal contract, which means replacing any layer (for instance, swapping the indexer for a domain-specific model) does not cascade into rewrites.

FrameHarbor honors the Model Context Protocol as its primary integration language. The exposed surface includes:

• sessions.list — Enumerate recorded sessions with duration, size, and chapter count.
• sessions.describe — Retrieve a natural-language summary plus descriptor histogram.
• frames.window — Extract a bounded temporal window around an anchor timestamp.
• frames.search — Semantic search across descriptors, hashes, and annotations.
• evidence.export — Produce an evidence pack for a selected sequence.
• annotations.create — Attach human or machine notes to a frame or range.
• timeline.chapters — List auto-generated chapter boundaries with representative frames.

Assistants can chain these calls fluidly. A typical investigation might begin with a semantic search, jump to a chapter boundary, pull a window, and finish by exporting a pack — all within one conversational turn.

• Rolling Temporal Buffer — Memory-bounded by design; the harbor never floods its own docks.
• Perceptual Deduplication — Identical frames collapse into single entries with expanded time spans.
• Responsive UI — The viewer reshapes itself across phones, tablets, ultrawide monitors, and embedded panels without losing timeline fidelity.
• Multilingual Support — Interface strings, timestamp formats, and descriptor vocabularies localize gracefully across major language families.
• 24/7 Customer Support — A rotating coverage model ensures questions at 3 a.m. in one timezone are answered by daylight in another.
• Local-First Privacy — Capture and indexing run on your machine; nothing is transmitted unless you deliberately export.
• Deterministic Playback — Frame ordering is stable across machines, which matters when two engineers compare notes.
• Annotation Layers — Separate human notes from machine descriptors so neither pollutes the other.
• Export Manifests — Evidence packs include a schema-described manifest for downstream tooling.
• Adaptive Cadence — Capture rate can slow during idle periods and tighten during bursts of activity.
• Crash-Safe Journals — An interrupted session is recoverable; the harbor logs even its own rough weather.

The viewer behaves like water: it takes the shape of its container. On a narrow phone screen, the timeline becomes a vertical ribbon and chapters fold into an accordion. On a wide desktop, frames fan out into a filmstrip with a synchronized scrubber. On a tablet in landscape, a split view places the descriptor panel beside the frame itself. Accessibility is treated as a first-class citizen: keyboard navigation, screen-reader labels, reduced-motion respect, and high-contrast palettes ship by default rather than as an afterthought.

Quality work is global work. FrameHarbor ships with interface translations and, more importantly, a descriptor vocabulary that adapts to locale. Timestamps follow regional conventions, right-to-left layouts are honored, and exported manifests can be emitted with localized human-readable summaries while keeping machine fields canonical. This dual-track approach means a reviewer in one region and an assistant configured in another can discuss the same frame without ambiguity.

Every session deserves a keeper. The support model behind FrameHarbor is deliberately round-the-clock, with coverage handoffs that follow the sun. Documentation includes guided tours, conceptual essays, and a troubleshooting atlas. When something misbehaves, the assistance channels include structured intake forms that automatically attach relevant diagnostic frames — because the best bug report is one that already contains its own evidence.

• The Vanishing Tooltip — A product team chases an intermittent tooltip that never appears in static screenshots. FrameHarbor's rolling buffer catches the exact millisecond the tooltip rendered behind another layer.
• The Slow Checkout — A commerce squad wants to know where users stall. Chapter segmentation reveals a recurring freeze at the payment step, and semantic search surfaces every frame tagged with a spinner descriptor.
• The Accessibility Audit — An auditor records a session navigating with keyboard only. Frames are annotated and exported as an evidence pack that becomes the backbone of a remediation ticket.
• The Flaky CI Companion — A desktop harness runs alongside an automated suite. When a test fails visually but passes logically, the harbor already holds the preceding ninety seconds.
• The Design Review Replay — A designer walks through a prototype, and the resulting chapters serve as a timestamped visual changelog for stakeholders who missed the call.
• The Support Escalation — A customer describes a glitch in prose. Support asks for an evidence pack, and the conversation shifts from words to frames.

Search in FrameHarbor is layered. At the surface, keyword matching against annotations and chapter titles feels familiar. Beneath that, descriptor vectors allow paraphrased queries — asking for "the screen where the button went grey" rather than "disabled primary action." Deeper still, perceptual hashes allow visual similarity queries: hand it a reference frame and it finds its relatives across sessions. The three layers compose, so an assistant can narrow by time, then by meaning, then by appearance.

FrameHarbor assumes screens contain sensitive material. Therefore:

• Capture is opt-in per session, with prominent indicators while active.
• Redaction regions can be defined per application or per window title pattern; those regions are masked before indexing.
• Retention defaults to a short rolling window, extended only by explicit policy.
• Exports are explicit, local, and accompanied by a manifest describing exactly what left the harbor.
• No telemetry about frame content is ever collected; diagnostics concern performance counters only.

The recorder is engineered to be a quiet tenant. Capture and hashing run on a dedicated worker pool sized to leave the interactive thread untouched. Memory is governed by the ring buffer's configured ceiling, and disk writes are batched to avoid thrashing. In measured scenarios on representative hardware, the steady-state overhead remains modest even during hour-long sessions, and cadence adaptation further reduces cost during idle stretches.

FrameHarbor exposes extension points at every stratum:

• Capture Plugins — Add new sources such as virtual displays or headless renderers.
• Descriptor Models — Swap in domain-specific classifiers trained on your product's visual language.
• Index Adapters — Persist the index to an external store when multi-machine federation is desired.
• Export Formats — Extend the evidence pack schema with team-specific metadata.
• MCP Tool Augmentations — Register custom tools that compose existing primitives.

Extensions declare capabilities through a manifest, and the core refuses to load anything that requests permissions beyond its declaration.

• Q1 2026 — Federated index synchronization across a trusted team mesh.
• Q2 2026 — Audio waveform alignment so spoken observations sync with visual frames.
• Q3 2026 — On-device descriptor model fine-tuning from user corrections.
• Q4 2026 — Evidence pack signing and chain-of-custody metadata for regulated environments.

The roadmap is a living document; priorities shift with community feedback, and each milestone ships behind a feature flag so early adopters can taste before the general table is set.

Does FrameHarbor replace my existing bug tracker?
No — it feeds it. The harbor produces evidence; your tracker remains the ledger of decisions.

Can I run it entirely offline?
Yes. The default configuration never contacts a network.

How long can a session run?
As long as your retention ceiling and disk budget allow; the ring buffer guarantees memory stays bounded regardless.

What happens if the assistant asks for a frame that has aged out?
The harbor returns a structured miss with the nearest surviving neighbors, so the assistant can explain the gap rather than hallucinate.

Is the interface usable without an assistant?
Absolutely. MCP is an enhancement, not a dependency.

Contributions are welcomed with the warmth of a harbor town. Before opening a change, please review the conceptual essays in the documentation folder to understand why the strata are shaped as they are. Tests accompany behavior changes; descriptors accompany new classifiers; translations accompany new interface strings. A changelog entry written in plain language is considered part of the work, not a formality. Discussion is encouraged, and disagreement is treated as a design signal rather than a nuisance.

FrameHarbor is released under the MIT License. The full text is available at the canonical license reference:

https://opensource.org/licenses/MIT

You are welcome to use, adapt, and redistribute the work in accordance with those terms. Attribution is appreciated but the license itself defines the obligations.

FrameHarbor records visual output of a device. You are responsible for ensuring that your use complies with applicable workplace policies, privacy regulations, and consent requirements in your jurisdiction. The maintainers make no warranty regarding fitness for a particular compliance regime. Always inform participants before recording, honor redaction policies, and treat captured frames with the same care you would treat any other sensitive artifact. Roadmap dates are aspirational and provided for planning texture rather than contractual commitment. The year referenced throughout this document is 2026, and any forward-looking statements should be read in that spirit.