wastebin-mcp-go/README.md
opencode-agent[bot] 4e0d7474f1
fix: sandbox translation now MCP-only; CLI rejects sandbox envs (#244)
* Sandbox translation now MCP-only; CLI rejects sandbox envs.

Co-authored-by: xlionjuan <[email protected]>

* docs: clarify CLI env var contract in INSTALL.md

CLI mode reads the same supported env vars as MCP mode, except the
sandbox path translation variables, which are rejected. Aligns the
CLI mode section with the sandbox translation note on the same page.

---------

Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>
Co-authored-by: xlionjuan <[email protected]>
2026-08-04 03:03:46 +08:00

4.9 KiB

Wastebin MCP Server

A Model Context Protocol (MCP) server and CLI tool for creating pastes on a Wastebin instance.

Quick Start

# Build
go build ./...

# MCP mode (stdio server for AI agents)
export WASTEBIN_SERVER_URL=https://bin-staging.xlion.tw
wastebin-mcp-go

# CLI mode
wastebin-mcp-go create --content "hello world" --extension md
wastebin-mcp-go create --file-path /tmp/doc.md

CLI mode does not support sandbox path translation — the sandbox translation environment variables are rejected with an error when set (see docs/INSTALL.md).

Arguments: --help and --version are available as top-level arguments. The create subcommand also accepts --help.

Exit codes: 0 = success, 1 = CLI error, 2 = MCP server error.

Features

  • Content mode: paste text directly
  • File mode (default: on): paste from file path
  • Path safety: allowlist + blocklist + symlink resolution
  • Sandbox translation (optional, ENV-gated, MCP mode only): translate container paths to host paths
  • Text validation: rejects binary and non-UTF-8 files
  • CLI mode: one-shot paste creation (create subcommand)
  • MCP mode: stdio server for AI agents

Configuration

Environment Variable Required Default Description
WASTEBIN_SERVER_URL ✅ — HTTP(S) Wastebin server URL, optionally with a base path (e.g. https://bin-staging.xlion.tw/wastebin). Credentials, query strings, and fragments are rejected
WASTEBIN_MCP_DEFAULT_EXPIRES 31536000 Default expiration in seconds
WASTEBIN_MCP_FILE_READ_ENABLED true Enable file reading mode
WASTEBIN_MCP_ALLOWED_PATHS — Comma-separated absolute directory paths
WASTEBIN_MCP_BLOCKED_PATHS — Comma-separated absolute directory paths (relative paths are rejected at startup). The built-in blocklist handles /etc,/proc,/sys,/dev separately
WASTEBIN_MCP_MAX_CONTENT_SIZE 1048576 Max content size in bytes
WASTEBIN_MCP_SANDBOX_MOUNTS — Docker mount mappings (host:sandbox,...); sandbox paths must be absolute and must not contain .. components. MCP mode only — rejected in CLI mode
WASTEBIN_MCP_SANDBOX_TRANSPARENT false Transparent sandbox translation. MCP mode only — rejected in CLI mode
WASTEBIN_MCP_ALLOW_INSECURE_PASSWORD false Allow password-protected pastes over non-loopback HTTP (not recommended)
WASTEBIN_MCP_DISABLE_BUILTIN_BLOCKLIST false Disable built-in blocklist (system + sensitive paths)
DEBUG — Set to 1 or true to enable debug logging

Response Format

The response contains a fixed set of fields (hostname, id, url, raw) plus conditional fields that appear only in specific scenarios.

Paste with .md extension

{
  "hostname": "https://bin-staging.xlion.tw",
  "id": "FTuutJssdSh",
  "url": "/FTuutJssdSh.md",
  "raw": "/raw/FTuutJssdSh.md",
  "markdown_rendered": "/md/FTuutJssdSh.md"
}

Paste with unknown extension (or no extension)

{
  "hostname": "https://bin-staging.xlion.tw",
  "id": "AbCdEfGh123",
  "url": "/AbCdEfGh123",
  "raw": "/raw/AbCdEfGh123",
  "hint": "Extension not detected; syntax highlighting may not apply"
}

Paste with password protection

{
  "hostname": "https://bin-staging.xlion.tw",
  "id": "XyZ789AbCdE",
  "url": "/XyZ789AbCdE.txt",
  "raw": "/raw/XyZ789AbCdE.txt",
  "password_hint": "This paste is password-protected. Retrieve raw content via the Wastebin-Password header:\n  curl -H 'Wastebin-Password: YOUR_PASSWORD' https://bin-staging.xlion.tw/raw/XyZ789AbCdE.txt\n(Replace YOUR_PASSWORD with the actual password.)"
}

Security

  • File reads are gated by an allowlist (ALLOWED_PATHS) and a blocklist (BLOCKED_PATHS, empty by default — the built-in blocklist handles /etc,/proc,/sys,/dev). Configured allowlist and blocklist entries must be absolute paths.
  • Sensitive path components (.ssh, .gnupg, .aws, .kube, .docker, .git) are checked on the raw input before symlink resolution, so a blocked-component symlink (e.g. .ssh → realssh) is caught before the symlink target obscures it. All paths are then resolved via filepath.EvalSymlinks for defense-in-depth blocklist matching.
  • Binary and non-UTF-8 files are rejected at read time.
  • Sandbox translation is opt-in and ENV-gated. Sandbox mount paths are validated at startup; .. components are rejected before path cleanup, and the absolute-path check runs after path cleanup.
  • Content size is pre-checked against a configurable limit.
  • Password-protected pastes over http:// are only allowed for loopback addresses (localhost, 127.0.0.1, ::1). Non-loopback HTTP is rejected unless WASTEBIN_MCP_ALLOW_INSECURE_PASSWORD=true is set.
  • See CONTEXT.md for the full security model.

License

AGPL-3.0