wastebin-mcp-go/CONTEXT.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

18 KiB

Wastebin MCP Server (wastebin-mcp-go)

A Model Context Protocol (MCP) server and CLI tool that creates pastes on a Wastebin pastebin instance via its REST API.

Language

Core Types

WastebinClient: The HTTP client that holds the server base URL and an *http.Client and communicates with a Wastebin instance to create pastes. The underlying HTTP transport uses hardcoded defaults that are not currently configurable via environment variables:

Setting Value
Request timeout 30s
TCP dial timeout 10s
TLS handshake timeout 10s
Response header timeout 30s
Idle connection timeout 90s
Max idle connections 100
Max idle connections per host 10
Max redirects 10

Config: The configuration parameters — server URL, default expiration, file read mode settings, sandbox mount mappings, and translation mode.

CreatePasteArgs: All input parameters for creating a paste in MCP mode — content or file_path, extension, expires, title, burn_after_reading, password, and optional sandbox path translation flag.

PasteResponse: The structured result returned after creating a paste — hostname, paste id, and URL variants (raw, rendered).

Blocklist: A default set of sensitive system directories (/etc, /proc, /sys, /dev) and sensitive path components (.ssh, .gnupg, .aws, .kube, .docker, .git) that are denied. The allowlist bypasses system directory prefixes (so ALLOWED_PATHS=/etc/nginx works) but the sensitive component blocklist is enforced regardless of ALLOWED_PATHS — a path under an allowed directory that contains .ssh or .git is still denied.

Wastebin API

The upstream Wastebin server (github.com/matze/wastebin) provides:

  • POST / with JSON body {"text": "...", "extension?": "...", "expires?": N, "burn_after_reading?": bool, "password?": "...", "title?": "..."} → returns {"path": "/FTuutJssdSh"}
  • GET /raw/:id — raw content
  • GET /md/:id — rendered Markdown (only for .md/.markdown pastes)
  • GET /dl/:id — download with Content-Disposition

Default max body size: 1 MB (WASTEBIN_MAX_BODY_SIZE). Default paste expirations: 0=d,10m,1h,1d,1w,1M,1y (WASTEBIN_PASTE_EXPIRATIONS).

Wastebin ID format

IDs are base64-like encoded integers (a-zA-Z0-9-+). They can be 6 characters (Id32) or 11 characters (Id64). The ID is randomly generated server-side. The response path includes the extension if one was provided.

POST / → {"path": "/FTuutJssdSh.md"}

create_paste Tool

Single tool with two usage modes — content passthrough or file path.

Parameters:

Parameter Type Required Description
content string no* Paste content directly
file_path string no* Local file path to read content from
extension string no Syntax highlighting extension (e.g. md, go, py)
expires string no Expiration: bare number = seconds, unit suffix (s/m/h/d/w/M/y)
title string no Optional paste title
burn_after_reading boolean no Delete after first read
password string no Encrypt with password
translate_sandbox_path boolean no Translate sandbox path (MCP mode only; only when mounts configured)

* At least one of content or file_path is required. If both are provided, the server returns a clear error: "provide either 'content' or 'file_path', not both; pick exactly one input mode".

Schema is built dynamically at startup based on env config:

  • If file read mode is OFF: content becomes required; file_path and translate_sandbox_path are excluded from the schema.
  • If sandbox mounts are not configured: translate_sandbox_path is excluded.
  • If transparent mode is ON: translate_sandbox_path is excluded (translation happens automatically).

Expiration Format

Accepts two formats:

  • Bare number (e.g. 3600) → treated as seconds
  • Number with unit suffix → translated to seconds

Supported units: s (seconds), m (minutes), h (hours), d (days), w (weeks), M (months ≈ 30d), y (years ≈ 365d).

Examples: 3600, 1h, 7d, 30d, 1y.

Output Format

