luno-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development commands

• make build - Build the luno-mcp binary into the repo root
• make test - Run all tests (go test ./...)
• go test ./internal/tools/... -run TestHandleGetBalances - Run a single test or package
• make run-stdio / make run-sse / make run-streamable-http - Run server with each transport
• make install - Install binary to $GOBIN
• make pre-commit - Install pre-commit hooks (requires gofumpt installed separately: go install mvdan.cc/gofumpt@latest)
• go tool mockery - Regenerate mocks (mockery is declared as a Go tool in go.mod, not invoked standalone). Config is in .mockery.yml.

Pre-commit runs go-vet-mod, go-imports, gofumpt, go-mod-tidy-repo, go-test-repo-mod, plus YAML/whitespace/EOF checks and a script-test for claude-desktop-install.sh. These run on every commit - run pre-commit run --all-files to validate before pushing.

Architecture

This is an MCP server wrapping the Luno crypto exchange API. Three layers matter:

sdk/luno_client.go defines the LunoClient interface that all tool/resource handlers depend on. The real *luno.Client satisfies it via a compile-time check; sdk/mock_luno_client_gen.go is the mockery-generated test double. Never call luno.Client methods directly from internal/ - go through the interface so tests can substitute the mock.

internal/config owns Config, which carries the LunoClient, an IsAuthenticated flag, and AllowWriteOperations. config.Load() decides authentication mode by inspecting env vars at startup - if LUNO_API_KEY_ID/LUNO_API_SECRET are absent, the server runs in unauthenticated mode and authenticated tools (get_balances, list_orders, etc.) return ErrAPICredentialsRequired rather than failing at registration time. CLI --allow-write-operations overrides the env var.

internal/server/server.go wires everything: NewMCPServer registers resources and tools, then ServeStdio / ServeSSE / ServeStreamableHTTP start the chosen transport. Key design choice in registerTools: write tools (create_order, cancel_order) are always registered with the server, but when AllowWriteOperations=false they are bound to HandleWriteOperationDisabled() instead of their real handlers. This means MCP clients can see the tools exist and discover how to enable them, rather than the tools silently disappearing. Don't change this pattern when adding new write tools.