npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@mateusz-klatt/snapper-mcp

v0.16.0

Published

Lightweight stdio-to-HTTP MCP bridge from Claude Desktop / Claude Code to Snapper /api/mcp, with a `watch` subcommand that streams live signal + order events as JSONL via the /api/auth/ws_token endpoint.

Readme

@mateusz-klatt/snapper-mcp

npm version node license CI Quality Gate Status Bugs Vulnerabilities Code Smells Claude Code Plugin

Lightweight stdio-to-HTTP Model Context Protocol bridge. Spawns as a subprocess, speaks MCP over stdio to Claude Desktop / Claude Code, and proxies every request to a Snapper backend's /api/mcp endpoint with Bearer-token auth.

What is this

Snapper is a multi-tenant trading platform. Its backend exposes MCP at /api/mcp, guarded by Bearer-JWT auth, feature flag, and per-principal rate limiting. MCP hosts (Claude Desktop, Claude Code) speak MCP over stdio — they spawn a subprocess and exchange JSON-RPC frames over stdin/stdout. @mateusz-klatt/snapper-mcp is the stdio ⇄ HTTP bridge that makes that conversation work.

It is a thin TypeScript bridge using Node's built-in fetch, plus @modelcontextprotocol/sdk for MCP framing. No OAuth, no telemetry. Standalone hosts (Claude Desktop, systemd, plain CLI) can provide credentials through CLI flags, a hardened --config JSON file, or environment variables. Claude Code plugin installs write a 0600-mode env.json into the per-plugin ${CLAUDE_PLUGIN_DATA} directory at proxy startup so the skill-armed monitor process can read its credentials via --config=PATH; the file is owned by the plugin's data dir and is overwritten atomically on every proxy startup.

Install

Three install paths, in recommended order. All three end at the same runtime — pick whichever matches your MCP host.

Option 1 — Claude Code plugin (recommended)

In any Claude Code session:

/plugin marketplace add mateusz-klatt/snapper-mcp
/plugin install snapper-mcp@mateusz-klatt-snapper-mcp

Claude Code prompts for two values:

  • Snapper API URL — your backend's /api/mcp endpoint.
  • Access token — paste from Snapper's AI Integration page (the config-snippet generator). The same token authenticates both the proxy MCP server and the watch monitor.

Plugin changes installed mid-session need /reload-plugins (or a Claude Code restart) before the MCP server starts. After reloading, /mcp list should show the snapper server connected.

The plugin manifest threads both credentials (SNAPPER_BASE_URL, SNAPPER_ACCESS_TOKEN) into the proxy MCP subprocess as env vars via ${user_config.KEY} interpolation. The proxy then writes a 0600-mode env.json snapshot into ${CLAUDE_PLUGIN_DATA} at startup so the skill-armed watch monitor can read the same values via --config="${CLAUDE_PLUGIN_DATA}/env.json". The manifest marks the token as sensitive: true; the host controls storage of its user configuration. The bridge's own credential copy is the protected env.json described above.

Option 2 — Claude Desktop manual config

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "snapper": {
      "command": "npx",
      "args": ["-y", "@mateusz-klatt/snapper-mcp"],
      "env": {
        "SNAPPER_BASE_URL": "https://your-snapper-instance.example.com/api/mcp",
        "SNAPPER_ACCESS_TOKEN": "<generated via Snapper UI: AI Integration>"
      }
    }
  }
}

Restart Claude Desktop; the Snapper server shows up in the MCP Servers settings panel.

Option 2b — Multi-CLI installer (snapper-mcp integrate)

Configure MCP tool access and interactive-only session wake across any of the supported coding CLIs (claude, codex, copilot, antigravity, kimi, grok, cursor, or all):

npm install -g @mateusz-klatt/snapper-mcp

SNAPPER_BASE_URL="https://snapper.example.com/api/mcp" \
SNAPPER_ACCESS_TOKEN="<delegate-jwt>" \
  snapper-mcp integrate all

# Headless / container MCP wiring without interactive wake hooks:
snapper-mcp integrate all --no-wake --config /path/to/config.json

# Inspect configured CLIs and credential validity offline:
snapper-mcp doctor

# Cleanly remove Snapper entries and restore prior user config files:
snapper-mcp integrate --remove all

