diff --git a/go.mod b/go.mod index 0fa66c1..ad86f85 100644 --- a/go.mod +++ b/go.mod @@ -5,14 +5,14 @@ go 1.26.11 require ( github.com/basecamp/cli v0.2.1 github.com/basecamp/fizzy-sdk/go v0.3.0 - github.com/basecamp/mcp v0.0.0-20260828100356-2d6f44b51e9d + github.com/basecamp/mcp v0.0.0-20261118214004-663b2e5d2836 github.com/charmbracelet/huh v1.0.0 github.com/charmbracelet/lipgloss v1.1.0 github.com/charmbracelet/x/term v0.2.2 github.com/hashicorp/go-version v1.9.0 github.com/itchyny/gojq v0.12.20 github.com/mattn/go-isatty v0.0.24 - github.com/modelcontextprotocol/go-sdk v1.8.0 + github.com/modelcontextprotocol/go-sdk v1.8.1-0.20261014132652-7c486efa8223 github.com/muesli/termenv v0.16.0 github.com/spf13/cobra v1.10.2 github.com/spf13/pflag v1.1.0 diff --git a/go.sum b/go.sum index e850118..c3406c2 100644 --- a/go.sum +++ b/go.sum @@ -10,8 +10,8 @@ github.com/basecamp/cli v0.2.1 h1:8GyehPVtsTXla0oOPu4QgXRjwwzJ99prlByvyi+0HRQ= github.com/basecamp/cli v0.2.1/go.mod h1:p8tt/DatJ2LAzWO6N6tNfV8x3gF5T3IxDTo+U8FfWPo= github.com/basecamp/fizzy-sdk/go v0.3.0 h1:WpaFl4xV0lS7BZ+Sf09ov4Yl5jRqtoeZqUUM+KCRk0Y= github.com/basecamp/fizzy-sdk/go v0.3.0/go.mod h1:/rdkaGOCbFmpjpK++VxzCzDagm03I62VYyU6YwpqZ2s= -github.com/basecamp/mcp v0.0.0-20260828100356-2d6f44b51e9d h1:zEQVGq1x1nhKMZ2TudFAcSJ32CHT8richI1vQakIKz4= -github.com/basecamp/mcp v0.0.0-20260828100356-2d6f44b51e9d/go.mod h1:Ee2c/q1/pg+5T5741PIuA3s6VJMQC7I0XBNXIHIujzA= +github.com/basecamp/mcp v0.0.0-20261118214004-663b2e5d2836 h1:ND4te8b+HVFFrgcm7+n8P83MKKPqBpIyoJ63tT9liRU= +github.com/basecamp/mcp v0.0.0-20261118214004-663b2e5d2836/go.mod h1:K3sgTH90CIR6Ed0XPnivIBqNIpw6aeOlcXThBrZ+2gc= github.com/catppuccin/go v0.3.0 h1:d+0/YicIq+hSTo5oPuRi5kOpqkVA5tAsU6dNhvRu+aY= github.com/catppuccin/go v0.3.0/go.mod h1:8IHJuMGaUUjQM82qBrGNBv7LFq6JI3NnQCF6MOlZjpc= github.com/charmbracelet/bubbles v0.21.1-0.20250623103423-23b8fd6302d7 h1:JFgG/xnwFfbezlUnFMJy0nusZvytYysV4SCS2cYbvws= @@ -79,8 +79,8 @@ github.com/mattn/go-runewidth v0.0.31 h1:1oCV4ReTlosDBc6rYRw5cL8S/4y8iv5oRl4SJ5I github.com/mattn/go-runewidth v0.0.31/go.mod h1:3qAiGCV4Koz/yuveO58qUefmUTRm8r0IGEXZ9jeHp/8= github.com/mitchellh/hashstructure/v2 v2.0.2 h1:vGKWl0YJqUNxE8d+h8f6NJLcCJrgbhC4NcD46KavDd4= github.com/mitchellh/hashstructure/v2 v2.0.2/go.mod h1:MG3aRVU/N29oo/V/IhBX8GR/zz4kQkprJgF2EVszyDE= -github.com/modelcontextprotocol/go-sdk v1.8.0 h1:KIvahhYqwtbeniWVPs3TcXEA7b8jEtwfBpOTAI+Urx4= -github.com/modelcontextprotocol/go-sdk v1.8.0/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts= +github.com/modelcontextprotocol/go-sdk v1.8.1-0.20261014132652-7c486efa8223 h1:THyv0oM2i7h3ezGwwXWCOqwsh/C2rUTabh+ukQCiClE= +github.com/modelcontextprotocol/go-sdk v1.8.1-0.20261014132652-7c486efa8223/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts= github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI= github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6/go.mod h1:CJlz5H+gyd6CUWT45Oy4q24RdLyn7Md9Vj2/ldJBSIo= github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA= diff --git a/internal/mcpserver/catalog/PROVENANCE.json b/internal/mcpserver/catalog/PROVENANCE.json index 7d05d76..6abe0aa 100644 --- a/internal/mcpserver/catalog/PROVENANCE.json +++ b/internal/mcpserver/catalog/PROVENANCE.json @@ -1,6 +1,6 @@ { "source": "github.com/basecamp/fizzy-mcp-server", - "commit": "4bef95299bde8fd6b88c5627d8fa6b4529abdef7", + "commit": "724955bfb1c9334b9aeedb08dc077b9df8d5d0f3", "path": "internal/catalog", "files": ["catalog.go", "domains.go", "testdata/catalog_snapshot.txt"], "synced_by": "scripts/sync-mcp-catalog.sh" diff --git a/internal/mcpserver/catalog/catalog.go b/internal/mcpserver/catalog/catalog.go index cf37484..5271688 100644 --- a/internal/mcpserver/catalog/catalog.go +++ b/internal/mcpserver/catalog/catalog.go @@ -15,9 +15,16 @@ import ( "sort" "strings" + toolkit "github.com/basecamp/mcp/catalog" "github.com/basecamp/mcp/gateway" ) +// WriteSemantics is the toolkit catalog's behavior-model vocabulary for how +// the server interprets a write's request body — aliased rather than +// redefined, so the hand-written catalog speaks exactly the vocabulary the +// fizzy-sdk model exports will use when generation replaces this package. +type WriteSemantics = toolkit.WriteSemantics + // Param is one path or query parameter of an operation. type Param struct { Name string `json:"name"` @@ -36,10 +43,25 @@ type Operation struct { Summary string `json:"summary"` Doc string `json:"doc,omitempty"` ReadOnly bool `json:"readonly"` + // Idempotent marks operations safe to repeat: every read (enforced by + // validate), plus writes whose repeat provably converges — PUT-style + // updates and the documented already-published publish. + Idempotent bool `json:"idempotent"` + // Destructive marks operations that delete or irreversibly alter data. + // Curation starts from parity with the toolkit's BridgeDestructive + // action-name classifier; hand-reviewed exceptions are pinned by the + // drift test in catalog_test.go. + Destructive bool `json:"destructive"` // Paginated marks endpoints that page via the Link header; responses // carry next_page when more results exist, fetched by passing page. - Paginated bool `json:"paginated,omitempty"` - Params []Param `json:"params,omitempty"` + Paginated bool `json:"paginated,omitempty"` + // WriteSemantics declares how the server treats the request body on + // write — most importantly whether omitted fields are cleared. Fizzy's + // API docs declare no such semantics today, so no operation sets it; + // the field keeps describe payloads shape-compatible with the toolkit + // catalog until fizzy-sdk model exports carry the real values. + WriteSemantics *WriteSemantics `json:"write_semantics,omitempty"` + Params []Param `json:"params,omitempty"` // Body is the JSON Schema of the request body's properties. The handler // nests supplied fields under BodyKey when set ({"card": {...}}). Body map[string]any `json:"body,omitempty"` @@ -54,6 +76,7 @@ type Operation struct { type Domain struct { Key string // short name, e.g. "cards" Tool string // MCP tool name, e.g. "fizzy_cards" + Title string // human-readable tool title, e.g. "Fizzy Cards" Blurb string // first line of the tool description Operations []*Operation // sorted by action name } @@ -66,6 +89,9 @@ func (d *Domain) Name() string { return d.Key } // ToolName returns the MCP tool name, e.g. "fizzy_cards". func (d *Domain) ToolName() string { return d.Tool } +// ToolTitle returns the human-readable tool title, e.g. "Fizzy Cards". +func (d *Domain) ToolTitle() string { return d.Title } + // Find returns the dispatch surface of the operation registered under the // given action name. func (d *Domain) Find(action string) (gateway.Operation, bool) { @@ -79,7 +105,7 @@ func (d *Domain) Find(action string) (gateway.Operation, bool) { // FilterReadOnly returns a copy of the domain containing only read-only // operations, reporting false when none remain. func (d *Domain) FilterReadOnly() (gateway.Domain, bool) { - filtered := &Domain{Key: d.Key, Tool: d.Tool, Blurb: d.Blurb} + filtered := &Domain{Key: d.Key, Tool: d.Tool, Title: d.Title, Blurb: d.Blurb} for _, op := range d.Operations { if op.ReadOnly { filtered.Operations = append(filtered.Operations, op) @@ -111,6 +137,29 @@ func (d *Domain) AllReadOnly() bool { return true } +// AllIdempotent reports whether repeating any call is safe: every write +// operation is idempotent. Read operations count as idempotent regardless, +// so an all-read domain is vacuously idempotent. +func (d *Domain) AllIdempotent() bool { + for _, op := range d.Operations { + if !op.ReadOnly && !op.Idempotent { + return false + } + } + return true +} + +// AnyDestructive reports whether any operation deletes or irreversibly +// alters data. +func (d *Domain) AnyDestructive() bool { + for _, op := range d.Operations { + if op.Destructive { + return true + } + } + return false +} + // Description renders the tool description: the domain blurb, the gateway // calling convention, and a one-line summary per action. Matches the // toolkit catalog's generated rendering. @@ -125,6 +174,9 @@ func (d *Domain) Description() string { if op.ReadOnly { notes = append(notes, "RO") } + if op.Destructive { + notes = append(notes, "destructive") + } if op.Paginated { notes = append(notes, "paginated") } @@ -170,9 +222,10 @@ func (d *Domain) Describe(action string) (any, error) { summaries := make([]map[string]any, 0, len(d.Operations)) for _, op := range d.Operations { summaries = append(summaries, map[string]any{ - "action": op.Action, - "summary": op.Summary, - "readonly": op.ReadOnly, + "action": op.Action, + "summary": op.Summary, + "readonly": op.ReadOnly, + "destructive": op.Destructive, }) } return map[string]any{"domain": d.Key, "actions": summaries}, nil @@ -222,6 +275,9 @@ func GatewayDomains(domains []*Domain) []gateway.Domain { } func validate(d *Domain) error { + if strings.TrimSpace(d.Title) == "" { + return fmt.Errorf("no title (connector directories require a title on every tool)") + } seen := map[string]bool{gateway.DescribeAction: true} sorted := sort.SliceIsSorted(d.Operations, func(i, j int) bool { return d.Operations[i].Action < d.Operations[j].Action @@ -237,6 +293,14 @@ func validate(d *Domain) error { if op.ReadOnly != (op.Method == "GET") { return fmt.Errorf("action %q: readonly must mirror the method (GET and only GET reads)", op.Action) } + if op.ReadOnly && !op.Idempotent { + return fmt.Errorf("action %q: read-only actions are idempotent by nature", op.Action) + } + if op.ReadOnly && op.Destructive { + // Contradictory annotations resolve differently across MCP + // clients; refuse the shape rather than emit it. + return fmt.Errorf("action %q: declared both readonly and destructive", op.Action) + } if err := validateParams(op); err != nil { return fmt.Errorf("action %q: %w", op.Action, err) } diff --git a/internal/mcpserver/catalog/catalog_test.go b/internal/mcpserver/catalog/catalog_test.go index 221b873..befe70e 100644 --- a/internal/mcpserver/catalog/catalog_test.go +++ b/internal/mcpserver/catalog/catalog_test.go @@ -13,6 +13,7 @@ import ( "strings" "testing" + toolkit "github.com/basecamp/mcp/catalog" "github.com/basecamp/mcp/mcptest" ) @@ -59,6 +60,39 @@ func TestOnlyIdentityIsUnscoped(t *testing.T) { } } +// TestDestructiveMatchesBridgeClassifier pins the destructive curation to +// the toolkit's action-name bridge classifier — the same heuristic the +// generated catalogs fall back on until SDK behavior models carry the +// trait — so the hand-written catalog can't silently drift from the +// convention. Divergence is deliberate and documented, or it's an error. +func TestDestructiveMatchesBridgeClassifier(t *testing.T) { + // Hand-reviewed exceptions: destructive despite a name the prefix + // heuristic misses. Each entry documents why. + exceptions := map[string]string{ + // Unpublishing destroys the publication and its secure-token key; + // republishing mints a new URL, so the old public link is + // irrecoverable. + "boards/unpublish_board": "invalidates the public link for good", + } + for _, d := range load(t) { + for _, op := range d.Operations { + key := d.Key + "/" + op.Action + if why, ok := exceptions[key]; ok { + if !op.Destructive { + t.Errorf("%s: exception (%s) must set Destructive", key, why) + } + if toolkit.BridgeDestructive(op.Action) { + t.Errorf("%s: the bridge now classifies this action; drop the exception", key) + } + continue + } + if got, want := op.Destructive, toolkit.BridgeDestructive(op.Action); got != want { + t.Errorf("%s: Destructive = %v drifts from the bridge classifier (%v) without a documented exception", key, got, want) + } + } + } +} + func TestPaginatedOperationsTakePage(t *testing.T) { for _, d := range load(t) { for _, op := range d.Operations { @@ -106,7 +140,7 @@ func TestValidateRejectsCurationMistakes(t *testing.T) { }{ { "unsorted operations", - &Domain{Key: "x", Tool: "fizzy_x", Operations: []*Operation{ + &Domain{Key: "x", Tool: "fizzy_x", Title: "X", Operations: []*Operation{ {Action: "b", Method: "GET", Path: "/b", ReadOnly: true}, {Action: "a", Method: "GET", Path: "/a", ReadOnly: true}, }}, @@ -114,36 +148,57 @@ func TestValidateRejectsCurationMistakes(t *testing.T) { }, { "reserved describe action", - &Domain{Key: "x", Tool: "fizzy_x", Operations: []*Operation{ + &Domain{Key: "x", Tool: "fizzy_x", Title: "X", Operations: []*Operation{ {Action: "describe", Method: "GET", Path: "/x", ReadOnly: true}, }}, "reserved", }, { "write marked read-only", - &Domain{Key: "x", Tool: "fizzy_x", Operations: []*Operation{ + &Domain{Key: "x", Tool: "fizzy_x", Title: "X", Operations: []*Operation{ {Action: "a", Method: "POST", Path: "/a", ReadOnly: true}, }}, "readonly must mirror the method", }, { "path token without param", - &Domain{Key: "x", Tool: "fizzy_x", Operations: []*Operation{ - {Action: "a", Method: "GET", Path: "/a/{id}", ReadOnly: true}, + &Domain{Key: "x", Tool: "fizzy_x", Title: "X", Operations: []*Operation{ + {Action: "a", Method: "GET", Path: "/a/{id}", ReadOnly: true, Idempotent: true}, }}, "no matching path param", }, { "path param not in path", - &Domain{Key: "x", Tool: "fizzy_x", Operations: []*Operation{ - {Action: "a", Method: "GET", Path: "/a", ReadOnly: true, + &Domain{Key: "x", Tool: "fizzy_x", Title: "X", Operations: []*Operation{ + {Action: "a", Method: "GET", Path: "/a", ReadOnly: true, Idempotent: true, Params: []Param{{Name: "id", In: "path", Required: true, Schema: str("x")}}}, }}, "does not appear in path", }, { - "body_key without body", + "missing title", &Domain{Key: "x", Tool: "fizzy_x", Operations: []*Operation{ + {Action: "a", Method: "GET", Path: "/a", ReadOnly: true, Idempotent: true}, + }}, + "no title", + }, + { + "read not marked idempotent", + &Domain{Key: "x", Tool: "fizzy_x", Title: "X", Operations: []*Operation{ + {Action: "a", Method: "GET", Path: "/a", ReadOnly: true}, + }}, + "idempotent by nature", + }, + { + "read marked destructive", + &Domain{Key: "x", Tool: "fizzy_x", Title: "X", Operations: []*Operation{ + {Action: "a", Method: "GET", Path: "/a", ReadOnly: true, Idempotent: true, Destructive: true}, + }}, + "both readonly and destructive", + }, + { + "body_key without body", + &Domain{Key: "x", Tool: "fizzy_x", Title: "X", Operations: []*Operation{ {Action: "a", Method: "POST", Path: "/a", BodyKey: "thing"}, }}, "without a body schema", diff --git a/internal/mcpserver/catalog/domains.go b/internal/mcpserver/catalog/domains.go index 5542813..c9f7fac 100644 --- a/internal/mcpserver/catalog/domains.go +++ b/internal/mcpserver/catalog/domains.go @@ -46,14 +46,27 @@ var cardNumber = pathParam("card_number", "The card number (the number in the ca // Domains is the hand-written v1 catalog, in tool display order. Each // operation mirrors one endpoint in Fizzy's public API docs (docs/api in // the fizzy repo); operations within a domain are sorted by action name. +// +// Annotation curation, pending fizzy-sdk model exports: +// - Destructive starts from parity with the toolkit's BridgeDestructive +// action-name classifier (delete_* here); hand-reviewed exceptions carry +// a comment and are pinned by the drift test. The DELETE-method state +// toggles (reopen_card, untriage_card, unmark_golden, unwatch_card) +// reverse cleanly, so they stay clean; unpublish_board is the one +// exception, documented inline. +// - Idempotent is true on every read (enforced by validate) and on writes +// whose repeat provably converges: PUT-style updates, and publish_board, +// which the API docs define as returning the existing publication when +// already published. Toggles and the other POSTs stay false. var Domains = []*Domain{ { Key: "identity", Tool: "fizzy_identity", + Title: "Fizzy Identity", Blurb: "Who you are on Fizzy: the accounts your token can reach and your user in each. Call this first when the account slug is unknown.", Operations: []*Operation{ { - Action: "get_identity", Method: "GET", Path: "/my/identity", ReadOnly: true, Unscoped: true, + Action: "get_identity", Method: "GET", Path: "/my/identity", ReadOnly: true, Idempotent: true, Unscoped: true, Summary: "List the accounts the token can access, with your user record in each", Doc: "Each account carries a slug naming it in API paths. Account-scoped actions run against the account the server is configured for; this action shows every account the token can reach.", }, @@ -62,6 +75,7 @@ var Domains = []*Domain{ { Key: "boards", Tool: "fizzy_boards", + Title: "Fizzy Boards", Blurb: "Fizzy boards: the kanban boards cards live on, who can access them, and public publication.", Operations: []*Operation{ { @@ -75,37 +89,42 @@ var Domains = []*Domain{ }, "name"), }, { - Action: "delete_board", Method: "DELETE", Path: "/boards/{board_id}", + Action: "delete_board", Method: "DELETE", Path: "/boards/{board_id}", Destructive: true, Summary: "Delete a board (board administrators only)", Params: []Param{pathParam("board_id", "The board ID")}, }, { - Action: "get_board", Method: "GET", Path: "/boards/{board_id}", ReadOnly: true, + Action: "get_board", Method: "GET", Path: "/boards/{board_id}", ReadOnly: true, Idempotent: true, Summary: "Get one board", Params: []Param{pathParam("board_id", "The board ID")}, }, { - Action: "list_accesses", Method: "GET", Path: "/boards/{board_id}/accesses", ReadOnly: true, Paginated: true, + Action: "list_accesses", Method: "GET", Path: "/boards/{board_id}/accesses", ReadOnly: true, Idempotent: true, Paginated: true, Summary: "List account users with their access and involvement for a board", Params: []Param{pathParam("board_id", "The board ID"), pageParam()}, }, { - Action: "list_boards", Method: "GET", Path: "/boards", ReadOnly: true, Paginated: true, + Action: "list_boards", Method: "GET", Path: "/boards", ReadOnly: true, Idempotent: true, Paginated: true, Summary: "List the boards you have access to", Params: []Param{pageParam()}, }, { - Action: "publish_board", Method: "POST", Path: "/boards/{board_id}/publication", + // Idempotent per the API docs: publishing an already-published + // board returns the existing publication. + Action: "publish_board", Method: "POST", Path: "/boards/{board_id}/publication", Idempotent: true, Summary: "Publish a board to a shareable public link (administrators only)", Params: []Param{pathParam("board_id", "The board ID")}, }, { - Action: "unpublish_board", Method: "DELETE", Path: "/boards/{board_id}/publication", + // Destructive beyond what the name-prefix bridge sees: unpublishing + // destroys the publication and its secure-token key, so republishing + // mints a new URL — the old public link is gone for good. + Action: "unpublish_board", Method: "DELETE", Path: "/boards/{board_id}/publication", Destructive: true, Summary: "Unpublish a board, removing public access (administrators only)", Params: []Param{pathParam("board_id", "The board ID")}, }, { - Action: "update_board", Method: "PUT", Path: "/boards/{board_id}", BodyKey: "board", + Action: "update_board", Method: "PUT", Path: "/boards/{board_id}", Idempotent: true, BodyKey: "board", Summary: "Update a board (administrators only)", Params: []Param{pathParam("board_id", "The board ID")}, Body: object(map[string]any{ @@ -121,6 +140,7 @@ var Domains = []*Domain{ { Key: "columns", Tool: "fizzy_columns", + Title: "Fizzy Columns", Blurb: "Workflow columns on a Fizzy board. Cards in Maybe?, Not Now, or Done live outside columns; move cards between columns with the cards tool's triage_card.", Operations: []*Operation{ { @@ -133,27 +153,27 @@ var Domains = []*Domain{ }, "name"), }, { - Action: "delete_column", Method: "DELETE", Path: "/boards/{board_id}/columns/{column_id}", + Action: "delete_column", Method: "DELETE", Path: "/boards/{board_id}/columns/{column_id}", Destructive: true, Summary: "Delete a column", Params: []Param{pathParam("board_id", "The board ID"), pathParam("column_id", "The column ID")}, }, { - Action: "get_column", Method: "GET", Path: "/boards/{board_id}/columns/{column_id}", ReadOnly: true, + Action: "get_column", Method: "GET", Path: "/boards/{board_id}/columns/{column_id}", ReadOnly: true, Idempotent: true, Summary: "Get one column", Params: []Param{pathParam("board_id", "The board ID"), pathParam("column_id", "The column ID")}, }, { - Action: "list_cards", Method: "GET", Path: "/boards/{board_id}/columns/{column_id}/cards", ReadOnly: true, Paginated: true, + Action: "list_cards", Method: "GET", Path: "/boards/{board_id}/columns/{column_id}/cards", ReadOnly: true, Idempotent: true, Paginated: true, Summary: "List the open cards in a column", Params: []Param{pathParam("board_id", "The board ID"), pathParam("column_id", "The column ID"), pageParam()}, }, { - Action: "list_columns", Method: "GET", Path: "/boards/{board_id}/columns", ReadOnly: true, + Action: "list_columns", Method: "GET", Path: "/boards/{board_id}/columns", ReadOnly: true, Idempotent: true, Summary: "List a board's columns", Params: []Param{pathParam("board_id", "The board ID")}, }, { - Action: "update_column", Method: "PUT", Path: "/boards/{board_id}/columns/{column_id}", BodyKey: "column", + Action: "update_column", Method: "PUT", Path: "/boards/{board_id}/columns/{column_id}", Idempotent: true, BodyKey: "column", Summary: "Rename or recolor a column", Params: []Param{pathParam("board_id", "The board ID"), pathParam("column_id", "The column ID")}, Body: object(map[string]any{ @@ -166,6 +186,7 @@ var Domains = []*Domain{ { Key: "cards", Tool: "fizzy_cards", + Title: "Fizzy Cards", Blurb: "Fizzy cards: create, find, and update cards; close and reopen; move between columns (triage), boards, and Not Now; tag, assign, watch, and mark golden.", Operations: []*Operation{ { @@ -185,17 +206,17 @@ var Domains = []*Domain{ }, "title"), }, { - Action: "delete_card", Method: "DELETE", Path: "/cards/{card_number}", + Action: "delete_card", Method: "DELETE", Path: "/cards/{card_number}", Destructive: true, Summary: "Delete a card (creator or board administrators only)", Params: []Param{cardNumber}, }, { - Action: "get_card", Method: "GET", Path: "/cards/{card_number}", ReadOnly: true, + Action: "get_card", Method: "GET", Path: "/cards/{card_number}", ReadOnly: true, Idempotent: true, Summary: "Get one card with its board, column, assignees, tags, and steps", Params: []Param{cardNumber}, }, { - Action: "list_cards", Method: "GET", Path: "/cards", ReadOnly: true, Paginated: true, + Action: "list_cards", Method: "GET", Path: "/cards", ReadOnly: true, Idempotent: true, Paginated: true, Summary: "List cards you have access to, filtered by board, column, tag, assignee, state, or search terms", Params: []Param{ queryParam("assignee_ids", "Filter by assignee user ID(s)", strArray("Assignee user IDs")), @@ -220,7 +241,7 @@ var Domains = []*Domain{ Params: []Param{cardNumber}, }, { - Action: "move_card", Method: "PUT", Path: "/cards/{card_number}/board", + Action: "move_card", Method: "PUT", Path: "/cards/{card_number}/board", Idempotent: true, Summary: "Move a card to a different board", Params: []Param{cardNumber}, Body: object(map[string]any{ @@ -277,7 +298,7 @@ var Domains = []*Domain{ Params: []Param{cardNumber}, }, { - Action: "update_card", Method: "PUT", Path: "/cards/{card_number}", BodyKey: "card", + Action: "update_card", Method: "PUT", Path: "/cards/{card_number}", Idempotent: true, BodyKey: "card", Summary: "Update a card's title, description, status, or tags", Params: []Param{cardNumber}, Body: object(map[string]any{ @@ -297,6 +318,7 @@ var Domains = []*Domain{ { Key: "comments", Tool: "fizzy_comments", + Title: "Fizzy Comments", Blurb: "Comments on Fizzy cards, chronological. Bodies support rich text.", Operations: []*Operation{ { @@ -308,22 +330,22 @@ var Domains = []*Domain{ }, "body"), }, { - Action: "delete_comment", Method: "DELETE", Path: "/cards/{card_number}/comments/{comment_id}", + Action: "delete_comment", Method: "DELETE", Path: "/cards/{card_number}/comments/{comment_id}", Destructive: true, Summary: "Delete a comment (comment creator only)", Params: []Param{cardNumber, pathParam("comment_id", "The comment ID")}, }, { - Action: "get_comment", Method: "GET", Path: "/cards/{card_number}/comments/{comment_id}", ReadOnly: true, + Action: "get_comment", Method: "GET", Path: "/cards/{card_number}/comments/{comment_id}", ReadOnly: true, Idempotent: true, Summary: "Get one comment", Params: []Param{cardNumber, pathParam("comment_id", "The comment ID")}, }, { - Action: "list_comments", Method: "GET", Path: "/cards/{card_number}/comments", ReadOnly: true, Paginated: true, + Action: "list_comments", Method: "GET", Path: "/cards/{card_number}/comments", ReadOnly: true, Idempotent: true, Paginated: true, Summary: "List a card's comments, oldest first", Params: []Param{cardNumber, pageParam()}, }, { - Action: "update_comment", Method: "PUT", Path: "/cards/{card_number}/comments/{comment_id}", BodyKey: "comment", + Action: "update_comment", Method: "PUT", Path: "/cards/{card_number}/comments/{comment_id}", Idempotent: true, BodyKey: "comment", Summary: "Update a comment (comment creator only)", Params: []Param{cardNumber, pathParam("comment_id", "The comment ID")}, Body: object(map[string]any{ @@ -335,6 +357,7 @@ var Domains = []*Domain{ { Key: "steps", Tool: "fizzy_steps", + Title: "Fizzy Steps", Blurb: "Steps: the checklist items on a Fizzy card.", Operations: []*Operation{ { @@ -347,22 +370,22 @@ var Domains = []*Domain{ }, "content"), }, { - Action: "delete_step", Method: "DELETE", Path: "/cards/{card_number}/steps/{step_id}", + Action: "delete_step", Method: "DELETE", Path: "/cards/{card_number}/steps/{step_id}", Destructive: true, Summary: "Delete a step", Params: []Param{cardNumber, pathParam("step_id", "The step ID")}, }, { - Action: "get_step", Method: "GET", Path: "/cards/{card_number}/steps/{step_id}", ReadOnly: true, + Action: "get_step", Method: "GET", Path: "/cards/{card_number}/steps/{step_id}", ReadOnly: true, Idempotent: true, Summary: "Get one step", Params: []Param{cardNumber, pathParam("step_id", "The step ID")}, }, { - Action: "list_steps", Method: "GET", Path: "/cards/{card_number}/steps", ReadOnly: true, + Action: "list_steps", Method: "GET", Path: "/cards/{card_number}/steps", ReadOnly: true, Idempotent: true, Summary: "List a card's steps", Params: []Param{cardNumber}, }, { - Action: "update_step", Method: "PUT", Path: "/cards/{card_number}/steps/{step_id}", BodyKey: "step", + Action: "update_step", Method: "PUT", Path: "/cards/{card_number}/steps/{step_id}", Idempotent: true, BodyKey: "step", Summary: "Edit a step or toggle its completion", Params: []Param{cardNumber, pathParam("step_id", "The step ID")}, Body: object(map[string]any{ @@ -375,10 +398,11 @@ var Domains = []*Domain{ { Key: "tags", Tool: "fizzy_tags", + Title: "Fizzy Tags", Blurb: "Tags: the labels applied to cards, account-wide. Apply or remove them with the cards tool's toggle_tag.", Operations: []*Operation{ { - Action: "list_tags", Method: "GET", Path: "/tags", ReadOnly: true, Paginated: true, + Action: "list_tags", Method: "GET", Path: "/tags", ReadOnly: true, Idempotent: true, Paginated: true, Summary: "List the account's tags, alphabetically", Params: []Param{pageParam()}, }, @@ -387,15 +411,16 @@ var Domains = []*Domain{ { Key: "users", Tool: "fizzy_users", + Title: "Fizzy Users", Blurb: "Users: the people in the Fizzy account. Assign them to cards with the cards tool's toggle_assignment.", Operations: []*Operation{ { - Action: "get_user", Method: "GET", Path: "/users/{user_id}", ReadOnly: true, + Action: "get_user", Method: "GET", Path: "/users/{user_id}", ReadOnly: true, Idempotent: true, Summary: "Get one user", Params: []Param{pathParam("user_id", "The user ID")}, }, { - Action: "list_users", Method: "GET", Path: "/users", ReadOnly: true, Paginated: true, + Action: "list_users", Method: "GET", Path: "/users", ReadOnly: true, Idempotent: true, Paginated: true, Summary: "List the account's active users", Params: []Param{pageParam()}, }, diff --git a/internal/mcpserver/catalog/testdata/catalog_snapshot.txt b/internal/mcpserver/catalog/testdata/catalog_snapshot.txt index f54073c..3e49aff 100644 --- a/internal/mcpserver/catalog/testdata/catalog_snapshot.txt +++ b/internal/mcpserver/catalog/testdata/catalog_snapshot.txt @@ -35,6 +35,8 @@ ACTIONS (RO = read-only): "summary": "List the accounts the token can access, with your user record in each", "doc": "Each account carries a slug naming it in API paths. Account-scoped actions run against the account the server is configured for; this action shows every account the token can reach.", "readonly": true, + "idempotent": true, + "destructive": false, "unscoped": true } ==== TOOL fizzy_boards ==== @@ -45,12 +47,12 @@ Call {"action": "describe", "params": {"action": "NAME"}} for an action's full p ACTIONS (RO = read-only): - create_board: Create a board -- delete_board: Delete a board (board administrators only) +- delete_board (destructive): Delete a board (board administrators only) - get_board (RO): Get one board - list_accesses (RO, paginated): List account users with their access and involvement for a board - list_boards (RO, paginated): List the boards you have access to - publish_board: Publish a board to a shareable public link (administrators only) -- unpublish_board: Unpublish a board, removing public access (administrators only) +- unpublish_board (destructive): Unpublish a board, removing public access (administrators only) - update_board: Update a board (administrators only) ---- input schema ---- { @@ -87,6 +89,8 @@ ACTIONS (RO = read-only): "path": "/boards", "summary": "Create a board", "readonly": false, + "idempotent": false, + "destructive": false, "body": { "properties": { "all_access": { @@ -120,6 +124,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}", "summary": "Delete a board (board administrators only)", "readonly": false, + "idempotent": false, + "destructive": true, "params": [ { "name": "board_id", @@ -140,6 +146,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}", "summary": "Get one board", "readonly": true, + "idempotent": true, + "destructive": false, "params": [ { "name": "board_id", @@ -160,6 +168,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}/accesses", "summary": "List account users with their access and involvement for a board", "readonly": true, + "idempotent": true, + "destructive": false, "paginated": true, "params": [ { @@ -190,6 +200,8 @@ ACTIONS (RO = read-only): "path": "/boards", "summary": "List the boards you have access to", "readonly": true, + "idempotent": true, + "destructive": false, "paginated": true, "params": [ { @@ -210,6 +222,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}/publication", "summary": "Publish a board to a shareable public link (administrators only)", "readonly": false, + "idempotent": true, + "destructive": false, "params": [ { "name": "board_id", @@ -230,6 +244,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}/publication", "summary": "Unpublish a board, removing public access (administrators only)", "readonly": false, + "idempotent": false, + "destructive": true, "params": [ { "name": "board_id", @@ -250,6 +266,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}", "summary": "Update a board (administrators only)", "readonly": false, + "idempotent": true, + "destructive": false, "params": [ { "name": "board_id", @@ -300,7 +318,7 @@ Call {"action": "describe", "params": {"action": "NAME"}} for an action's full p ACTIONS (RO = read-only): - create_column: Create a column on a board -- delete_column: Delete a column +- delete_column (destructive): Delete a column - get_column (RO): Get one column - list_cards (RO, paginated): List the open cards in a column - list_columns (RO): List a board's columns @@ -338,6 +356,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}/columns", "summary": "Create a column on a board", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "board_id", @@ -375,6 +395,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}/columns/{column_id}", "summary": "Delete a column", "readonly": false, + "idempotent": false, + "destructive": true, "params": [ { "name": "board_id", @@ -405,6 +427,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}/columns/{column_id}", "summary": "Get one column", "readonly": true, + "idempotent": true, + "destructive": false, "params": [ { "name": "board_id", @@ -435,6 +459,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}/columns/{column_id}/cards", "summary": "List the open cards in a column", "readonly": true, + "idempotent": true, + "destructive": false, "paginated": true, "params": [ { @@ -475,6 +501,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}/columns", "summary": "List a board's columns", "readonly": true, + "idempotent": true, + "destructive": false, "params": [ { "name": "board_id", @@ -495,6 +523,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}/columns/{column_id}", "summary": "Rename or recolor a column", "readonly": false, + "idempotent": true, + "destructive": false, "params": [ { "name": "board_id", @@ -541,7 +571,7 @@ Call {"action": "describe", "params": {"action": "NAME"}} for an action's full p ACTIONS (RO = read-only): - close_card: Close a card (move it to Done) - create_card: Create a card on a board (new cards start in Maybe? triage) -- delete_card: Delete a card (creator or board administrators only) +- delete_card (destructive): Delete a card (creator or board administrators only) - get_card (RO): Get one card with its board, column, assignees, tags, and steps - list_cards (RO, paginated): List cards you have access to, filtered by board, column, tag, assignee, state, or search terms - mark_golden: Mark a card as golden @@ -600,6 +630,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/closure", "summary": "Close a card (move it to Done)", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -620,6 +652,8 @@ ACTIONS (RO = read-only): "path": "/boards/{board_id}/cards", "summary": "Create a card on a board (new cards start in Maybe? triage)", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "board_id", @@ -672,6 +706,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}", "summary": "Delete a card (creator or board administrators only)", "readonly": false, + "idempotent": false, + "destructive": true, "params": [ { "name": "card_number", @@ -692,6 +728,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}", "summary": "Get one card with its board, column, assignees, tags, and steps", "readonly": true, + "idempotent": true, + "destructive": false, "params": [ { "name": "card_number", @@ -712,6 +750,8 @@ ACTIONS (RO = read-only): "path": "/cards", "summary": "List cards you have access to, filtered by board, column, tag, assignee, state, or search terms", "readonly": true, + "idempotent": true, + "destructive": false, "paginated": true, "params": [ { @@ -910,6 +950,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/goldness", "summary": "Mark a card as golden", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -930,6 +972,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/board", "summary": "Move a card to a different board", "readonly": false, + "idempotent": true, + "destructive": false, "params": [ { "name": "card_number", @@ -962,6 +1006,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/not_now", "summary": "Move a card to Not Now", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -982,6 +1028,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/closure", "summary": "Reopen a closed card", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -1002,6 +1050,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/assignments", "summary": "Toggle assignment of a user to/from a card", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -1034,6 +1084,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/taggings", "summary": "Toggle a tag on or off for a card, creating the tag if needed", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -1066,6 +1118,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/triage", "summary": "Move a card into a workflow column", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -1098,6 +1152,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/goldness", "summary": "Remove golden status from a card", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -1118,6 +1174,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/triage", "summary": "Send a card back to triage (Maybe?)", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -1138,6 +1196,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/watch", "summary": "Unsubscribe from notifications for a card", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -1158,6 +1218,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}", "summary": "Update a card's title, description, status, or tags", "readonly": false, + "idempotent": true, + "destructive": false, "params": [ { "name": "card_number", @@ -1207,6 +1269,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/watch", "summary": "Subscribe to notifications for a card", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -1228,7 +1292,7 @@ Call {"action": "describe", "params": {"action": "NAME"}} for an action's full p ACTIONS (RO = read-only): - create_comment: Comment on a card -- delete_comment: Delete a comment (comment creator only) +- delete_comment (destructive): Delete a comment (comment creator only) - get_comment (RO): Get one comment - list_comments (RO, paginated): List a card's comments, oldest first - update_comment: Update a comment (comment creator only) @@ -1264,6 +1328,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/comments", "summary": "Comment on a card", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -1297,6 +1363,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/comments/{comment_id}", "summary": "Delete a comment (comment creator only)", "readonly": false, + "idempotent": false, + "destructive": true, "params": [ { "name": "card_number", @@ -1327,6 +1395,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/comments/{comment_id}", "summary": "Get one comment", "readonly": true, + "idempotent": true, + "destructive": false, "params": [ { "name": "card_number", @@ -1357,6 +1427,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/comments", "summary": "List a card's comments, oldest first", "readonly": true, + "idempotent": true, + "destructive": false, "paginated": true, "params": [ { @@ -1387,6 +1459,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/comments/{comment_id}", "summary": "Update a comment (comment creator only)", "readonly": false, + "idempotent": true, + "destructive": false, "params": [ { "name": "card_number", @@ -1431,7 +1505,7 @@ Call {"action": "describe", "params": {"action": "NAME"}} for an action's full p ACTIONS (RO = read-only): - create_step: Add a step to a card -- delete_step: Delete a step +- delete_step (destructive): Delete a step - get_step (RO): Get one step - list_steps (RO): List a card's steps - update_step: Edit a step or toggle its completion @@ -1467,6 +1541,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/steps", "summary": "Add a step to a card", "readonly": false, + "idempotent": false, + "destructive": false, "params": [ { "name": "card_number", @@ -1504,6 +1580,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/steps/{step_id}", "summary": "Delete a step", "readonly": false, + "idempotent": false, + "destructive": true, "params": [ { "name": "card_number", @@ -1534,6 +1612,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/steps/{step_id}", "summary": "Get one step", "readonly": true, + "idempotent": true, + "destructive": false, "params": [ { "name": "card_number", @@ -1564,6 +1644,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/steps", "summary": "List a card's steps", "readonly": true, + "idempotent": true, + "destructive": false, "params": [ { "name": "card_number", @@ -1584,6 +1666,8 @@ ACTIONS (RO = read-only): "path": "/cards/{card_number}/steps/{step_id}", "summary": "Edit a step or toggle its completion", "readonly": false, + "idempotent": true, + "destructive": false, "params": [ { "name": "card_number", @@ -1657,6 +1741,8 @@ ACTIONS (RO = read-only): "path": "/tags", "summary": "List the account's tags, alphabetically", "readonly": true, + "idempotent": true, + "destructive": false, "paginated": true, "params": [ { @@ -1708,6 +1794,8 @@ ACTIONS (RO = read-only): "path": "/users/{user_id}", "summary": "Get one user", "readonly": true, + "idempotent": true, + "destructive": false, "params": [ { "name": "user_id", @@ -1728,6 +1816,8 @@ ACTIONS (RO = read-only): "path": "/users", "summary": "List the account's active users", "readonly": true, + "idempotent": true, + "destructive": false, "paginated": true, "params": [ {