Go Conventions -- hairglasses-studio

Standards enforced across mcpkit, hg-mcp, mesmer, cobb, claudekit, and ralphglasses.

Error Handling

MCP tools communicate errors through results, not Go errors:

go
1// CORRECT -- always return (*CallToolResult, nil)
2return handler.CodedErrorResult(handler.ErrInvalidParam, err), nil
3
4// WRONG -- breaks MCP protocol
5return nil, err

Error codes: ErrClientInit, ErrInvalidParam, ErrTimeout, ErrNotFound, ErrAPIError, ErrPermission (defined in handler/result.go).

For non-MCP Go code, use standard fmt.Errorf("context: %w", err) wrapping.

Testing

bash
1go test ./pkg -count=1
2go test ./... -count=1 -race

• Integration: mcptest.NewServer() + mcptest.NewClient()
• Unit: stdlib testing, table-driven, t.Parallel() where safe
• File naming: foo_test.go tests foo.go
• Each package must pass in isolation
• Coverage target: 90%+ per package
• Assertions: mcptest.Assert* helpers or stdlib t.Errorf/t.Fatalf

Middleware

Signature:

go
1func(name string, td registry.ToolDefinition, next registry.ToolHandlerFunc) registry.ToolHandlerFunc

Thread Safety

• All registries: sync.RWMutex -- RLock for reads, Lock for writes
• Never hold a write lock while calling user-provided callbacks
• Lazy client init: sync.Once or LazyClient[T] pattern

Import Rules

• Lower dependency layers never import upper layers (Layer 1 < 2 < 3 < 4)
• One agent per package to avoid import cycles
• Import MCP types through registry/compat.go aliases for SDK portability

Dual-SDK Build Tags

go
1//go:build !official_sdk
2//go:build official_sdk

Use adapter functions: registry.MakeTextContent(), registry.MakeErrorResult(), registry.ExtractArguments() -- never SDK-specific constructors directly.

Parameter Extraction

go
1name := handler.GetStringParam(req, "name")
2count := handler.GetIntParam(req, "count", 10)
3flag := handler.GetBoolParam(req, "verbose", false)

Never access request.Params map directly.

Result Builders

Resilience

Every external service call should use:

1. CircuitBreaker
2. RateLimiter
3. Timeout

go
1resilience.NewCircuitBreaker(resilience.CBConfig{
2    MaxFailures:  5,
3    ResetTimeout: 30 * time.Second,
4})

RBAC And Audit

• Write-mode tools must have confirm_write parameter for destructive operations
• Audit middleware logs all tool invocations to JSONL
• Roles: admin, platform, support, readonly

Build Commands

bash
1go build ./...
2go vet ./...
3make check
4make build-official
5make check-dual

Code Organization

• init() for auto-registration -- no central tool lists
• Clients lazy-initialized via LazyClient[T] or sync.Once
• Config from env: centralized in client/config init, not scattered in handlers
• Atomic writes for config files: mktemp + mv pattern