mirror of
https://github.com/xlionjuan/wastebin-mcp-go.git
synced 2026-11-17 04:17:54 +00:00
* fix(deps): update module github.com/modelcontextprotocol/go-sdk to v1.7.0 * Accept server/discover in stdin gate. Co-authored-by: xlionjuan <[email protected]> * Stateless requests pass; dead ErrBufferFull branch fixed and covered. Co-authored-by: xlionjuan <[email protected]> * All four issues fixed; verification green. Co-authored-by: xlionjuan <[email protected]> * Validate transport bound; bounded incremental first-line read; docs and PR body fixes --------- Co-authored-by: xlion-bot-renovate[bot] <218815870+xlion-bot-renovate[bot]@users.noreply.github.com> Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com> Co-authored-by: xlionjuan <[email protected]>
156 lines
6.9 KiB
Markdown
156 lines
6.9 KiB
Markdown
# ADR-001: Use Go SDK for MCP and Follow searxng-mcp-go Patterns
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
The wastebin-mcp-go project is an MCP server that exposes paste-creation
|
|
functionality via the Model Context Protocol. Several architectural decisions
|
|
needed to be made at the outset:
|
|
|
|
1. Which MCP SDK to use for implementing the server
|
|
2. What project structure and patterns to follow
|
|
3. Whether to include a paste retrieval tool
|
|
4. Whether file-mode reading should be opt-in or enabled by default
|
|
|
|
The existing [searxng-mcp-go](https://github.com/xlionjuan/searxng-mcp-go)
|
|
project (also by the same author) provides an established template for MCP
|
|
servers in Go, with proven patterns for SDK usage, CLI structure, and
|
|
documentation.
|
|
|
|
## Decisions
|
|
|
|
### 1. Use `github.com/modelcontextprotocol/go-sdk`
|
|
|
|
**Decision:** Use the official Go SDK for the Model Context Protocol
|
|
(`github.com/modelcontextprotocol/go-sdk`) to implement the MCP server.
|
|
|
|
**Reasoning:**
|
|
|
|
- Official SDK maintained by the MCP specification authors — follows spec
|
|
correctly and stays up to date with protocol changes.
|
|
- Same SDK used by searxng-mcp-go, providing a known, working codebase to
|
|
reference.
|
|
- Provides `mcp.NewServer`, `mcp.AddTool`, and `mcp.CallToolResult` types that
|
|
handle JSON-RPC framing and transport details.
|
|
- The SDK supports both tool registration (for MCP mode) and direct invocation
|
|
patterns (for CLI mode) — both are needed by this project.
|
|
- Avoids maintaining a custom JSON-RPC implementation.
|
|
|
|
**Alternatives considered:**
|
|
- **Custom JSON-RPC implementation** — rejected; would require implementing
|
|
protocol negotiation, error handling, and transport management from scratch.
|
|
- **`go-mcp` community SDK** — rejected; the official SDK has broader adoption
|
|
and is guaranteed to follow the spec.
|
|
|
|
### 2. Follow searxng-mcp-go Project Patterns
|
|
|
|
**Decision:** Structure wastebin-mcp-go following the same patterns as
|
|
searxng-mcp-go.
|
|
|
|
**Reasoning:**
|
|
|
|
- Same author and same deployment context (MCP server for a self-hosted service
|
|
behind an OpenCode agent runtime).
|
|
- Proven project structure:
|
|
- Root `main.go` for entry point and CLI dispatch
|
|
- `cli.go` for CLI subcommand implementation (create subcommand)
|
|
- `mcp.go` for MCP server initialization and handler registration
|
|
- `internal/{service}/` for core business logic, types, and HTTP client
|
|
- Root `*_test.go` for integration-style tests
|
|
- `docs/` for user-facing documentation
|
|
- `docs/adr/` for architecture decision records
|
|
- Same CI patterns (Go build, test, golangci-lint, goreleaser).
|
|
- Same SDK import style and MCP server setup pattern.
|
|
|
|
**Specific patterns adopted:**
|
|
- Config loaded from environment variables in `internal/wastebin/config.go`
|
|
via `ConfigFromEnv()`.
|
|
- CLI flags parsed with Go's `flag` package in root-level files.
|
|
- MCP server initialized with `mcp.NewServer`, tools added via `mcp.AddTool`,
|
|
then `server.Run(ctx, &mcp.IOTransport{...})`.
|
|
- Error messages returned as `IsError: true` MCP tool results with plain text
|
|
descriptions.
|
|
- Stdin validation (checking the first line is a valid MCP session starter —
|
|
`initialize`, `server/discover`, or any request carrying the stateless
|
|
protocol metadata in `params._meta` for protocol version `2026-07-28`) to
|
|
prevent hanging when piped non-MCP input. The first-line transport bound is
|
|
derived from the configured `WASTEBIN_MCP_MAX_CONTENT_SIZE` (capped at
|
|
256 MiB) plus a 64 KiB JSON envelope/escaping allowance, so a first-request
|
|
`tools/call` carrying content up to the configured limit passes the gate
|
|
under typical JSON escaping; heavy escaping (quotes, control characters,
|
|
HTML metacharacters) expands the wire representation and lowers the
|
|
effective first-call content ceiling.
|
|
|
|
### 3. Do NOT Add a `get_paste` Tool
|
|
|
|
**Decision:** Do not implement a `get_paste` MCP tool for retrieving existing
|
|
pastes.
|
|
|
|
**Reasoning:**
|
|
|
|
- Paste retrieval is trivially done with `curl {hostname}/raw/{id}` — no
|
|
special tool is needed.
|
|
- The Wastebin server supports raw content retrieval via simple HTTP GET,
|
|
which is well-suited to `curl`.
|
|
- Adding a `get_paste` tool would require an HTTP client that supports password
|
|
headers (`Wastebin-Password`), increasing the scope and surface area of the project.
|
|
- Keeping the tool set focused on a single creation tool reduces complexity,
|
|
testing burden, and documentation surface.
|
|
- Agents already have `curl` or HTTP client capabilities — telling them to
|
|
use `{hostname}{raw}` gives them everything they need.
|
|
|
|
**Limitation acknowledged:**
|
|
- Password-protected paste retrieval requires `curl -H "Wastebin-Password: ..."`,
|
|
which is a manual step for agents but well within standard tooling.
|
|
- The tool description explicitly instructs agents on how to handle this.
|
|
|
|
### 4. File Mode On by Default with Security Guards
|
|
|
|
**Decision:** Enable file-reading mode by default
|
|
(`WASTEBIN_MCP_FILE_READ_ENABLED=true`), but with strict security guards.
|
|
|
|
**Reasoning:**
|
|
|
|
- **On by default makes the tool immediately useful** — the most common use case
|
|
for wastebin-mcp-go is uploading file contents from a workspace. Requiring
|
|
explicit opt-in for every deployment adds friction.
|
|
- **Security guards prevent abuse in default configuration:**
|
|
- Path allowlist (`WASTEBIN_MCP_ALLOWED_PATHS`): When configured, only paths
|
|
under allowed directories are accepted. When empty, the server falls through
|
|
to the blocklist pipeline (built-in + user blocklists).
|
|
- Path blocklist (`WASTEBIN_MCP_BLOCKED_PATHS`, empty by default; the
|
|
built-in blocklist handles `/etc,/proc,/sys,/dev`): Sensitive system
|
|
directories are blocked.
|
|
- Symlink resolution (`filepath.EvalSymlinks`): Prevents symlink-based
|
|
allowlist bypass.
|
|
- Binary detection: First 8 KB are checked for UTF-8 validity and control
|
|
character ratio before upload.
|
|
- Content size limit: Configurable maximum size prevents oversized uploads.
|
|
- **Explicit security warning in documentation** for sandbox/container
|
|
deployments where unrestricted file read could enable sandbox escape.
|
|
|
|
**Alternative considered:**
|
|
- **File mode off by default** — rejected; would require every user to discover
|
|
and enable the feature, reducing usability for the primary use case.
|
|
- **File mode opt-in with a startup flag** — rejected; environment variable
|
|
already provides the toggle mechanism without adding CLI complexity.
|
|
|
|
## Consequences
|
|
|
|
- The project has a single `create_paste` tool with dynamic schema based on
|
|
configuration (file mode, sandbox mounts, transparent mode).
|
|
- Agents must use `curl` for paste retrieval, but the response always includes
|
|
the `raw` URL and `hostname` for easy reconstruction.
|
|
- Security documentation must clearly warn about the implications of file mode
|
|
in sandbox/container environments.
|
|
- The project structure is immediately familiar to anyone who has worked with
|
|
searxng-mcp-go.
|
|
- Upgrading the MCP SDK follows the same dependency update pattern as
|
|
searxng-mcp-go.
|
|
|
|
## Effective Date
|
|
|
|
2026-06-09
|