mirror of
https://github.com/xlionjuan/wastebin-mcp-go.git
synced 2026-11-17 04:17:54 +00:00
140 lines
7.3 KiB
Markdown
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.
|