wastebin-mcp-go/AGENTS.md

7.3 KiB

Wastebin MCP Server

A Model Context Protocol (MCP) server providing paste creation via a Wastebin instance. Agents call this server to upload content (text, code, documents) to a configured Wastebin pastebin.

Orientation

  • Entry points: main.go, cli.go, mcp.go
  • Core package: internal/wastebin/
  • Unit tests: root *_test.go and internal/wastebin/*_test.go
  • CI and release workflows: .github/workflows/
  • Domain context and terminology: CONTEXT.md

Documentation Index

Topic Document
Build, install, configuration docs/INSTALL.md
MCP tool parameters docs/MCP_TOOLS.md
Issue tracker workflow docs/agents/issue-tracker.md
Triage labels docs/agents/triage-labels.md
Domain and ADR workflow docs/agents/domain.md
Architecture decisions docs/adr/

Agent skills

Issue tracker

Issues are tracked as GitHub issues. See docs/agents/issue-tracker.md.

Triage labels

Labels are managed via gh label list. See docs/agents/triage-labels.md.

Domain docs

Single-context. See docs/agents/domain.md.

Project Rules

Build and Test

# Verify and download dependencies
just deps

# Check module files are tidy
just mod-tidy

# Build the canonical wastebin-mcp-go binary
just build

# CI-style test run with race detector and coverage
just test-cover

# Known vulnerability scan
just vulncheck

# Lint
just lint

# Check formatting (gofumpt / goimports / gci)
just fmt-check

# Static analysis fallback (when golangci-lint is unavailable)
just vet

# E2E tests (requires Wastebin server)
just test-e2e

Goroutine leak detection: main_test.go and internal/wastebin/main_test.go run goleak in their respective test binaries. A leak in either package causes that package's test suite to exit with code -1. Use go test -v ./... to see leak output on stderr.

E2E test env vars: E2E_MCP_BINARY (set to skip per-test rebuild of the MCP binary) and E2E_RAW_RETRIEVAL_WARN (set to true to downgrade expired-paste failures to warnings for local runs). Both are optional.

Editing

  • Use patch-style edits for existing files (patch tool); avoid sed -i.
  • For new files, use write_file.
  • Follow the searxng-mcp-go patterns for SDK usage (github.com/modelcontextprotocol/go-sdk).

Code Cleanliness

  • Remove junk files before committing: .bak, *.test, *~, .swp, .swo.
  • .gitignore already covers *.bak, *.test, *.swp, *.swo, *.out, REPORT.md, .env.
  • The only correct build output binary name is wastebin-mcp-go. Do not create, commit, or leave behind binaries with other names (e.g. wastebin-mcp, wastebin, server) in the project root. Use go build -o wastebin-mcp-go . — never a different -o value.
  • NEVER create a binary with a name different from the project's canonical binary name. The canonical binary is wastebin-mcp-go (the module name). Use go build . (without -o) to let Go use the directory name, which IS the canonical name. If you use go build -o <name>, the name MUST be wastebin-mcp-go. Any other name is a self-inflicted mess that must be cleaned up immediately and NEVER added to .gitignore — that would hide the mistake instead of facing it.
  • .gitignore covers wastebin-mcp-go, *.bak, *.test, *.swp, *.swo, *.out, REPORT.md, .env, and common toolchain extensions.

Do Not Change

  • Do not modify .gitignore unless explicitly asked.

Documentation

  • All docs (docs/*.md, README, CONTEXT, AGENTS) must be in English.
  • Pull requests must update related documentation.

Go Skill Corpus

  • When the optional cc-skills-golang series is available, every AI agent working on Go code must locate and read the relevant skill files before editing, reviewing, or claiming completion.
  • For coding tasks, first identify the implementation domains involved, such as error handling, concurrency, context propagation, CLI behavior, testing, security, dependencies, or performance. Then read the matching cc-skills-golang skill files. Do not limit coding work to the review-focused skill subset.
  • Repository rules and local project context override generic skill advice.

Go Toolchain

Never manually install Go. Run which go before any Go command. If which go fails, report and stop — do not install, download, or work around it.

Verification

  • Before every commit that touches Go code, tests, dependencies, or Go-related scripts/workflows, the committing agent must run just verify locally. Do not guess or compose a custom verification command — use just verify.
  • just verify covers build, vet, lint, test (with race driver), mod tidy, and formatting. It mirrors the non-E2E CI pipeline.
  • After adding or changing MCP tool schemas, verify schema construction with mcp_test.go and schema_test.go (automated tests covering dynamic schema) in addition to just verify.
  • Pure documentation changes (.md files only) do not require just verify.
  • CLI testability caveat: runCLIMode writes JSON output directly to os.Stdout, not through a caller-provided io.Writer, so it cannot be cleanly unit-tested for output capture. Base schema/response coverage lives in mcp_test.go and schema_test.go.

GitHub and PR Work

  • Use gh CLI for all GitHub operations (not browser tools).
  • PR title and body must be in English.
  • PR agents must create requested PRs with gh pr create; do not stop after pushing a branch.
  • Do not ask cloud OpenCode (/oc) to amend, rebase, squash, reset, cherry-pick for history editing, force-push, or otherwise rewrite git history or existing commit metadata. Treat cloud OpenCode as unable to handle git history rewriting safely. If a PR check requires an existing commit message or author to be rewritten, handle it outside /oc or report it as a manual/local follow-up. /oc dispatches may ask for new additive commits for code, test, or documentation changes only.

Git Configuration

  • Treat all Git configuration as read-only. Agents may inspect Git config, but must not write, unset, or override any Git config at repo, worktree, global, system, file, submodule, or per-command (git -c) scope unless the current human explicitly names the config key to change. If Git fails because config or identity is missing, unsafe, or wrong, stop and report; do not repair, guess, or work around it.

Git Identity

  • Use the existing git identity as-is. Inspect with git config --get user.name / git config --get user.email. Do not set, override, or hard-code author/committer identity.
  • A commit with known wrong author metadata is tainted: do not make it the tip of any branch.

Key Constraints

  • No get_paste tool — agents should use curl {hostname}/raw/{id} instead.
  • File read mode is ON by default — configure ALLOWED_PATHS and review BLOCKED_PATHS defaults for sandbox deployments.
  • Schema is dynamic — file_path and translate_sandbox_path are excluded from the MCP tool schema when their respective features are disabled.
  • Upstream: github.com/xlionjuan/wastebin-mcp-go
  • SDK: github.com/modelcontextprotocol/go-sdk (same as searxng-mcp-go).
  • Error messages: English.
  • All docs: English.