{
  "hostname": "https://bin-staging.xlion.tw",
  "id": "FTuutJssdSh",
  "url": "/FTuutJssdSh.md",
  "raw": "/raw/FTuutJssdSh.md",
  "markdown_rendered": "/md/FTuutJssdSh.md",
  "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/FTuutJssdSh.md\n(Replace YOUR_PASSWORD with the actual password.)"
}
Scenario extension markdown_rendered hint password_hint
Content mode + ext=.md from caller ✅ ❌ when password set
Content mode + ext≠.md from caller ❌ ❌ when password set
Content mode + no ext unset ❌ ✅ when password set
File mode + .md extension from path ✅ ❌ when password set
File mode + non-.md ext from path ❌ ❌ when password set
File mode + no extension unset ❌ ✅ when password set
  • id is included for agents to construct custom URLs (e.g. curl).
  • markdown_rendered only appears when extension is .md or .markdown.
  • hint only appears when extension is unknown (fuzzy case).
  • password_hint only appears when the paste is password-protected.
  • URLs are relative (hostname is separate). The tool description instructs agents to reconstruct full URLs as {hostname}{url}.

Extension Detection (File Mode)

Uses Go's filepath.Ext() which returns the trailing extension only:

  • script.py → .py, archive.tar.gz → .gz, Dockerfile → ""
  • For extensionless filenames (Dockerfile, Makefile), the extension parameter can be used explicitly.

Password-protected pastes: If you create a paste with a password, retrieval requires providing the password via the Wastebin-Password header. Since there is no get_paste tool, agents must use curl -H "Wastebin-Password: ..." {hostname}/raw/{id} to retrieve it. This is a known limitation by design.

Security: The password query parameter is deprecated and should not be used. URL query parameters are commonly logged by proxies, load balancers, and web servers, which can leak secrets.

Operation Modes

MCP Mode: The program starts a stdio JSON-RPC server implementing the Model Context Protocol, listening for incoming create_paste tool-call requests and returning structured JSON responses. Activated when no CLI subcommand is given.

CLI Mode: Activated by the create subcommand. Accepts paste parameters as flags, executes a one-shot paste creation, and prints the result to stdout, then exits. Output format: JSON (same as MCP mode response). CLI mode does not support sandbox path translation — it rejects the sandbox translation environment variables (WASTEBIN_MCP_SANDBOX_MOUNTS, WASTEBIN_MCP_SANDBOX_TRANSPARENT) with a configuration error, since sandbox translation is an MCP-mode-only feature.

Debug Mode: Activated by DEBUG=1 env var in MCP mode, or --debug flag on the create subcommand — enables sparse slog.Debug logging to stderr for selected operations (paste submission details, sandbox path translation, error responses, response-body close failures). This is not an HTTP wire dump; individual request and response bodies are not logged.

Error Handling

When a paste creation fails, the error message is constructed as follows:

Unified wording: Every paste-creation (handler) error message follows the "<problem>; <next-step guidance>" convention, with dynamic values appended as : <value>. Errors that carry structured, programmatically-relevant data are typed errors whose Error() method produces the static wording centrally (see docs/adr/005-error-model.md and internal/wastebin/errors.go); purely diagnostic values are appended with : <value> suffixes at the wrapping site. Pure condition checks remain sentinel errors.

Known errors translated to clear messages:

Error Condition Message
HTTP 403 "server rejected the request; content may contain disallowed data; ask the user to check the content or the server logs"
HTTP 413 "content exceeds the server's maximum allowed size; split the content into smaller parts and upload each separately"
Connection refused / dial timeout "cannot connect to Wastebin server; verify the server is running: "
DNS resolution failure "cannot resolve the server hostname; verify WASTEBIN_SERVER_URL points to a resolvable host: "
Sandbox translation requested, no mounts "sandbox path translation was requested but no sandbox mounts are configured; ask the user to check WASTEBIN_MCP_SANDBOX_MOUNTS if translation should be enabled"
Sandbox path matches no mount "sandbox path does not match any configured mount; ask the user to check the sandbox mount configuration: "

Unknown/ambiguous errors: Returned with the HTTP status code:

"unknown HTTP error; ask the user to check the server status or the request: HTTP <CODE>"

Format: Errors are always reported via IsError: true in the MCP tool result with a plain text description. The complete error tables live in docs/MCP_TOOLS.md.

File Read Mode

File read mode allows the create_paste tool to read file contents from the local filesystem. It is enabled by default (WASTEBIN_MCP_FILE_READ_ENABLED).

