Summarise catalogue listings by default, and document the legacy 1.x release path

[riccardone]

Two unrelated papercuts, both surfaced while shipping the argument-validation fix.

1. Catalogue listings are too large to read

get_command_catalogue returned every command's full description. On a thoroughly documented endpoint that's 47 KB for ~65 commands, which clients spill to a file before a model can read it — for a listing whose only job is to let the caller choose an operation.

Both catalogue tools now truncate each description to 200 characters unless the caller passes detail: "full". Measured against a fixture matching that shape:

mode	size
full	59.9 KB
summary (default)	23.6 KB — 61% smaller

Nothing is lost: get_command_schema / get_query_schema already return one operation's complete text, so the long descriptions are deferred, not discarded.

A character cap, not "first sentence." Real descriptions open with routing metadata — "Source: managing. Schema: approve-absence/1.0. Approves a pending or overdue absence…" — so keeping the first sentence would throw away the part that says what the operation does. The cut lands on a word boundary when one is close enough.

Deliberately conservative elsewhere: short descriptions are untouched, non-description fields are untouched, and the output stays a bare JSON array in both modes, so the response shape is unchanged for anything already parsing it.

It also extends validateToolArgs to reject values outside a declared enum. detail is the first enum on this surface, and a typo'd value silently falling through to the handler's default is exactly the silent-wrong-behaviour that function exists to stop.

2. The legacy 1.x release path was undocumented

Nothing recorded that the pre-rename @behavioralstate/bsp-mcp 1.x line still exists, is maintained off the mcp/v1.7.1 tag, and is released by tagging manually.

That gap has a sharp edge: release-mcp.sh cannot cut a 1.x release, because it requires main — where mcp-server/package.json is @behavioralstate/best-mcp. Tagging mcp/v1.x from main would publish best-mcp at that version, and since CI's npm publish passes no --tag, that moves best-mcp's latest backwards from 2.x.

So the README now states that the tag prefix does not select the package (CI publishes whatever the tagged commit names), documents the manual-tag exception for 1.x, and notes verifying a release by packing the published tarball — dist/ is gitignored yet ships, so the artifact depends on a build having run. Also corrects "two independent artifacts": the table lists three.

Verification

Drove the built stdio server with raw JSON-RPC against a local fake endpoint — 8 checks, all passing: the size reduction, both catalogues summarised, the cap respected, short descriptions untouched, non-description fields surviving, full returning verbatim text, and the invalid enum value rejected rather than silently defaulted. The earlier argument-validation cases still pass unchanged.

No version bump here — scripts/release-mcp.sh does that when cutting the release. Once merged this wants releasing on both lines, since the catalogue size affects bsp-mcp deployments just as much.

🤖 Generated with Claude Code