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.goandinternal/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.goandinternal/wastebin/main_test.gorun goleak in their respective test binaries. A leak in either package causes that package's test suite to exit with code -1. Usego 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) andE2E_RAW_RETRIEVAL_WARN(set totrueto downgrade expired-paste failures to warnings for local runs). Both are optional.
Editing
- Use patch-style edits for existing files (
patchtool); avoidsed -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. .gitignorealready 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. Usego build -o wastebin-mcp-go .— never a different-ovalue. - 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). Usego build .(without-o) to let Go use the directory name, which IS the canonical name. If you usego build -o <name>, the name MUST bewastebin-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. .gitignorecoverswastebin-mcp-go,*.bak,*.test,*.swp,*.swo,*.out,REPORT.md,.env, and common toolchain extensions.
Do Not Change
- Do not modify
.gitignoreunless 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-golangseries 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-golangskill 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 verifylocally. Do not guess or compose a custom verification command — usejust verify. just verifycovers 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.goandschema_test.go(automated tests covering dynamic schema) in addition tojust verify. - Pure documentation changes (
.mdfiles only) do not requirejust verify. - CLI testability caveat:
runCLIModewrites JSON output directly toos.Stdout, not through a caller-providedio.Writer, so it cannot be cleanly unit-tested for output capture. Base schema/response coverage lives inmcp_test.goandschema_test.go.
GitHub and PR Work
- Use
ghCLI 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/ocor report it as a manual/local follow-up./ocdispatches 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_pastetool — agents should usecurl {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_pathandtranslate_sandbox_pathare 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.