Credentials are stored in a mode-0600 JSON file inside the user's private snapper-mcp state directory (or read from --config PATH) and are never embedded into CLI hook commands or process arguments. On Windows, POSIX mode bits do not enforce NTFS ACLs; keep the credential file under the default %APPDATA%\snapper-mcp\config.json path inside the user profile or verify NTFS read permissions are restricted to the current user when passing a custom --config PATH.

For claude, snapper-mcp integrate claude writes a local plugin bundle under the snapper-mcp state directory and registers snapper@snapper-local in Claude Code's user configuration (~/.claude/settings.json and ~/.claude/plugins/). All client-facing snapper-mcp watch --client <cli> modes default to --actionable-only and emit fixed, content-free attention notices rather than raw backend frame payloads unless --all-frames is explicitly passed. Interactive wake hooks verify terminal attachment and client argument grammar before arming so non-interactive print runs (-p, --print, codex exec) never emit extra lines or continuation turns.

Option 3 — Direct CLI / custom hosts

SNAPPER_BASE_URL="..." SNAPPER_ACCESS_TOKEN="..." \
  npx -y @mateusz-klatt/snapper-mcp

npm install -g @mateusz-klatt/snapper-mcp
SNAPPER_BASE_URL="..." SNAPPER_ACCESS_TOKEN="..." snapper-mcp

Requires Node 26+ (uses Node's built-in fetch, AbortController, and ESM top-level await). CI validates the declared minimum (Node 26) across Ubuntu / macOS / Windows.

Configuration

Two environment variables are the common MCP-host configuration shape:

| Variable | Required? | Purpose | | --- | --- | --- | | SNAPPER_BASE_URL | yes | URL of Snapper's /api/mcp endpoint. | | SNAPPER_ACCESS_TOKEN | yes | Long-lived AI delegate JWT for Bearer auth (generated in Snapper UI). The same token authenticates both the proxy MCP server and the watch monitor. |

See .env.example for placeholder values.

Direct CLI runs also accept --base-url, --access-token, and --config=PATH. Resolution order is CLI flags, then a JSON config file, then environment variables. Config files can contain the same top-level SNAPPER_BASE_URL / SNAPPER_ACCESS_TOKEN keys shown above; on POSIX systems the bridge refuses world-writable files and warns when the file is group- or world-readable.

Multi-profile support

Run multiple Snapper instances (prod + staging, prod + local dev) from one bridge install. Select a profile at spawn time:

SNAPPER_PROFILE=prod snapper-mcp
# or
snapper-mcp --profile=prod

When a profile is selected, the bridge reads SNAPPER_PROFILE_<UPPER>_BASE_URL and SNAPPER_PROFILE_<UPPER>_ACCESS_TOKEN instead of the bare top-level vars (hard isolation — no accidental cross-profile fallback). Profile names match ^[a-z0-9]{1,32}$. CLI flag wins over env var. CLI --base-url / --access-token flags still override the selected profile; otherwise config/env lookup is profile-scoped.

The --config JSON file may carry a profiles block:

{
  "profiles": {
    "prod":    { "SNAPPER_BASE_URL": "https://snapper.example.com/api/mcp", "SNAPPER_ACCESS_TOKEN": "..." },
    "staging": { "SNAPPER_BASE_URL": "https://staging.example.com/api/mcp", "SNAPPER_ACCESS_TOKEN": "..." }
  }
}

Verify a profile offline before spawning the bridge:

snapper-mcp check --profile=prod

Generating tokens

Snapper's AI Integration screen creates delegates and generates their configuration snippets. Each delegate emits a single long-lived (~3-month / 90-day) access JWT. Paste the value into SNAPPER_ACCESS_TOKEN; the same token powers both the proxy MCP server and the optional push-wakeup monitor.

Each delegate has configurable caps: per-instrument quantity, max open orders, rolling 24h USD notional, and 60-second cancel rate. Tokens are bound to the delegate's permissions + wallet scope; revoke the delegate in-place via POST /api/ai-delegates/{id}/deactivate to revoke the backend token inventory and evict verify caches via admin.user_deactivated.

Logging

All bridge logs go to stderr exclusively. Stdout is reserved for MCP JSON-RPC frames — any stray write there corrupts the protocol stream and Claude Desktop disconnects.

Verbosity knob: set SNAPPER_MCP_LOG_LEVEL=debug for transport-level diagnostics (URL, HTTP status, error_code). Valid levels: debug / info (default) / warn / error. Timestamps in the log prefix: SNAPPER_MCP_LOG_TIMESTAMPS=1.

For structured-log pipelines, set SNAPPER_MCP_LOG_FORMAT=json to switch every stderr line to a single-line JSON object:

{"t":"2026-05-02T16:00:00.000Z","lvl":"info","prefix":"bridge","msg":"connected","rest":[{"req":42}]}

The t field is always present in JSON mode regardless of SNAPPER_MCP_LOG_TIMESTAMPS. Pipe through jq for filtering:

SNAPPER_MCP_LOG_FORMAT=json snapper-mcp 2>bridge.log
# In a separate terminal, inspect stderr without mixing in MCP stdout:
jq 'select(.lvl=="error")' bridge.log

Error instances in the rest arguments serialise as {name, message, stack}; circular objects fall back to String(value) rather than throwing.

Authentication

On every outbound HTTP request, the bridge injects Authorization: Bearer ${SNAPPER_ACCESS_TOKEN} while preserving any Accept / Content-Type / other headers the SDK set.

On 401 the bridge writes a single-line stderr message — once per session — and propagates the 401 response to the MCP host. The host surfaces the auth error as a protocol error; the operator recreates the AI delegate in Snapper to recover.

Watch subcommand

snapper-mcp watch opens a long-lived WebSocket session against Snapper's /api/ws endpoint and writes one JSONL frame per line to stdout. A Claude Code plugin monitor (or any host that can read a subprocess's stdout) consumes the JSONL stream as push-style wakeup.

