New:Socket for Asana Is Now Available.Learn more
Get Started

snapmcp

Package Overview
Dependencies
Maintainers
1
Versions
8
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

snapmcp - npm Package Compare versions

Comparing version
2.3.1
to
2.3.2
+6
-0
CHANGELOG.md

@@ -8,2 +8,8 @@ # Changelog

## [2.3.2] - 2026-08-17
### Changed
- Dependabot now opens bun-ecosystem PRs (lockfile kept in sync); merged @types/node 26.2.0, playwright 1.62.1, shiki 4.4.3, action-gh-release v3
- Added `mcpName` + validated `server.json` for the MCP Registry submission
## [2.3.1] - 2026-08-17

@@ -10,0 +16,0 @@

+6
-5
{
"name": "snapmcp",
"version": "2.3.1",
"mcpName": "io.github.reeinharddd/snapmcp",
"version": "2.3.2",
"description": "All-in-one MCP server for visual captures: terminal, code, browser, markdown, diffs, HTML, and PDF — via Playwright",

@@ -52,11 +53,11 @@ "keywords": [

"dependencies": {
"@modelcontextprotocol/sdk": "1.29.0",
"@modelcontextprotocol/sdk": "1.30.0",
"fast-png": "^8.0.0",
"gifenc": "^1.0.3",
"marked": "18",
"playwright": "1.61.1",
"shiki": "4.3.0"
"playwright": "1.62.1",
"shiki": "4.4.3"
},
"devDependencies": {
"@types/node": "26.0.1",
"@types/node": "26.2.0",
"typescript": "7"

@@ -63,0 +64,0 @@ },

+110
-203

@@ -6,12 +6,13 @@ <p align="center">

<p align="center">
<b>All-in-one MCP server for visual captures.</b><br/>
<b>The visual documentation MCP server.</b><br/>
Terminal · Code · Browser · Markdown · Diff · HTML · PDF · GIF<br/>
<em>One server. 13 tools. Real fidelity. Zero juggling.</em>
<em>For documentation workflows — when structured snapshots aren't enough.</em>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/snapmcp"><img src="https://img.shields.io/npm/v/snapmcp?style=flat&label=npm&color=%2306b6d4" alt="npm"/></a>
<a href="https://github.com/reeinharddd/snapmcp"><img src="https://img.shields.io/github/stars/reeinharddd/snapmcp?style=flat&color=%236366f1" alt="stars"/></a>
<img src="https://img.shields.io/badge/license-MIT-%2306b6d4" alt="MIT"/>
<img src="https://img.shields.io/badge/bun-%23f9f9f9?logo=bun" alt="bun"/>
<a href="https://www.npmjs.com/package/snapmcp"><img src="https://img.shields.io/npm/v/snapmcp?style=flat&label=npm&color=%2300d4aa" alt="npm version"/></a>
<a href="https://www.npmjs.com/package/snapmcp"><img src="https://img.shields.io/npm/dm/snapmcp?style=flat&label=downloads&color=%2300d4aa" alt="npm downloads"/></a>
<a href="https://github.com/reeinharddd/snapmcp/actions/workflows/ci.yml"><img src="https://github.com/reeinharddd/snapmcp/actions/workflows/ci.yml/badge.svg" alt="tests"/></a>
<a href="https://github.com/reeinharddd/snapmcp"><img src="https://img.shields.io/github/stars/reeinharddd/snapmcp?style=flat&color=%2300d4aa" alt="stars"/></a>
<img src="https://img.shields.io/badge/license-MIT-%2300d4aa" alt="MIT"/>
</p>

@@ -21,75 +22,17 @@

Generate screenshots of terminals, code, web pages, markdown, diffs, PDFs, and GIF animations — all through a single MCP server. **No more juggling 4 different MCP servers for your visual capture needs.**
Real terminal colors, Shiki-highlighted code, visual diffs, PDFs and GIFs — one MCP server, 13 tools, zero heavy dependencies. SSRF protection on by default. Built for agents that write documentation, not just drive browsers.
## Features
## Quick Start
| Tool | Description |
|------|-------------|
| `capture_terminal` | Terminal output with syntax-colored prompts (auto-detects real terminal theme) |
| `capture_code` | Syntax-highlighted code via Shiki (50+ languages, 27 themes) |
| `capture_browser` | Full-page or viewport screenshots (uses system Chrome profile when available) |
| `capture_file` | File → auto-detected language → highlighted screenshot |
| `capture_markdown` | Rendered markdown as a styled document |
| `capture_html` | Arbitrary HTML snippet rendered as image |
| `capture_diff` | Git diffs with green additions / red deletions |
| `capture_pdf` | URL → PDF document |
| `capture_batch` | Batch capture multiple items in one call |
| `capture_gif` | Animated GIF from multiple screenshots |
| `capture_sequence` | Side-by-side animated sequence |
| `capture_to_document` | Multi-section markdown document render |
| `snapmcp-hint` | Server capability hints for MCP clients |
Three steps, under two minutes:
## Documentation
**1. Install**
Full reference documentation at **[docs/](docs/README.md)** — organized like a site with hyperlinks between pages:
| Page | Contents |
|------|----------|
| [Getting Started](docs/getting-started.md) | Installation, quick start, MCP client setup |
| [Tools Reference](docs/tools.md) | All 13 tools with parameters and examples |
| [Configuration](docs/configuration.md) | All SNAPMCP_* env vars, themes, defaults |
| [CLI Reference](docs/cli.md) | Init, doctor, test commands |
| [Guides](docs/guides/) | Terminal capture, browser capture, GIF animation |
### v2.2 Highlights
- **Real Terminal Colors** — detects Kitty, Gnome Terminal, Alacritty, WezTerm, Xfce4, and LXTerminal configs for authentic terminal captures
- **Real Browser Profile** — finds system Chrome/Edge/Brave installations and uses your real user data directory
- **In-Project Captures** — saves to `./captures` in your current project, not an isolated directory
- **SSRF Protection** — opt-in URL protection that blocks private/internal IP ranges (enable via `SNAPMCP_SSRF_PROTECTION=true`)
- **Audit Logging** — optional structured audit log file with timestamped events
- **Centralized Brand** — consistent teal/blue ANSI output across all CLI commands
- **Zero-Dep GIF** — migrated from gifencoder to gifenc + fast-png (7 fewer security vulnerabilities)
- **Interactive Setup** — guided wizard with dependency detection and configuration
## Quick Start
```bash
# Install globally
npm install -g snapmcp
# Start the server
snapmcp
# or run without installing: npx -y snapmcp
```
Or run a quick health check:
**2. Add to Claude Code** (`~/.claude/claude.json`)
```bash
# Run the interactive setup wizard
snapmcp init
# Check system readiness
snapmcp doctor
# Generate test captures
snapmcp test
```
## Installation Guides
<details>
<summary><strong>Claude Code</strong></summary>
Add to your `~/.claude/claude.json`:
```json

@@ -109,8 +52,15 @@ {

```
</details>
**3. Capture**
Ask your agent in natural language:
> "Capture a terminal screenshot of `git log --oneline -5` and a syntax-highlighted PNG of `src/index.ts`."
The agent calls `capture_terminal` and `capture_file` — images land in `./captures/` with your real terminal theme and the chosen syntax theme applied.
<details>
<summary><strong>OpenCode</strong></summary>
<summary><strong>Other clients: OpenCode, VS Code / Cline, Docker</strong></summary>
Add to your `opencode.json`:
**OpenCode** (`opencode.json`):

@@ -132,9 +82,5 @@ ```json

```
</details>
<details>
<summary><strong>VS Code / Cline / Roo-Cline</strong></summary>
**VS Code / Cline / Roo-Cline** (`settings.json` → `cline.mcpServers`):
Add to VS Code settings (`settings.json` → `cline.mcpServers`):
```json

@@ -154,6 +100,4 @@ {

```
</details>
<details>
<summary><strong>Docker</strong></summary>
**Docker**:

@@ -169,39 +113,76 @@ ```bash

## CLI Commands
## What it looks like
SnapMCP ships with a full CLI beyond the MCP server:
<!-- TODO(demo assets): replace the static table below with three high-impact captures at the repo root:
- assets/demo-terminal.png — capture_terminal output of a real CLI session (ls -la + git log), Kitty/Gnome theme auto-detected, showing TRUE terminal colors (the unique selling point vs Playwright accessibility snapshots)
- assets/demo-code.png — capture_code output, a ~20-line TypeScript function, nord theme, window chrome on, soft shadow
- assets/demo-diff.png — capture_diff output of a real commit, green/red highlighting visible at a glance
Optional fourth: assets/demo-gif.gif — capture_gif animating 3-4 frames of a terminal typing session.
Until those exist, the real generated captures below serve as proof. -->
```
snapmcp — Start the MCP server
snapmcp init — Interactive setup wizard
snapmcp doctor — Health check for all dependencies
snapmcp test — Generate test captures (terminal + browser)
snapmcp --help — Show available tools and version
```
Real screenshots generated by snapmcp:
### `snapmcp init`
| Capture | Preview |
|---------|---------|
| Terminal (real detected colors) | <img src="docs/assets/test-terminal.png" alt="terminal capture" width="300"/> |
| Code (Shiki syntax) | <img src="docs/assets/test-code.png" alt="code capture" width="300"/> |
| Diff (green/red) | <img src="docs/assets/diff-example.png" alt="diff capture" width="300"/> |
| Markdown render | <img src="docs/assets/markdown-preview.png" alt="markdown render" width="300"/> |
Interactive wizard that:
1. Detects system state (Chrome, Playwright, output directory, theme)
2. Guides you through configuration choices
3. Installs Chromium if missing
4. Prints a ready-to-use MCP config snippet
## Why snapmcp vs Playwright MCP
### `snapmcp doctor`
Different tools for different jobs. Playwright MCP drives a browser through token-efficient accessibility snapshots; snapmcp renders pixel-faithful images for humans to read. If your agent needs to *click*, use Playwright. If it needs to *show*, use snapmcp.
Runs 7 checks:
1. Node.js version ≥ 18
2. Playwright Chromium installed
3. Output directory writable
4. SnapMCP version
5. Chrome/Chromium detected
6. System terminal theme detected
7. Environment variables valid
| Use case | snapmcp | Playwright MCP |
|----------|:-------:|:--------------:|
| Terminal capture with real colors | ✅ auto-detects Kitty, Gnome, Alacritty, WezTerm themes | ❌ no terminal support |
| Code → syntax-highlighted image | ✅ Shiki, 50+ languages, 27 themes | ❌ not its purpose |
| Git diff → visual red/green image | ✅ `capture_diff` | ❌ |
| URL → PDF document | ✅ `capture_pdf` | ❌ |
| Animated GIF from captures | ✅ `capture_gif` (zero-dep gifenc) | ❌ |
| Markdown → styled document | ✅ `capture_markdown`, `capture_to_document` | ❌ |
| Browser page screenshot | ✅ `capture_browser` (full-page or viewport) | ✅ |
| Browser **automation** (click, fill, navigate) | ❌ screenshots only | ✅ accessibility-tree driven, token-efficient — the right tool for this |
### `snapmcp test`
Most documentation pipelines pair them: Playwright MCP to *interact*, snapmcp to *document*.
Generates sample captures to verify everything works:
- `captures/test-terminal.png` — terminal screenshot
- `captures/test-code.png` — code screenshot
## Tools
| Tool | Description |
|------|-------------|
| `capture_terminal` | Terminal output with syntax-colored prompts (auto-detects real terminal theme) |
| `capture_code` | Syntax-highlighted code via Shiki (50+ languages, 27 themes) |
| `capture_browser` | Full-page or viewport screenshots (uses system Chrome profile when available) |
| `capture_file` | File → auto-detected language → highlighted screenshot |
| `capture_markdown` | Rendered markdown as a styled document |
| `capture_html` | Arbitrary HTML snippet rendered as image |
| `capture_diff` | Git diffs with green additions / red deletions |
| `capture_pdf` | URL → PDF document |
| `capture_batch` | Batch capture multiple items in one call |
| `capture_gif` | Animated GIF from multiple screenshots |
| `capture_sequence` | Side-by-side animated sequence |
| `capture_to_document` | Multi-section markdown document render |
| `snapmcp-hint` | Server capability hints for MCP clients |
## Use cases
**Automated documentation** — an agent writes a setup guide and embeds real captures: the terminal output of the install command (with your actual theme), the config file syntax-highlighted, the diff of the migration. One prompt, three `capture_*` calls, images saved next to the markdown.
**Visual QA** — after a UI change, the agent captures the affected pages with `capture_browser`, batches before/after with `capture_batch`, and assembles an animated comparison with `capture_gif` for the PR description.
**Terminal guides** — CLI tutorials where the screenshots must match what readers will see: `capture_terminal` reproduces the real prompt colors instead of a generic dark rectangle.
## Security
SSRF protection is **on by default** — no opt-in required.
| Feature | Description |
|---------|-------------|
| **SSRF Protection** | On by default (disable with `SNAPMCP_SSRF_PROTECTION=false`). Blocks IP literals (v4 + v6), localhost variants, and DNS names that resolve to private ranges (`127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7`, `fe80::/10`, etc.); every page request (redirects included) is re-checked |
| **File Allowlist** | `SNAPMCP_ALLOWED_PATHS` defaults to deny-all when unset; only explicitly allowed paths can be captured |
| **Path Traversal** | Prevents `../` escapes, symlink traversal (via realpath), and null byte injection |
| **Input Limits** | Terminal 1000 lines; code/markdown/HTML 200KB; diff 500KB; file reads 5MB; max GIF frames 60; max GIF canvas 8192×8192 |
| **Audit Log** | Optional structured JSON log file with timestamped events |
| **Chromium Sandbox** | Sandbox availability checked at startup |
## Configuration

@@ -218,3 +199,3 @@

| `SNAPMCP_PADDING` | `32` | Content padding in pixels |
| `SNAPMCP_SHADOW` | `none` | Drop shadow (`none`, `soft`, `medium`, `strong`; aliases `sm`/`md`/`lg`; invalid values fall back to `none`) |
| `SNAPMCP_SHADOW` | `none` | Drop shadow (`none`, `soft`, `medium`, `strong`; aliases `sm`/`md`/`lg`) |
| `SNAPMCP_WINDOW_CHROME` | `false` | macOS-style title bar frame |

@@ -229,85 +210,27 @@ | `SNAPMCP_BORDER_RADIUS` | `0` | Window corner radius |

### Real Fidelity
27 built-in Shiki themes: `dracula`, `one-dark-pro`, `nord`, `tokyo-night`, `catppuccin-mocha`, `catppuccin-latte`, `ayu-dark`, `ayu-light`, `vitesse-dark`, `vitesse-light`, `min-dark`, `min-light`, `poimandres`, `rose-pine`, `rose-pine-moon`, `rose-pine-dawn`, `slack-dark`, `slack-ochin`, `snazzy-light`, `github-dark-dimmed`, `github-light`, `one-light`, `solarized-light`, `solarized-dark`, `material-theme`, `material-theme-lighter`, `material-theme-ocean`
SnapMCP detects your real environment for authentic captures.
## CLI
**Terminal auto-detection** (in priority order):
SnapMCP ships with a full CLI beyond the MCP server:
| Source | Detection method |
|--------|-----------------|
| Kitty | `kitty.conf` (`foreground`, `background`, `tab_bar_style`) |
| Gnome Terminal | `dconf /org/gnome/terminal/legacy/profiles:/` |
| Alacritty | `alacritty.toml` / `alacritty.yml` (`colors.*`) |
| WezTerm | `wezterm.lua` (background detection) |
| Xfce4 Terminal | `xfce4/terminal/terminalrc` |
| LXTerminal | `lxterminal.conf` |
| COLORFGBG | Environment variable fallback |
| OS Theme | `gsettings` dark mode detection |
**Browser auto-detection** (in priority order):
1. `SNAPMCP_CHROME_EXECUTABLE` env var
2. System Chrome paths (Linux: `google-chrome`, `chromium-browser`; macOS: `/Applications/Google Chrome.app`; Windows: `%LOCALAPPDATA%\Google\Chrome`)
3. `which` / `where` PATH lookup
4. Edge / Brave / Chromium fallbacks
5. Bundled Playwright Chromium as final fallback
### Security
| Feature | Description |
|---------|-------------|
| **SSRF Protection** | **On by default** (disable with `SNAPMCP_SSRF_PROTECTION=false`). Blocks IP literals (v4 + v6), localhost variants, and DNS names that resolve to private ranges (`127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7`, `fe80::/10`, etc.); every page request (redirects included) is re-checked |
| **File Allowlist** | `SNAPMCP_ALLOWED_PATHS` defaults to deny-all when unset; only explicitly allowed paths can be captured |
| **Path Traversal** | Prevents `../` escapes, symlink traversal (via realpath), and null byte injection |
| **Input Limits** | Terminal 1000 lines; code/markdown/HTML 200KB; diff 500KB; file reads 5MB; max GIF frames 60; max GIF canvas 8192×8192 |
| **Audit Log** | Optional structured JSON log file with timestamped events |
| **Chromium Sandbox** | Sandbox availability checked at startup |
### Themes
27 built-in Shiki themes:
`dracula`, `one-dark-pro`, `nord`, `tokyo-night`, `catppuccin-mocha`, `catppuccin-latte`, `ayu-dark`, `ayu-light`, `vitesse-dark`, `vitesse-light`, `min-dark`, `min-light`, `poimandres`, `rose-pine`, `rose-pine-moon`, `rose-pine-dawn`, `slack-dark`, `slack-ochin`, `snazzy-light`, `github-dark-dimmed`, `github-light`, `one-light`, `solarized-light`, `solarized-dark`, `material-theme`, `material-theme-lighter`, `material-theme-ocean`
## Example Output
```
captures/
├── test-terminal.png # Terminal output with real detected colors
├── test-code.png # Syntax-highlighted code
├── page.png # Full-page browser screenshot
└── output.pdf # URL converted to PDF
snapmcp — Start the MCP server
snapmcp init — Interactive setup wizard (detects Chrome, terminal theme, output dir)
snapmcp doctor — Health check: 7 checks across Node, Chromium, paths, env
snapmcp test — Generate test captures (terminal + code) to verify the setup
```
**Real screenshots generated by snapmcp:**
## Documentation
| Capture | Preview |
|---------|---------|
| Terminal | <img src="docs/assets/test-terminal.png" alt="terminal" width="300"/> |
| Code | <img src="docs/assets/test-code.png" alt="code" width="300"/> |
| Doctor | <img src="docs/assets/doctor.png" alt="doctor" width="300"/> |
| Init | <img src="docs/assets/init-wizard.png" alt="init" width="300"/> |
| Diff | <img src="docs/assets/diff-example.png" alt="diff" width="300"/> |
| Config | <img src="docs/assets/config-code.png" alt="config" width="300"/> |
| Page | Contents |
|------|----------|
| [Getting Started](docs/getting-started.md) | Installation, quick start, MCP client setup |
| [Tools Reference](docs/tools.md) | All 13 tools with parameters and examples |
| [Configuration](docs/configuration.md) | All SNAPMCP_* env vars, themes, defaults |
| [CLI Reference](docs/cli.md) | Init, doctor, test commands |
| [Guides](docs/guides/) | Terminal capture, browser capture, GIF animation |
| [ARCHITECTURE.md](./ARCHITECTURE.md) | Module map, data flow, security architecture |
| [CONTRIBUTING.md](./CONTRIBUTING.md) | Dev workflow, testing guidelines, PR checklist |
## Architecture
```
src/
├── index.ts — MCP server, 13 tool registrations, CLI entry
├── renderer.ts — Capture engine + SSRF route guard (terminal, code, browser, PDF)
├── config.ts — Config loader, defaults, 27 themes
├── cli.ts — CLI commands (init, doctor, test)
├── security.ts — SSRF denylist (incl. DNS resolve), path traversal, input limits
├── logger.ts — Audit logging (AuditEvent, log file)
├── brand.ts — Centralized brand tokens (colors, ANSI, logo)
├── terminal.ts — Real terminal detection (Kitty/Gnome/Alacritty/WezTerm)
├── browser.ts — System Chrome profile detection (8-step fallback)
├── setup-shared.ts — Shared bootstrap for interactive setup
├── document.ts — Document render engine (brand-colored)
├── gif.ts — GIF animation (gifenc + fast-png, zero deps)
├── tools/ — One file per MCP tool (13 registrations)
└── highlighter.ts — Shiki wrapper
```
## Development

@@ -320,25 +243,9 @@

bun run build # tsc → dist/
bun test # 240+ tests
bun test # 317 tests
```
### Docs
Requirements: Node.js ≥ 20 or Bun ≥ 1.2. CI runs on ubuntu / macOS / windows via GitHub Actions.
Full reference documentation in **[docs/](docs/README.md)**: getting started, tools reference, configuration, CLI, and guides.
### Project Documentation
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** — Module map, data flow, key design decisions, security architecture, cross-platform support, and full MCP protocol reference. Required reading for anyone modifying the codebase.
- **[CONTRIBUTING.md](./CONTRIBUTING.md)** — Development workflow, coding principles, testing guidelines, and PR checklist.
### Requirements
- **Runtime**: Node.js ≥ 20 or Bun ≥ 1.2
- **TypeScript**: 5.x (ES2022, Node16 modules)
### CI
GitHub Actions runs on `ubuntu-latest`, `macos-latest`, `windows-latest` — bun only, no node matrix.
## License
MIT — see [LICENSE](./LICENSE).