⚠️ Security warning for sandbox users: When file read mode is enabled without any path restrictions (no ALLOWED_PATHS, no blocklist), an agent running inside a container/sandbox can read any file accessible from its perspective. This is effectively sandbox escape. Always configure ALLOWED_PATHS and review the BLOCKED_PATHS defaults.

Path Allowlist (WASTEBIN_MCP_ALLOWED_PATHS): A comma-separated list of absolute directory paths. Any file read is validated against this list — the resolved path must be within one of the allowed directories. Has no default; if file read mode is enabled and ALLOWED_PATHS is empty, the server skips the allowlist check and falls through to the blocklist pipeline instead. Relative entries are rejected at startup.

Built-in Blocklist: Two independent sub-checks:

  • System directory prefixes (/etc, /proc, /sys, /dev): Bypassed by ALLOWED_PATHS. This allows e.g. ALLOWED_PATHS=/etc/nginx to work despite /etc being in the prefix blocklist.
  • Sensitive path components (.ssh, .gnupg, .aws, .kube, .docker, .git): Not bypassed by ALLOWED_PATHS. Even if a file is under an explicitly allowed directory, it is denied if any path component matches a sensitive pattern.

User Blocklist (WASTEBIN_MCP_BLOCKED_PATHS): A comma-separated list of absolute directory paths to block. Empty by default — the built-in blocklist handles system directories (/etc, /proc, /sys, /dev) separately. Each entry stores both the lexical form (as configured, filepath.Clean) and the resolved form (after filepath.EvalSymlinks; falls back to filepath.Clean for non-existent paths). The lexical form enables a pre-resolution check (Stage 4a) that catches late-created or retargeted symlinks, including relative file_path values in CLI mode. The resolved form (Stage 4b) matches what EvalSymlinks produces at request time. Relative entries are rejected at startup. The allowlist takes precedence over the user blocklist.

Path resolution: Sensitive path components (.ssh, .gnupg, .aws, .kube, .docker, .git) are checked on the raw input before symlink resolution, catching symlinked blocked components (e.g. .ssh → realssh) before EvalSymlinks resolves the symlink and the component name disappears. After this pre-resolution check, the path is then resolved via filepath.EvalSymlinks and filepath.Clean. This multi-layer approach prevents symlink-based bypass of the component blocklist. After validation passes, the file is opened using openat(2) with O_NOFOLLOW, walking every path component from a trusted root fd (/). This three-layer approach prevents TOCTOU symlink-swap attacks where a validated path is replaced with a symlink between validation and the actual file open.

Validation flow:

User-supplied file_path
  → Sandbox path traversal detection (before sandbox translation)
  → Sandbox component blocklist check (before sandbox translation)
  → Sandbox translation (if enabled)
  → Mount host root verification (after translation)
  → Stage 1a — Path traversal detection (raw input)
  → Stage 1b — Sensitive component detection (raw input, before symlink resolution)
  → Stage 4a — User blocklist lexical (pre-resolution, before EvalSymlinks)
  → Resolve (EvalSymlinks + Clean + Abs)
     → Stage 2 — ALLOWED_PATHS check
      ├─ ALLOWED_PATHS configured
      │  ├─ Path under allowed path → Stage 3b (sensitive component check)
      │  │                          ├─ Blocked component found → ❌  denied
      │  │                          └─ No blocked component → ✅  IsLikelyText
      │  └─ Path not under any allowed path → ❌  denied (not authorized)
      └─ ALLOWED_PATHS not configured
         → Stage 3a — Built-in prefix blocklist
         │  ├─ Blocked → ❌  denied
         │  └─ OK → Stage 3b — Built-in component blocklist
         │          ├─ Blocked → ❌  denied
         │          └─ OK → Stage 4b — User blocklist resolved (post-resolution)
         │                  ├─ Blocked → ❌  denied
         │                  └─ OK → ✅  IsLikelyText

File validation (text detection: IsLikelyText):

Reads the first 8 KB of the file and applies a content-based heuristic:

  1. Magic-byte signature detection (hasBinarySignature) — rejects files starting with known binary format signatures: PDF (%PDF), PNG (\x89PNG), ZIP (PK\x03\x04 / PK\x05\x06 / PK\x07\x08), GZip (\x1f\x8b), and ELF (\x7fELF). This runs first, before UTF-8 validation, to catch binary formats that happen to pass the other checks.
  2. Must be valid UTF-8 (utf8.Valid).
  3. No null bytes (b == 0).
  4. Control character ratio (characters 0x00-0x1F excluding \n, \r, \t) must be below 5%.