snapper-mcp watch --topic signals. --topic orders.events.

Default subscription: signals., orders.events., ai_reviews., and ai_research. if no --topic is given. Each prefix MUST end with . to address a topic family root. The ai_reviews. family carries review-request and decision-ack frames, while ai_research. carries committed research-round wakes. A monitoring host can therefore wake its consumer when either kind of work needs attention.

The watch session mints a one-shot WebSocket token via POST /api/auth/ws_token using the same SNAPPER_ACCESS_TOKEN configured for the proxy.

Check subcommand

snapper-mcp check runs an offline diagnostic on the configured access token + base URL — no network. Useful for validating the contents of SNAPPER_ACCESS_TOKEN (sub, role, expiry, and any scope/scopes claim present) without burning the token on a failed bridge-up. This is an offline decode only; server-side signature, inventory revocation, wallet scope, and permission checks still happen on the Snapper backend.

snapper-mcp check
# base URL: https://snapper.example.com/api/mcp/
# access token:
#   alg: HS256
#   sub: ai-claudedesktop-a1b2c3
#   role: ai_delegate
#   exp: 2026-08-01T00:00:00.000Z (in 90.5d)
#   status: valid

Exit codes:

  • 0 — token decoded, base URL parsed, expiry OK.
  • 1 — env validation failed (missing or malformed inputs).
  • 2 — token decoded but is already expired or has no exp claim.

The same --config=PATH, --access-token, and --base-url flags the proxy + watch subcommands accept also work for check.

Arming the monitor: the wake skill

Installing the plugin starts no background process. Run /wake in the session that should answer review requests: the manifest declares the monitor with when: "on-skill-invoke:snapper-mcp:wake", so the host arms it in response to that invocation. A session that never runs /wake never connects, so several open sessions do not compete for the same request or burn tokens waiting. The monitor is not restored when a session resumes — run /wake again to re-arm it.

Note the qualified skill name in that trigger. The host matches when against on-skill-invoke:<plugin name>:<skill>; a bare on-skill-invoke:wake never matches and the monitor silently never arms. The skill verifies the monitor started and arms it itself if the host did not, so the plugin still works where the trigger is unsupported.

Credentials come from the --config=PATH JSON file the proxy MCP server seeds into ${CLAUDE_PLUGIN_DATA}/env.json at startup, so both processes share one SNAPPER_ACCESS_TOKEN. Because the host expands ${CLAUDE_PLUGIN_DATA} itself, the monitor always reads this plugin's own data directory.

Development

See CONTRIBUTING.md for the dev workflow (npm install, npm test, npm run build).

License

Apache License, Version 2.0. See NOTICE for attribution. Third-party dependencies retain their own licenses.

Revisions through the last-mit tag, including previously published npm versions, were released under MIT. Subsequent original work is licensed under Apache-2.0; earlier MIT grants remain valid.