From c4c9b4d7985ada273f06acd7f8a0e9afd72b7a71 Mon Sep 17 00:00:00 2001 From: Jeremy Daer Date: Wed, 18 Nov 2026 17:12:36 -0800 Subject: [PATCH] Bump the basecamp/mcp toolkit, and sync the catalog that titles its tools Move github.com/basecamp/mcp from the 2026-08-28 pin (2d6f44b) to 663b2e5, which carries the result paging and size-cap middleware and the eval multi-turn mode. go-sdk moves with it to the toolkit's own pin. The toolkit's gateway.Domain grew ToolTitle, AllIdempotent and AnyDestructive, and the gateway now derives every tool's annotations (title, idempotent, destructive, closed world) from them and refuses a domain without a title. The vendored catalog predated that, so it no longer satisfied the interface. Re-sync it with scripts/sync-mcp-catalog.sh from fizzy-mcp-server 724955b, the commit that adopted those annotations there: every domain gets a "Fizzy ..." title, every read and the provably converging writes are idempotent, and the delete_* actions plus unpublish_board are destructive. The snapshot delta is exactly the new "destructive" notes and fields. The sync stops at 724955b rather than the sibling's head. Later catalog changes there (top-level body fields, read-only blurbs) need matching dispatch and server changes here, so they are a port of their own. The CLI's catalog tests take the sibling's matching changes: titled fixtures, the three new validate refusals, and the drift test pinning the destructive curation to the toolkit's bridge classifier. --- go.mod | 4 +- go.sum | 8 +- internal/mcpserver/catalog/PROVENANCE.json | 2 +- internal/mcpserver/catalog/catalog.go | 76 +++++++++++-- internal/mcpserver/catalog/catalog_test.go | 71 ++++++++++-- internal/mcpserver/catalog/domains.go | 83 +++++++++----- .../catalog/testdata/catalog_snapshot.txt | 102 ++++++++++++++++-- 7 files changed, 290 insertions(+), 56 deletions(-) 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": [ {