This rejects binary files and non-UTF-8 encodings (Big5, Shift-JIS, Latin-1), but accepts any text-like file regardless of file extension — Makefile, Dockerfile, .gitignore, scripts without extension, etc.

Known limitation: Non-UTF-8 text files (Big5, Shift-JIS, Latin-1) are rejected. Workaround: convert to UTF-8 before uploading.

Content size pre-check: A configurable maximum content size (WASTEBIN_MCP_MAX_CONTENT_SIZE, default 1 MB) is checked before sending the HTTP request to Wastebin. This saves wasted uploads for oversized files.

Design rationale: The Wastebin server itself enforces WASTEBIN_MAX_BODY_SIZE (default 1 MB) and uses zstd compression. The client-side checks are a safety net to prevent accidental binary uploads and to fail fast on oversized content.

Sandbox Path Translation

A gated feature (WASTEBIN_MCP_SANDBOX_MOUNTS) for translating container/sandbox-internal paths to host paths before file reading.

MCP mode only: Sandbox path translation is only available in MCP mode. The CLI (wastebin-mcp-go create) does not support it and rejects the sandbox translation environment variables with a configuration error, so transparent mode never applies translation in CLI mode.

Mount Mapping Format: Docker mount style host_path:sandbox_path pairs, comma-separated. Example: /home/user/.hermes/profiles/neko/sandboxes/default/workspace:/workspace

Sandbox mount paths must be unique and non-overlapping — one mount's sandbox path cannot be a prefix of another's. Overlapping or duplicate paths are rejected at startup with a clear error.

Translation Modes:

  • opt-in (default): Tool schema includes a translate_sandbox_path boolean parameter. The caller must explicitly set it to true.
  • transparent (WASTEBIN_MCP_SANDBOX_TRANSPARENT=true): Translation is automatic. The translate_sandbox_path parameter is removed from the schema, and the server always attempts sandbox-to-host translation when mounts are configured.

Behavior when a transparent-mode path matches no mount: If the path does not match any configured mount, the request is rejected with an error.

In both modes, the translated path must still pass the allowlist + blocklist checks.

Startup validation: If WASTEBIN_MCP_SANDBOX_MOUNTS is configured, the server validates at startup that each mount's host_path is covered by at least one entry in WASTEBIN_MCP_ALLOWED_PATHS. When ALLOWED_PATHS is empty (or not set), mounts self-authorize — no startup validation check is performed. When ALLOWED_PATHS is set and a mount's host path is not covered, the server logs a warning and skips that mount; startup continues normally.

Security: Path traversal (..) is detected on the original sandbox path before any translation occurs. After translation, the result is verified to still be under the matched mount's host root. This prevents an attacker from using filepath.Join normalization to bypass the traversal check.

Gating Summary

Feature ENV Default
File read mode WASTEBIN_MCP_FILE_READ_ENABLED true
Path allowlist WASTEBIN_MCP_ALLOWED_PATHS — (optional — when empty, falls through to blocklist pipeline)
Path blocklist WASTEBIN_MCP_BLOCKED_PATHS — (empty; built-in blocklist handles /etc,/proc,/sys,/dev)
Max content size WASTEBIN_MCP_MAX_CONTENT_SIZE 1 MB
Sandbox mounts WASTEBIN_MCP_SANDBOX_MOUNTS — (MCP mode only — rejected in CLI mode)
Transparent mode WASTEBIN_MCP_SANDBOX_TRANSPARENT false (MCP mode only — rejected in CLI mode)
Disable built-in blocklist WASTEBIN_MCP_DISABLE_BUILTIN_BLOCKLIST false
Server URL WASTEBIN_SERVER_URL — (required)
Default expires WASTEBIN_MCP_DEFAULT_EXPIRES 31536000
Insecure password (HTTP) WASTEBIN_MCP_ALLOW_INSECURE_PASSWORD false
Debug logging DEBUG —