wastebin-mcp-go/AGENTS.md

140 lines
7.3 KiB
Markdown

# 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](docs/INSTALL.md) |
| MCP tool parameters | [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) |
| Issue tracker workflow | [docs/agents/issue-tracker.md](docs/agents/issue-tracker.md) |
| Triage labels | [docs/agents/triage-labels.md](docs/agents/triage-labels.md) |
| Domain and ADR workflow | [docs/agents/domain.md](docs/agents/domain.md) |
| Architecture decisions | [docs/adr/](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
```bash
# 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.