unofficial-dinero-mcp-server: Instructions file for Claude Code

CLAUDE.md

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

Commands

go mod tidy           # fetch dependencies / regenerate go.sum
go build ./...        # compile
go vet ./...          # static analysis
go test ./...         # run all tests
go run .              # run server locally (no env vars needed — credentials come from URL)

Docker:

go mod tidy && docker build -t dinero-mcp .

Architecture

Go HTTP server using mark3labs/mcp-go for the MCP protocol.

Transport: Streamable HTTP via server.NewStreamableHTTPServer(s, server.WithStateLess(true)). Clients connect to /mcp with credentials as URL query params.

Auth: Credentials come from URL params on every request — no server-side env vars needed for Dinero. The middleware in internal/auth/middleware.go reads clientId, clientSecret, apiKey, organizationId from the URL, exchanges them for a Dinero OAuth token (cached in memory), and injects a *dinero.Client into the request context.

Dinero auth: OAuth password grant via https://authz.dinero.dk/dineroapi/oauth/token. Bearer token is cached per credential hash with 2-min early expiry.

Package layout:

• main.go — server startup, streamable HTTP wiring
• internal/auth/middleware.go — credential injection from URL params, token cache
• internal/dinero/auth.go — OAuth token exchange + in-memory cache
• internal/dinero/client.go — HTTP client with all Dinero API methods
• internal/tools/ — one file per domain (invoices, files, contacts, accounts); each exports a Register*(s) function
• internal/tools/helpers.go — strArg, intArg, boolArg, boolPtr, ClientFromCtx

Tool pattern: Tools call ClientFromCtx(ctx) to get the per-request Dinero client. Errors are returned as mcp.NewToolResultError(...) so the MCP client sees them as tool failures rather than protocol errors.

Accounting Year Rules