No description
  • Go 99.6%
  • Just 0.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
xlion-bot-renovate[bot] 9e93edc095
chore(deps): update github/codeql-action action to v4.39.3 (#278)
Co-authored-by: xlion-bot-renovate[bot] <218815870+xlion-bot-renovate[bot]@users.noreply.github.com>
2026-11-07 19:08:07 +00:00
.github chore(deps): update github/codeql-action action to v4.39.3 (#278) 2026-11-07 19:08:07 +00:00
docs fix: sandbox translation now MCP-only; CLI rejects sandbox envs (#244) 2026-08-04 03:03:46 +08:00
internal/wastebin fix: remove obsolete lint suppressions 2026-10-29 23:55:18 +08:00
.env.example docs: fix .env.example and INSTALL.md (#223) 2026-07-22 05:28:44 +08:00
.gitignore chore: Add coverage.* to .gitignore 2026-07-06 21:25:29 +08:00
.golangci.yml chore(deps): update dependency go to v1.27.1 (#251) 2026-09-06 23:13:47 +08:00
.goreleaser.yaml feat: add version metadata, goreleaser config, and release CI 2026-06-16 23:13:25 +08:00
AGENTS.md test: run goleak in wastebin package (#219) 2026-07-22 01:20:18 +08:00
cli.go fix: sandbox translation now MCP-only; CLI rejects sandbox envs (#244) 2026-08-04 03:03:46 +08:00
cli_test.go fix: sandbox translation now MCP-only; CLI rejects sandbox envs (#244) 2026-08-04 03:03:46 +08:00
codecov.yml Fixed 6 doc issues across 4 files 2026-06-18 14:13:46 +00:00
CONTEXT.md fix: sandbox translation now MCP-only; CLI rejects sandbox envs (#244) 2026-08-04 03:03:46 +08:00
e2e_helper_test.go fix(deps): update module github.com/modelcontextprotocol/go-sdk to v1.7.0 (#233) 2026-08-02 22:13:37 +08:00
e2e_lifecycle_test.go fix(deps): update module github.com/modelcontextprotocol/go-sdk to v1.7.0 (#233) 2026-08-02 22:13:37 +08:00
e2e_mcp_test.go Removed password query param guidance from code, schema, docs & tests. 2026-07-01 09:54:51 +00:00
go.mod Bump to v0.13.2 2026-10-30 00:00:11 +08:00
go.sum chore(deps): update module golang.org/x/vuln to v1.9.0 (#257) 2026-10-21 07:10:53 +08:00
justfile ci: centralize Go verification commands in just (#216) 2026-07-21 01:50:59 +08:00
LICENSE Initial commit: Wastebin MCP Server 2026-06-16 01:43:53 +08:00
main.go Bump to v0.13.2 2026-10-30 00:00:11 +08:00
main_test.go test: consolidate duplicated CLI behavior tests 2026-07-01 01:59:17 +08:00
mcp.go chore(deps): update dependency go to v1.27.1 (#251) 2026-09-06 23:13:47 +08:00
mcp_test.go fix(deps): update module github.com/modelcontextprotocol/go-sdk to v1.7.0 (#233) 2026-08-02 22:13:37 +08:00
README.md fix: sandbox translation now MCP-only; CLI rejects sandbox envs (#244) 2026-08-04 03:03:46 +08:00

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