mcp and ucp

pkg/cart/mcp/jsonrpc.go

@@ -0,0 +1,44 @@
+package mcp
+
+import "encoding/json"
+
+// JSON-RPC 2.0 envelope types (the wire format MCP rides on). Notifications are
+// requests with no id and must not receive a response.
+
+type rpcRequest struct {
+	JSONRPC string          `json:"jsonrpc"`
+	ID      json.RawMessage `json:"id,omitempty"`
+	Method  string          `json:"method"`
+	Params  json.RawMessage `json:"params,omitempty"`
+}
+
+func (r *rpcRequest) isNotification() bool { return len(r.ID) == 0 }
+
+type rpcResponse struct {
+	JSONRPC string          `json:"jsonrpc"`
+	ID      json.RawMessage `json:"id,omitempty"`
+	Result  any             `json:"result,omitempty"`
+	Error   *rpcError       `json:"error,omitempty"`
+}
+
+type rpcError struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+	Data    any    `json:"data,omitempty"`
+}
+
+const (
+	codeParseError     = -32700
+	codeInvalidRequest = -32600
+	codeMethodNotFound = -32601
+	codeInvalidParams  = -32602
+	codeInternalError  = -32603
+)
+
+func result(id json.RawMessage, v any) *rpcResponse {
+	return &rpcResponse{JSONRPC: "2.0", ID: id, Result: v}
+}
+
+func errorResponse(id json.RawMessage, code int, msg string) *rpcResponse {
+	return &rpcResponse{JSONRPC: "2.0", ID: id, Error: &rpcError{Code: code, Message: msg}}
+}

pkg/cart/mcp/mcp.go

@@ -0,0 +1,159 @@
+// Package mcp is the MCP edge for the cart: a Model Context Protocol server
+// exposing the cart grain as tools so an agent can inspect and mutate carts
+// (list items, change quantities, remove items, clear carts, apply vouchers,
+// manage users, etc.).
+//
+// Transport is streamable HTTP (JSON-RPC 2.0 over POST). It is mounted by
+// cmd/cart under /mcp on the same HTTP server as the cart API. Tools map
+// 1:1 to cart grain read/apply operations; no restart is needed because every
+// tool call goes through the shared grain pool.
+package mcp
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+
+	"git.k6n.net/mats/go-cart-actor/pkg/actor"
+	"git.k6n.net/mats/go-cart-actor/pkg/cart"
+	"google.golang.org/protobuf/proto"
+)
+
+const (
+	serverName      = "cart"
+	serverVersion   = "0.1.0"
+	protocolVersion = "2025-06-18"
+)
+
+// Applier is the minimal grain-pool interface the cart MCP needs: read a
+// cart's current state (Get) and apply a mutation (Apply). The
+// SimpleGrainPool[cart.CartGrain] in cmd/cart satisfies it directly.
+type Applier interface {
+	Get(ctx context.Context, id uint64) (*cart.CartGrain, error)
+	Apply(ctx context.Context, id uint64, mutation ...proto.Message) (*actor.MutationResult[cart.CartGrain], error)
+}
+
+// Server is the MCP edge over the cart grain pool.
+type Server struct {
+	applier Applier
+	tools   []tool
+}
+
+// New builds an MCP server exposing the cart grain as tools.
+func New(applier Applier) *Server {
+	s := &Server{applier: applier}
+	s.tools = s.buildTools()
+	return s
+}
+
+// Handler returns the streamable-HTTP handler to mount (e.g. at /mcp).
+func (s *Server) Handler() http.Handler {
+	return http.HandlerFunc(s.serveHTTP)
+}
+
+func (s *Server) serveHTTP(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		w.Header().Set("Allow", "POST")
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	body, err := io.ReadAll(io.LimitReader(r.Body, 4<<20))
+	if err != nil {
+		writeRPC(w, errorResponse(nil, codeParseError, "read error"))
+		return
+	}
+	if isBatch(body) {
+		var reqs []rpcRequest
+		if err := json.Unmarshal(body, &reqs); err != nil {
+			writeRPC(w, errorResponse(nil, codeParseError, "invalid JSON"))
+			return
+		}
+		var out []*rpcResponse
+		for i := range reqs {
+			if resp := s.dispatch(&reqs[i]); resp != nil {
+				out = append(out, resp)
+			}
+		}
+		if len(out) == 0 {
+			w.WriteHeader(http.StatusAccepted)
+			return
+		}
+		writeRPC(w, out)
+		return
+	}
+	var req rpcRequest
+	if err := json.Unmarshal(body, &req); err != nil {
+		writeRPC(w, errorResponse(nil, codeParseError, "invalid JSON"))
+		return
+	}
+	resp := s.dispatch(&req)
+	if resp == nil {
+		w.WriteHeader(http.StatusAccepted)
+		return
+	}
+	writeRPC(w, resp)
+}
+
+func (s *Server) dispatch(req *rpcRequest) *rpcResponse {
+	if req.JSONRPC != "2.0" {
+		if req.isNotification() {
+			return nil
+		}
+		return errorResponse(req.ID, codeInvalidRequest, "jsonrpc must be \"2.0\"")
+	}
+	switch req.Method {
+	case "initialize":
+		return result(req.ID, s.initialize(req.Params))
+	case "ping":
+		return result(req.ID, struct{}{})
+	case "tools/list":
+		return result(req.ID, map[string]any{"tools": s.tools})
+	case "tools/call":
+		return s.callTool(req)
+	case "notifications/initialized", "notifications/cancelled":
+		return nil
+	default:
+		if req.isNotification() {
+			return nil
+		}
+		return errorResponse(req.ID, codeMethodNotFound, "unknown method: "+req.Method)
+	}
+}
+
+func (s *Server) initialize(params json.RawMessage) map[string]any {
+	pv := protocolVersion
+	if len(params) > 0 {
+		var p struct {
+			ProtocolVersion string `json:"protocolVersion"`
+		}
+		if json.Unmarshal(params, &p) == nil && p.ProtocolVersion != "" {
+			pv = p.ProtocolVersion
+		}
+	}
+	return map[string]any{
+		"protocolVersion": pv,
+		"capabilities":    map[string]any{"tools": map[string]any{}},
+		"serverInfo":      map[string]any{"name": serverName, "version": serverVersion},
+	}
+}
+
+func isBatch(body []byte) bool {
+	for _, b := range body {
+		switch b {
+		case ' ', '\t', '\r', '\n':
+			continue
+		case '[':
+			return true
+		default:
+			return false
+		}
+	}
+	return false
+}
+
+func writeRPC(w http.ResponseWriter, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusOK)
+	_ = json.NewEncoder(w).Encode(v)
+}

