mirror of
https://github.com/xlionjuan/wastebin-mcp-go.git
synced 2026-11-16 19:40:06 +00:00
No description
- Go 99.6%
- Just 0.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Co-authored-by: xlion-bot-renovate[bot] <218815870+xlion-bot-renovate[bot]@users.noreply.github.com> |
||
| .github | ||
| docs | ||
| internal/wastebin | ||
| .env.example | ||
| .gitignore | ||
| .golangci.yml | ||
| .goreleaser.yaml | ||
| AGENTS.md | ||
| cli.go | ||
| cli_test.go | ||
| codecov.yml | ||
| CONTEXT.md | ||
| e2e_helper_test.go | ||
| e2e_lifecycle_test.go | ||
| e2e_mcp_test.go | ||
| go.mod | ||
| go.sum | ||
| justfile | ||
| LICENSE | ||
| main.go | ||
| main_test.go | ||
| mcp.go | ||
| mcp_test.go | ||
| README.md | ||
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 (
createsubcommand) - 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 viafilepath.EvalSymlinksfor 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 unlessWASTEBIN_MCP_ALLOW_INSECURE_PASSWORD=trueis set. - See
CONTEXT.mdfor the full security model.
License
AGPL-3.0