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

119 lines
4.9 KiB
Markdown

# Wastebin MCP Server
A Model Context Protocol (MCP) server and CLI tool for creating pastes on a
[Wastebin](https://github.com/matze/wastebin) instance.
## Quick Start
```bash
# 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
```json
{
"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)
```json
{
"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
```json
{
"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