pkg/cart/mcp/mcp_test.go

@@ -0,0 +1,421 @@
+package mcp
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"git.k6n.net/mats/go-cart-actor/pkg/actor"
+	"git.k6n.net/mats/go-cart-actor/pkg/cart"
+	"google.golang.org/protobuf/proto"
+)
+
+// testApplier implements Applier with an in-memory map of carts, using the real
+// cart mutation registry so write tools exercise the actual mutation handlers.
+type testApplier struct {
+	grains map[uint64]*cart.CartGrain
+	reg    actor.MutationRegistry
+}
+
+func newTestApplier() *testApplier {
+	reg := cart.NewCartMultationRegistry(cart.NewCartMutationContext(nil))
+	return &testApplier{
+		grains: make(map[uint64]*cart.CartGrain),
+		reg:    reg,
+	}
+}
+
+func (a *testApplier) addCart(id uint64, items int) *cart.CartGrain {
+	g := cart.NewCartGrain(id, time.Now())
+	g.Currency = "SEK"
+	g.Language = "sv-se"
+	for i := 1; i <= items; i++ {
+		g.Items = append(g.Items, &cart.CartItem{
+			Id:       uint32(i),
+			ItemId:   uint32(1000 + i),
+			Sku:      fmt.Sprintf("SKU-%03d", i),
+			Quantity: uint16(i),
+			Price:    *cart.NewPriceFromIncVat(int64(i*10000), 25),
+			Tax:      2500,
+			Meta:     &cart.ItemMeta{Name: fmt.Sprintf("Item %d", i)},
+		})
+	}
+	g.UpdateTotals()
+	a.grains[id] = g
+	return g
+}
+
+func (a *testApplier) Get(_ context.Context, id uint64) (*cart.CartGrain, error) {
+	g, ok := a.grains[id]
+	if !ok {
+		return nil, fmt.Errorf("cart %d not found", id)
+	}
+	return g, nil
+}
+
+func (a *testApplier) Apply(ctx context.Context, id uint64, msgs ...proto.Message) (*actor.MutationResult[cart.CartGrain], error) {
+	g, ok := a.grains[id]
+	if !ok {
+		return nil, fmt.Errorf("cart %d not found", id)
+	}
+	results, err := a.reg.Apply(ctx, g, msgs...)
+	if err != nil {
+		return nil, err
+	}
+	// Re-read state after mutations.
+	state, err := g.GetCurrentState()
+	if err != nil {
+		return nil, err
+	}
+	return &actor.MutationResult[cart.CartGrain]{
+		Result:    *state, //nolint:govet // test helper snapshot, same pattern as SimpleGrainPool
+		Mutations: results,
+	}, nil
+
+}
+
+// call issues a tools/call against the handler and returns the decoded text
+// payload (the JSON the tool returned), failing on a tool/transport error.
+func call(t *testing.T, h http.Handler, name string, args map[string]any) map[string]any {
+	t.Helper()
+	body, _ := json.Marshal(map[string]any{
+		"jsonrpc": "2.0",
+		"id":      1,
+		"method":  "tools/call",
+		"params":  map[string]any{"name": name, "arguments": args},
+	})
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/mcp", bytes.NewReader(body))
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("%s: status %d", name, rec.Code)
+	}
+	var resp struct {
+		Result struct {
+			IsError bool `json:"isError"`
+			Content []struct {
+				Text string `json:"text"`
+			} `json:"content"`
+		} `json:"result"`
+		Error *struct {
+			Message string `json:"message"`
+		} `json:"error"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("%s: decode response: %v (%s)", name, err, rec.Body.String())
+	}
+	if resp.Error != nil {
+		t.Fatalf("%s: rpc error: %s", name, resp.Error.Message)
+	}
+	if resp.Result.IsError {
+		t.Fatalf("%s: tool error: %s", name, resp.Result.Content[0].Text)
+	}
+	var out map[string]any
+	if len(resp.Result.Content) > 0 {
+		_ = json.Unmarshal([]byte(resp.Result.Content[0].Text), &out)
+	}
+	return out
+}
+
+func TestCartMCPRoundTrip(t *testing.T) {
+	a := newTestApplier()
+	a.addCart(42, 3) // cart 42 with 3 items
+	h := New(a).Handler()
+
+	// get_cart
+	got := call(t, h, "get_cart", map[string]any{"cartId": "g"})
+	if got == nil {
+		t.Fatal("get_cart returned nil")
+	}
+	if id, _ := got["id"].(string); id != "g" {
+		t.Errorf("get_cart id = %v, want g", got["id"])
+	}
+	if curr, _ := got["currency"].(string); curr != "SEK" {
+		t.Errorf("get_cart currency = %q, want SEK", curr)
+	}
+
+	// get_cart_items
+	items := call(t, h, "get_cart_items", map[string]any{"cartId": "g"})
+	if c, _ := items["count"].(float64); c != 3 {
+		t.Errorf("get_cart_items count = %v, want 3", items["count"])
+	}
+
+	// get_cart_totals
+	totals := call(t, h, "get_cart_totals", map[string]any{"cartId": "g"})
+	if _, ok := totals["totalPrice"]; !ok {
+		t.Errorf("get_cart_totals missing totalPrice: %v", totals)
+	}
+	if _, ok := totals["totalDiscount"]; !ok {
+		t.Errorf("get_cart_totals missing totalDiscount: %v", totals)
+	}
+
+	// get_cart_vouchers (empty cart)
+	vouchers := call(t, h, "get_cart_vouchers", map[string]any{"cartId": "g"})
+	if c, _ := vouchers["count"].(float64); c != 0 {
+		t.Errorf("get_cart_vouchers count = %v, want 0", vouchers["count"])
+	}
+
+	// update_item_quantity: change item id=1 from qty 1 to qty 5
+	updated := call(t, h, "update_item_quantity", map[string]any{
+		"cartId": "g", "itemId": 1, "quantity": 5,
+	})
+	if updated == nil {
+		t.Fatal("update_item_quantity returned nil")
+	}
+	// Verify via get_cart_items
+	items2 := call(t, h, "get_cart_items", map[string]any{"cartId": "g"})
+	itemsRaw, _ := items2["items"].([]any)
+	if len(itemsRaw) != 3 {
+		t.Fatalf("after qty change: want 3 items, got %d", len(itemsRaw))
+	}
+	firstItem := itemsRaw[0].(map[string]any)
+	if q, _ := firstItem["qty"].(float64); q != 5 {
+		t.Errorf("item 1 qty = %v, want 5", q)
+	}
+
+	// remove_cart_item: remove item id=2
+	removed := call(t, h, "remove_cart_item", map[string]any{
+		"cartId": "g", "itemId": 2,
+	})
+	if removed == nil {
+		t.Fatal("remove_cart_item returned nil")
+	}
+	items3 := call(t, h, "get_cart_items", map[string]any{"cartId": "g"})
+	itemsRaw3, _ := items3["items"].([]any)
+	if len(itemsRaw3) != 2 {
+		t.Fatalf("after remove: want 2 items, got %d", len(itemsRaw3))
+	}
+
+	// apply_voucher
+	withVoucher := call(t, h, "apply_voucher", map[string]any{
+		"cartId": "g", "code": "SAVE10", "value": 10000,
+	})
+	if withVoucher == nil {
+		t.Fatal("apply_voucher returned nil")
+	}
+	vouchers2 := call(t, h, "get_cart_vouchers", map[string]any{"cartId": "g"})
+	if c, _ := vouchers2["count"].(float64); c != 1 {
+		t.Errorf("after voucher apply: count = %v, want 1", vouchers2["count"])
+	}
+
+	// remove_voucher: find the voucher id
+	voucherList, _ := vouchers2["vouchers"].([]any)
+	if len(voucherList) > 0 {
+		v := voucherList[0].(map[string]any)
+		vID := v["id"].(float64)
+		call(t, h, "remove_voucher", map[string]any{
+			"cartId": "g", "voucherId": int(vID),
+		})
+		vouchers3 := call(t, h, "get_cart_vouchers", map[string]any{"cartId": "g"})
+		if c, _ := vouchers3["count"].(float64); c != 0 {
+			t.Errorf("after remove voucher: count = %v, want 0", vouchers3["count"])
+		}
+	}
+
+	// set_cart_user
+	withUser := call(t, h, "set_cart_user", map[string]any{
+		"cartId": "g", "userId": "user-abc-123",
+	})
+	if withUser == nil {
+		t.Fatal("set_cart_user returned nil")
+	}
+
+	// clear_cart
+	cleared := call(t, h, "clear_cart", map[string]any{"cartId": "g"})
+	if cleared == nil {
+		t.Fatal("clear_cart returned nil")
+	}
+	items4 := call(t, h, "get_cart_items", map[string]any{"cartId": "g"})
+	if c, _ := items4["count"].(float64); c != 0 {
+		t.Errorf("after clear: count = %v, want 0", items4["count"])
+	}
+}
+
+func TestCartMCPErrors(t *testing.T) {
+	a := newTestApplier()
+	a.addCart(1, 1)
+	h := New(a).Handler()
+
+	// Invalid cart id -> isError result.
+	result := callWithRaw(t, h, "get_cart", map[string]any{"cartId": "!!!"})
+	if !result.IsError {
+		t.Fatal("expected isError for invalid cart id")
+	}
+
+	// Missing required cartId -> still hits decode (cartId absent is empty string)
+	result2 := callWithRaw(t, h, "get_cart", map[string]any{})
+	if !result2.IsError {
+		t.Fatal("expected isError for missing cartId")
+	}
+
+	// Non-existent cart -> isError result.
+	result3 := callWithRaw(t, h, "get_cart", map[string]any{"cartId": "zzzzzz"})
+	if !result3.IsError {
+		t.Fatal("expected isError for non-existent cart")
+	}
+
+	// Remove non-existent item -> isError
+	result4 := callWithRaw(t, h, "remove_cart_item", map[string]any{
+		"cartId": "1", "itemId": 999,
+	})
+	if !result4.IsError {
+		t.Fatal("expected isError for non-existent item")
+	}
+
+	// Unknown tool -> protocol error.
+	var resp struct {
+		Error *struct {
+			Message string `json:"message"`
+		} `json:"error"`
+	}
+	body, _ := json.Marshal(map[string]any{
+		"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+		"params": map[string]any{"name": "nope", "arguments": map[string]any{}},
+	})
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/mcp", bytes.NewReader(body))
+	h.ServeHTTP(rec, req)
+	json.Unmarshal(rec.Body.Bytes(), &resp)
+	if resp.Error == nil {
+		t.Fatal("expected protocol error for unknown tool")
+	}
+}
+
+// callWithRaw returns the raw result (including isError) without failing.
+type rawResult struct {
+	IsError bool
+	Content []struct {
+		Text string `json:"text"`
+	}
+}
+
+func callWithRaw(t *testing.T, h http.Handler, name string, args map[string]any) rawResult {
+	t.Helper()
+	body, _ := json.Marshal(map[string]any{
+		"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+		"params": map[string]any{"name": name, "arguments": args},
+	})
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/mcp", bytes.NewReader(body))
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("%s: status %d", name, rec.Code)
+	}
+	var resp struct {
+		Result rawResult `json:"result"`
+		Error  *struct{ Message string } `json:"error"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("%s: decode: %v", name, err)
+	}
+	if resp.Error != nil {
+		t.Fatalf("%s: rpc error: %s", name, resp.Error.Message)
+	}
+	return resp.Result
+}
+
+func TestInitializeAndToolsList(t *testing.T) {
+	a := newTestApplier()
+	h := New(a).Handler()
+
+	// Initialize.
+	body, _ := json.Marshal(map[string]any{
+		"jsonrpc": "2.0", "id": 1, "method": "initialize",
+		"params": map[string]any{"protocolVersion": "2025-06-18"},
+	})
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/mcp", bytes.NewReader(body))
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("initialize: status %d", rec.Code)
+	}
+	var initResp struct {
+		Result struct {
+			ProtocolVersion string `json:"protocolVersion"`
+			ServerInfo      struct {
+				Name string `json:"name"`
+			} `json:"serverInfo"`
+		} `json:"result"`
+	}
+	json.Unmarshal(rec.Body.Bytes(), &initResp)
+	if initResp.Result.ProtocolVersion != "2025-06-18" || initResp.Result.ServerInfo.Name != "cart" {
+		t.Fatalf("unexpected initialize: %+v", initResp)
+	}
+
+	// tools/list.
+	body2, _ := json.Marshal(map[string]any{
+		"jsonrpc": "2.0", "id": 1, "method": "tools/list",
+	})
+	rec2 := httptest.NewRecorder()
+	req2 := httptest.NewRequest(http.MethodPost, "/mcp", bytes.NewReader(body2))
+	h.ServeHTTP(rec2, req2)
+	var listResp struct {
+		Result struct {
+			Tools []struct {
+				Name        string          `json:"name"`
+				InputSchema json.RawMessage `json:"inputSchema"`
+			} `json:"tools"`
+		} `json:"result"`
+	}
+	json.Unmarshal(rec2.Body.Bytes(), &listResp)
+	want := map[string]bool{
+		"get_cart": false, "update_item_quantity": false,
+		"remove_cart_item": false, "clear_cart": false,
+	}
+	for _, tl := range listResp.Result.Tools {
+		if _, ok := want[tl.Name]; ok {
+			want[tl.Name] = true
+		}
+		if len(tl.InputSchema) == 0 {
+			t.Fatalf("tool %s has empty inputSchema", tl.Name)
+		}
+	}
+	for name, found := range want {
+		if !found {
+			t.Fatalf("expected tool %q in tools/list", name)
+		}
+	}
+}
+
+func TestCartMCPCartIdRoundTrip(t *testing.T) {
+	// Verify that we can round-trip a base62 cart id through tools.
+	a := newTestApplier()
+	// Use a larger cart id to test base62 encoding.
+	g := cart.NewCartGrain(12345, time.Now())
+	g.Currency = "EUR"
+	a.grains[12345] = g
+	h := New(a).Handler()
+
+	got := call(t, h, "get_cart", map[string]any{"cartId": g.Id.String()})
+	if curr, _ := got["currency"].(string); curr != "EUR" {
+		t.Errorf("currency = %q, want EUR", curr)
+	}
+}
+
+func TestGetCartPromotions(t *testing.T) {
+	a := newTestApplier()
+	g := a.addCart(99, 2)
+	// Add a synthetic applied promotion.
+	g.AppliedPromotions = []cart.AppliedPromotion{
+		{PromotionId: "volymrabatt", Name: "Volymrabatt", Type: "tiered_discount", Discount: cart.NewPriceFromIncVat(10000, 25)},
+	}
+	h := New(a).Handler()
+
+	result := call(t, h, "get_cart_promotions", map[string]any{"cartId": g.Id.String()})
+	if result == nil {
+		t.Fatal("get_cart_promotions returned nil")
+	}
+	promos, _ := result["appliedPromotions"].([]any)
+	if len(promos) != 1 {
+		t.Fatalf("want 1 promotion, got %d", len(promos))
+	}
+	p := promos[0].(map[string]any)
+	if name, _ := p["name"].(string); name != "Volymrabatt" {
+		t.Errorf("promotion name = %q, want Volymrabatt", name)
+	}
+}

