Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -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=
Expand Down Expand Up @@ -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=
Expand Down
2 changes: 1 addition & 1 deletion internal/mcpserver/catalog/PROVENANCE.json
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
76 changes: 70 additions & 6 deletions internal/mcpserver/catalog/catalog.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"`
Expand All @@ -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"`
Expand All @@ -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
}
Expand All @@ -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) {
Expand All @@ -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)
Expand Down Expand Up @@ -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.
Expand All @@ -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")
}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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)
}
Expand Down
71 changes: 63 additions & 8 deletions internal/mcpserver/catalog/catalog_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import (
"strings"
"testing"

toolkit "github.com/basecamp/mcp/catalog"
"github.com/basecamp/mcp/mcptest"
)

Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -106,44 +140,65 @@ 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},
}},
"sorted",
},
{
"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",
Expand Down
Loading
Loading