Pointframe

# Pointframe

<p align="center">
  <a href="https://dimitar-radenkov.github.io/Pointframe/">
    <img src="website/app-icon.png" alt="Pointframe icon" width="48" height="48">
  </a>
</p>

<h1 align="center">Pointframe</h1>


<p align="center">
  <b>A free Windows screenshot and recording tool built for fast bug reports, walkthroughs, and support replies.</b><br>
  Capture a region, a window, or a whole monitor — annotate, blur, record to MP4/GIF, and extract text with OCR.<br>
  Drive it from the tray app, the standalone CLI, or an AI agent over MCP.
</p>

<p align="center">
  <b>🌐 <a href="https://dimitar-radenkov.github.io/Pointframe/">Visit the Official Website</a></b>
</p>

<p align="center">
  <a href="https://github.com/dimitar-radenkov/Pointframe/actions/workflows/ci.yml"><img src="https://github.com/dimitar-radenkov/Pointframe/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://codecov.io/gh/dimitar-radenkov/Pointframe"><img src="https://codecov.io/gh/dimitar-radenkov/Pointframe/branch/master/graph/badge.svg" alt="codecov"></a>
  <a href="https://github.com/dimitar-radenkov/Pointframe/releases/latest"><img src="https://img.shields.io/github/v/release/dimitar-radenkov/Pointframe?color=success" alt="Latest release"></a>
  <a href="https://github.com/microsoft/winget-pkgs/tree/master/manifests/d/DimitarRadenkov/Pointframe"><img src="https://img.shields.io/winget/v/DimitarRadenkov.Pointframe?label=winget&color=blue" alt="winget"></a>
  <a href="https://github.com/dimitar-radenkov/Pointframe/releases"><img src="https://img.shields.io/github/downloads/dimitar-radenkov/Pointframe/total?label=downloads&color=purple" alt="Downloads"></a>
  <a href="https://github.com/dimitar-radenkov/Pointframe/releases/latest/download/Pointframe.Cli-win-x64.zip"><img src="https://img.shields.io/github/downloads/dimitar-radenkov/Pointframe/latest/Pointframe.Cli-win-x64.zip?label=cli%20downloads&color=orange" alt="CLI downloads"></a>
  <a href="https://github.com/dimitar-radenkov/Pointframe/releases/latest/download/Pointframe.Mcp-win-x64.mcpb"><img src="https://img.shields.io/github/downloads/dimitar-radenkov/Pointframe/latest/Pointframe.Mcp-win-x64.mcpb?label=mcp%20downloads&color=orange" alt="MCP downloads"></a>
</p>

<p align="center">
  <b>☕ If Pointframe saves you time, consider <a href="https://paypal.me/DimitarRadenkov">buying me a beer</a>:</b><br>
  <a href="https://paypal.me/DimitarRadenkov"><img src="https://img.shields.io/badge/PayPal-donate-blue?logo=paypal" alt="PayPal"></a>
  <a href="https://revolut.me/dimitarradenkov"><img src="https://img.shields.io/badge/Revolut-donate-black?logo=revolut" alt="Revolut"></a>
</p>

<p align="center">
  <video src="https://github.com/user-attachments/assets/bb6387d7-5ab9-4e91-91d5-fbe539a7ad13" width="100%" controls autoplay loop muted></video>
</p>

## 🚀 Quick Start

Install in seconds with the Windows Package Manager:

Starting with the `5.0` release line, the winget package ID is `DimitarRadenkov.Pointframe`.

```powershell
winget install DimitarRadenkov.Pointframe
```