pkg/cart/mcp/tools.go

@@ -0,0 +1,439 @@
+package mcp
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"git.k6n.net/mats/go-cart-actor/pkg/cart"
+	messages "git.k6n.net/mats/go-cart-actor/proto/cart"
+)
+
+// tool is one MCP tool: a name, a description, a JSON-Schema for its arguments,
+// and the handler that runs it.
+type tool struct {
+	Name        string                                  `json:"name"`
+	Description string                                  `json:"description"`
+	InputSchema json.RawMessage                         `json:"inputSchema"`
+	invoke      func(args json.RawMessage) (any, error) `json:"-"`
+}
+
+func (s *Server) callTool(req *rpcRequest) *rpcResponse {
+	var p struct {
+		Name      string          `json:"name"`
+		Arguments json.RawMessage `json:"arguments"`
+	}
+	if err := json.Unmarshal(req.Params, &p); err != nil {
+		return errorResponse(req.ID, codeInvalidParams, "invalid params")
+	}
+	var t *tool
+	for i := range s.tools {
+		if s.tools[i].Name == p.Name {
+			t = &s.tools[i]
+			break
+		}
+	}
+	if t == nil {
+		return errorResponse(req.ID, codeInvalidParams, "unknown tool: "+p.Name)
+	}
+	out, err := t.invoke(p.Arguments)
+	if err != nil {
+		return result(req.ID, toolError(err))
+	}
+	return result(req.ID, toolText(out))
+}
+
+func (s *Server) buildTools() []tool {
+	return []tool{
+		{
+			Name:        "get_cart",
+			Description: "Get the full state of a cart by its base62 cart id: items, totals, vouchers, promotions, user info, currency, language, checkout status, subscription details, and all applied/pending promotions with progress nudges.",
+			InputSchema: object(props{
+				"cartId": str("the base62 cart id"),
+			}, []string{"cartId"}),
+			invoke: func(args json.RawMessage) (any, error) {
+				var a struct {
+					CartID string `json:"cartId"`
+				}
+				if err := decode(args, &a); err != nil {
+					return nil, err
+				}
+				id, ok := cart.ParseCartId(a.CartID)
+				if !ok {
+					return nil, fmt.Errorf("invalid cart id %q", a.CartID)
+				}
+				g, err := s.applier.Get(context.Background(), uint64(id))
+				if err != nil {
+					return nil, fmt.Errorf("get cart: %w", err)
+				}
+				return g, nil
+			},
+		},
+		{
+			Name:        "get_cart_items",
+			Description: "List all items in a cart with their SKU, name, quantity, unit price, total price, stock, tax rate, markings, custom fields, and optional child/parent relationships.",
+			InputSchema: object(props{
+				"cartId": str("the base62 cart id"),
+			}, []string{"cartId"}),
+			invoke: func(args json.RawMessage) (any, error) {
+				var a struct {
+					CartID string `json:"cartId"`
+				}
+				if err := decode(args, &a); err != nil {
+					return nil, err
+				}
+				id, ok := cart.ParseCartId(a.CartID)
+				if !ok {
+					return nil, fmt.Errorf("invalid cart id %q", a.CartID)
+				}
+				g, err := s.applier.Get(context.Background(), uint64(id))
+				if err != nil {
+					return nil, fmt.Errorf("get cart: %w", err)
+				}
+				return map[string]any{"items": g.Items, "count": len(g.Items)}, nil
+			},
+		},
+		{
+			Name:        "get_cart_totals",
+			Description: "Get price breakdown for a cart: total incVat, total exVat, VAT breakdown by rate, total discount (vouchers + promotions), and per-item totals.",
+			InputSchema: object(props{
+				"cartId": str("the base62 cart id"),
+			}, []string{"cartId"}),
+			invoke: func(args json.RawMessage) (any, error) {
+				var a struct {
+					CartID string `json:"cartId"`
+				}
+				if err := decode(args, &a); err != nil {
+					return nil, err
+				}
+				id, ok := cart.ParseCartId(a.CartID)
+				if !ok {
+					return nil, fmt.Errorf("invalid cart id %q", a.CartID)
+				}
+				g, err := s.applier.Get(context.Background(), uint64(id))
+				if err != nil {
+					return nil, fmt.Errorf("get cart: %w", err)
+				}
+				return map[string]any{
+					"totalPrice":    g.TotalPrice,
+					"totalDiscount": g.TotalDiscount,
+					"currency":      g.Currency,
+					"language":      g.Language,
+					"vouchers":      g.Vouchers,
+				}, nil
+			},
+		},
+		{
+			Name:        "get_cart_promotions",
+			Description: "Get all applied and pending promotions on a cart, including discount amounts and progress nudges (e.g. 'spend 1200 SEK more for free shipping').",
+			InputSchema: object(props{
+				"cartId": str("the base62 cart id"),
+			}, []string{"cartId"}),
+			invoke: func(args json.RawMessage) (any, error) {
+				var a struct {
+					CartID string `json:"cartId"`
+				}
+				if err := decode(args, &a); err != nil {
+					return nil, err
+				}
+				id, ok := cart.ParseCartId(a.CartID)
+				if !ok {
+					return nil, fmt.Errorf("invalid cart id %q", a.CartID)
+				}
+				g, err := s.applier.Get(context.Background(), uint64(id))
+				if err != nil {
+					return nil, fmt.Errorf("get cart: %w", err)
+				}
+				return map[string]any{
+					"appliedPromotions": g.AppliedPromotions,
+					"totalDiscount":     g.TotalDiscount,
+				}, nil
+			},
+		},
+		{
+			Name:        "get_cart_vouchers",
+			Description: "List all vouchers applied to a cart with their codes, values, rules, and whether they are currently active.",
+			InputSchema: object(props{
+				"cartId": str("the base62 cart id"),
+			}, []string{"cartId"}),
+			invoke: func(args json.RawMessage) (any, error) {
+				var a struct {
+					CartID string `json:"cartId"`
+				}
+				if err := decode(args, &a); err != nil {
+					return nil, err
+				}
+				id, ok := cart.ParseCartId(a.CartID)
+				if !ok {
+					return nil, fmt.Errorf("invalid cart id %q", a.CartID)
+				}
+				g, err := s.applier.Get(context.Background(), uint64(id))
+				if err != nil {
+					return nil, fmt.Errorf("get cart: %w", err)
+				}
+				return map[string]any{"vouchers": g.Vouchers, "count": len(g.Vouchers)}, nil
+			},
+		},
+		{
+			Name:        "update_item_quantity",
+			Description: "Change the quantity of a line item in a cart. Use quantity=0 to remove the item. Returns the updated cart state.",
+			InputSchema: object(props{
+				"cartId":   str("the base62 cart id"),
+				"itemId":   integer("the line item id (numeric, e.g. 1, 2, 3)"),
+				"quantity": integer("the new quantity (0 removes the item)"),
+			}, []string{"cartId", "itemId", "quantity"}),
+			invoke: func(args json.RawMessage) (any, error) {
+				var a struct {
+					CartID   string `json:"cartId"`
+					ItemID   int    `json:"itemId"`
+					Quantity int32  `json:"quantity"`
+				}
+				if err := decode(args, &a); err != nil {
+					return nil, err
+				}
+				id, ok := cart.ParseCartId(a.CartID)
+				if !ok {
+					return nil, fmt.Errorf("invalid cart id %q", a.CartID)
+				}
+				res, err := s.applier.Apply(context.Background(), uint64(id), &messages.ChangeQuantity{
+					Id:       uint32(a.ItemID),
+					Quantity: a.Quantity,
+				})
+				if err != nil {
+					return nil, fmt.Errorf("change quantity: %w", err)
+				}
+				// Check for per-mutation errors.
+				for _, m := range res.Mutations {
+					if m.Error != nil {
+						return nil, m.Error
+					}
+				}
+				return map[string]any{"cartId": a.CartID, "cart": &res.Result}, nil
+			},
+		},
+		{
+			Name:        "remove_cart_item",
+			Description: "Remove a line item (and its children) from a cart by item id. Returns the updated cart state.",
+			InputSchema: object(props{
+				"cartId": str("the base62 cart id"),
+				"itemId": integer("the line item id to remove (numeric, e.g. 1, 2, 3)"),
+			}, []string{"cartId", "itemId"}),
+			invoke: func(args json.RawMessage) (any, error) {
+				var a struct {
+					CartID string `json:"cartId"`
+					ItemID int    `json:"itemId"`
+				}
+				if err := decode(args, &a); err != nil {
+					return nil, err
+				}
+				id, ok := cart.ParseCartId(a.CartID)
+				if !ok {
+					return nil, fmt.Errorf("invalid cart id %q", a.CartID)
+				}
+				res, err := s.applier.Apply(context.Background(), uint64(id), &messages.RemoveItem{Id: uint32(a.ItemID)})
+				if err != nil {
+					return nil, fmt.Errorf("remove item: %w", err)
+				}
+				for _, m := range res.Mutations {
+					if m.Error != nil {
+						return nil, m.Error
+					}
+				}
+				return map[string]any{"cartId": a.CartID, "cart": &res.Result}, nil
+			},
+		},
+		{
+			Name:        "clear_cart",
+			Description: "Remove all items and vouchers from a cart, resetting it to an empty state. The cart id, user id, and currency are preserved. Returns the updated (empty) cart.",
+			InputSchema: object(props{
+				"cartId": str("the base62 cart id"),
+			}, []string{"cartId"}),
+			invoke: func(args json.RawMessage) (any, error) {
+				var a struct {
+					CartID string `json:"cartId"`
+				}
+				if err := decode(args, &a); err != nil {
+					return nil, err
+				}
+				id, ok := cart.ParseCartId(a.CartID)
+				if !ok {
+					return nil, fmt.Errorf("invalid cart id %q", a.CartID)
+				}
+				res, err := s.applier.Apply(context.Background(), uint64(id), &messages.ClearCartRequest{})
+				if err != nil {
+					return nil, fmt.Errorf("clear cart: %w", err)
+				}
+				for _, m := range res.Mutations {
+					if m.Error != nil {
+						return nil, m.Error
+					}
+				}
+				return map[string]any{"cartId": a.CartID, "cart": &res.Result}, nil
+			},
+		},
+		{
+			Name:        "apply_voucher",
+			Description: "Apply a voucher code to a cart. The voucher value is in öre (e.g. 10000 = 100 kr). Returns the updated cart with the voucher applied.",
+			InputSchema: object(props{
+				"cartId":      str("the base62 cart id"),
+				"code":        str("the voucher code"),
+				"value":       integer("the voucher value in öre (e.g. 10000 = 100 kr)"),
+				"description": str("optional description of the voucher"),
+				"rules":       stringArray("optional list of rule expressions for when the voucher applies"),
+			}, []string{"cartId", "code", "value"}),
+			invoke: func(args json.RawMessage) (any, error) {
+				var a struct {
+					CartID      string   `json:"cartId"`
+					Code        string   `json:"code"`
+					Value       int64    `json:"value"`
+					Description string   `json:"description"`
+					Rules       []string `json:"rules"`
+				}
+				if err := decode(args, &a); err != nil {
+					return nil, err
+				}
+				id, ok := cart.ParseCartId(a.CartID)
+				if !ok {
+					return nil, fmt.Errorf("invalid cart id %q", a.CartID)
+				}
+				res, err := s.applier.Apply(context.Background(), uint64(id), &messages.AddVoucher{
+					Code:         a.Code,
+					Value:        a.Value,
+					Description:  a.Description,
+					VoucherRules: a.Rules,
+				})
+				if err != nil {
+					return nil, fmt.Errorf("apply voucher: %w", err)
+				}
+				for _, m := range res.Mutations {
+					if m.Error != nil {
+						return nil, m.Error
+					}
+				}
+				return map[string]any{"cartId": a.CartID, "cart": &res.Result}, nil
+			},
+		},
+		{
+			Name:        "remove_voucher",
+			Description: "Remove a voucher from a cart by its voucher id. Returns the updated cart.",
+			InputSchema: object(props{
+				"cartId":    str("the base62 cart id"),
+				"voucherId": integer("the voucher id to remove (numeric)"),
+			}, []string{"cartId", "voucherId"}),
+			invoke: func(args json.RawMessage) (any, error) {
+				var a struct {
+					CartID    string `json:"cartId"`
+					VoucherID int    `json:"voucherId"`
+				}
+				if err := decode(args, &a); err != nil {
+					return nil, err
+				}
+				id, ok := cart.ParseCartId(a.CartID)
+				if !ok {
+					return nil, fmt.Errorf("invalid cart id %q", a.CartID)
+				}
+				res, err := s.applier.Apply(context.Background(), uint64(id), &messages.RemoveVoucher{Id: uint32(a.VoucherID)})
+				if err != nil {
+					return nil, fmt.Errorf("remove voucher: %w", err)
+				}
+				for _, m := range res.Mutations {
+					if m.Error != nil {
+						return nil, m.Error
+					}
+				}
+				return map[string]any{"cartId": a.CartID, "cart": &res.Result}, nil
+			},
+		},
+		{
+			Name:        "set_cart_user",
+			Description: "Set or update the user ID on a cart, linking it to a customer account. Returns the updated cart.",
+			InputSchema: object(props{
+				"cartId": str("the base62 cart id"),
+				"userId": str("the user/customer id"),
+			}, []string{"cartId", "userId"}),
+			invoke: func(args json.RawMessage) (any, error) {
+				var a struct {
+					CartID string `json:"cartId"`
+					UserID string `json:"userId"`
+				}
+				if err := decode(args, &a); err != nil {
+					return nil, err
+				}
+				id, ok := cart.ParseCartId(a.CartID)
+				if !ok {
+					return nil, fmt.Errorf("invalid cart id %q", a.CartID)
+				}
+				res, err := s.applier.Apply(context.Background(), uint64(id), &messages.SetUserId{UserId: a.UserID})
+				if err != nil {
+					return nil, fmt.Errorf("set user: %w", err)
+				}
+				for _, m := range res.Mutations {
+					if m.Error != nil {
+						return nil, m.Error
+					}
+				}
+				return map[string]any{"cartId": a.CartID, "cart": &res.Result}, nil
+			},
+		},
+	}
+}
+
+// ---- result + schema helpers -----------------------------------------------
+
+func toolText(v any) map[string]any {
+	b, err := json.Marshal(v)
+	if err != nil {
+		return toolError(err)
+	}
+	return map[string]any{
+		"content": []map[string]any{{"type": "text", "text": string(b)}},
+	}
+}
+
+func toolError(err error) map[string]any {
+	return map[string]any{
+		"isError": true,
+		"content": []map[string]any{{"type": "text", "text": err.Error()}},
+	}
+}
+
+// decode unmarshals tool arguments, tolerating empty/absent arguments.
+func decode(args json.RawMessage, v any) error {
+	if len(args) == 0 || string(args) == "null" {
+		return nil
+	}
+	if err := json.Unmarshal(args, v); err != nil {
+		return fmt.Errorf("invalid arguments: %w", err)
+	}
+	return nil
+}
+
+type props map[string]json.RawMessage
+
+func object(p props, required []string) json.RawMessage {
+	m := map[string]any{
+		"type":       "object",
+		"properties": p,
+	}
+	if len(required) > 0 {
+		m["required"] = required
+	}
+	b, _ := json.Marshal(m)
+	return b
+}
+
+func str(desc string) json.RawMessage       { return scalar("string", desc) }
+func integer(d string) json.RawMessage      { return scalar("integer", d) }
+func obj(desc string) json.RawMessage       { return scalar("object", desc) }
+
+func scalar(typ, desc string) json.RawMessage {
+	b, _ := json.Marshal(map[string]any{"type": typ, "description": desc})
+	return b
+}
+
+func stringArray(desc string) json.RawMessage {
+	b, _ := json.Marshal(map[string]any{
+		"type": "array", "description": desc, "items": map[string]string{"type": "string"},
+	})
+	return b
+}