*Prefer a manual install? Download the latest installer from the [Releases](https://github.com/dimitar-radenkov/Pointframe/releases) page.*

1. Install Pointframe with `winget install DimitarRadenkov.Pointframe` or download the latest installer from [Releases](https://github.com/dimitar-radenkov/Pointframe/releases).
2. Press `Print Screen` to capture a region.
3. Add arrows, text, or blur and then copy, save, pin, or record.

You can complete your first capture workflow in under a minute.

For the standalone command-line workflow, installation, artifact verification,
exit codes, and troubleshooting, see the dedicated
[Pointframe CLI README](docs/cli/README.md).

## Pointframe CLI

A self-contained Windows CLI for monitor and window discovery, PNG screenshots of a
monitor, a sub-region, or a single window, on-screen text extraction via OCR, and
whole-monitor MP4 recordings. The Pointframe desktop app, the .NET runtime, and the
.NET SDK are not required.

```powershell
winget install DimitarRadenkov.Pointframe.Cli
pointframe displays
```

winget adds a `pointframe` command to `PATH`. Each GitHub Release also includes
`Pointframe.Cli-<version>-win-x64.zip` for a manual install: extract it and run
`Pointframe.Cli.exe`.

The CLI requires an interactive Windows desktop session. It cannot capture a user's
desktop from a Windows service (session 0).

```powershell
.\Pointframe.Cli.exe displays
.\Pointframe.Cli.exe windows
.\Pointframe.Cli.exe capture --monitor '\\.\DISPLAY1' --output .\shot.png
.\Pointframe.Cli.exe capture --monitor '\\.\DISPLAY1' --region 100,100,800,600
.\Pointframe.Cli.exe capture-window --window-id 12345678
.\Pointframe.Cli.exe ocr --monitor '\\.\DISPLAY1'
.\Pointframe.Cli.exe ocr-window --window-id 12345678
.\Pointframe.Cli.exe record --monitor '\\.\DISPLAY1' --seconds 10 --output .\take1.mp4
```

Use the exact `monitorName` emitted by `displays`, or a window handle emitted by
`windows`. Every command other than `--help`/`--version` writes a single-line JSON
response to standard output on both the success and the failure path, so a script can
parse it the same way either way: success exits `0`, a runtime failure exits `1` and
carries an `Error.Code` (`target_not_found`, `target_not_capturable`, `invalid_region`,
`invalid_output_path`, `canceled`, or `capture_failed`), and invalid arguments exit `2`
with usage text on standard error.

After installing the CLI, it can install and verify the standalone MCP server
for VS Code without manual archive extraction or JSON editing:

```powershell
pointframe mcp install --client vscode
pointframe mcp doctor --client vscode
```

The installer verifies the published MCPB SHA-256, preserves unrelated VS Code
MCP entries, creates a configuration backup, and performs a real MCP handshake.
Use `pointframe mcp install --client vscode --dry-run` to validate the download
and proposed configuration without persisting changes. See the
[CLI guide](docs/cli/README.md#install-and-verify-the-mcp-server-for-vs-code)
for status, diagnostics, output contracts, and current client support.

Pass `--output <file>` (`-o`) to any command that produces a file to choose the exact
path to write; parent directories are created for you. Without it, screenshots and their
metadata sidecars are saved under `%LOCALAPPDATA%\Pointframe\Screenshots` and recordings
under `%LOCALAPPDATA%\Pointframe\Recordings`, each with a generated timestamped name.

`ocr` captures the monitor the same way `capture` does, then runs Windows OCR against
the captured image and adds a `RecognizedText` field to the JSON output (`null` when no
text is found or no OCR language pack is installed). `capture-window` and `ocr-window` do
the same for a single window by handle, using visible screen-rectangle semantics: an
occluding window may appear in the capture, and minimized, zero-size, off-screen, and
multi-monitor-spanning windows are rejected. `record` starts a direct MP4 recording, waits
for the requested `--seconds` (or an earlier Ctrl+C for a graceful early stop that still
finalizes and reports the artifact), then writes the combined session/artifact JSON;
recordings require `ffmpeg.exe` on `PATH`, via `POINTFRAME_FFMPEG_PATH`, or bundled next
to the executable.

## Pointframe MCP Server

Pointframe also ships a standalone MCP server for agents that need to inspect the Windows desktop and produce verifiable screenshot or recording artifacts. The MCP server uses `Pointframe.Engine` directly; it does not start the Pointframe tray application, create a WPF overlay, or require the full Pointframe installer.

The standalone host requires an interactive Windows desktop session. It is a local stdio server intended to be launched by VS Code, Copilot, or another MCP client.

### MCP capabilities

The server exposes:

- 🔎 `search_captures` — search the local catalog of saved screenshots by filename or indexed OCR text. Results may be incomplete while newly discovered images are indexed.
- 🗂️ `get_capture` — retrieve a catalog artifact by its opaque ID, including metadata and an optional downscaled inline preview. It never accepts arbitrary local paths.
- 🖥️ `list_displays` — return monitor identifiers, physical pixel bounds, and DPI scales.
- 🪟 `list_windows` — return visible top-level windows with handles, titles, process names, bounds, and containing monitor names. Window handles are session-local and temporary.
- 📸 `capture_monitor` — capture a named monitor, or an optional monitor-local sub-region of it, and return a PNG artifact plus metadata. The captured image is also returned inline as an image block (downscaled to at most 1600 px on its longest edge) so the calling model can see it directly; pass `includeImage: false` to get metadata only.
- 📸 `capture_window` — capture the visible screen rectangle of a window by its handle from `list_windows`. Occluding windows may appear; minimized, off-screen, and multi-monitor-spanning windows are rejected. Returns the image inline like `capture_monitor` unless `includeImage: false`.
- 🔤 `read_text_from_monitor` — capture a named monitor (optionally a sub-region) and run OCR against it, returning the PNG artifact plus recognized text (`null` when no text is found or no OCR language pack is installed). The captured image is also returned inline unless `includeImage: false`.
- 🔤 `read_text_from_window` — capture a window by handle and run OCR against it. Same screen-rectangle capture semantics as `capture_window`, and the same inline-image behavior.
- 🎥 `start_recording` — start a whole-monitor MP4 recording. `redactionRegionsCaptureLocalPixels` is optional; omit it to record without redaction.
- ⏹️ `stop_recording` — stop the active recording and return the finalized MP4 artifact, metadata, and event sidecar references.
- ⏱️ `get_recording_status` — report whether a recording is currently active and, if so, its session details and elapsed duration;