feat(codegen): derive idempotentHint + openWorldHint, allow per-action annotation overrides

[johnxie]

Completes the MCP tool-annotation set started in #44 (derived readOnlyHint/destructiveHint, called out there as a hard prerequisite for the Claude Connectors Directory). The codegen now derives all four spec hints per tool and supports explicit per-action overrides.

Derivation table (HTTP method → hints)

Method	readOnlyHint	destructiveHint	idempotentHint	openWorldHint
GET	true	false	true	false
HEAD	true	false	true	false
PUT	false	false	true	false
DELETE	false	true	true	false
POST	false	false	false	false

• idempotentHint follows HTTP semantics (GET/HEAD/PUT/DELETE idempotent, POST not). Per the MCP spec it is only meaningful when readOnlyHint is false — it is emitted uniformly, but the values that matter are on the PUT/DELETE/POST tools.
• openWorldHint: false everywhere: this server talks only to the Taskade API — a closed world.

Per-action overrides

ActionConfig now accepts explicit readOnlyHint / destructiveHint / idempotentHint / openWorldHint; an undefined-checked override beats the derived value (so an explicit false wins too). This makes future exceptions expressible — e.g. a POST like taskComplete is arguably idempotent. No overrides are set in this PR; all generated values are purely derived.

Zero-regression proof (A1)

Scripted comparison of per-tool annotation objects between 24f491b and the regenerated files:

packages/server/src/tools.generated.ts: old=57 new=57 (expected 57) sameNameSet=true
  preexisting annotations changed: 0; tools with unexpected new keys: 0
packages/server/src/tools.v2.generated.ts: old=5 new=5 (expected 5) sameNameSet=true
  preexisting annotations changed: 0; tools with unexpected new keys: 0
A1 PASS

Every pre-existing readOnlyHint/destructiveHint/title value is byte-identical; the only additions per tool are idempotentHint and openWorldHint.

Changeset

Patch bump for @taskade/mcp-openapi-codegen and @taskade/mcp-server: "Generated tools now carry the full MCP annotation set: derived idempotentHint and openWorldHint:false alongside readOnly/destructive hints; per-action overrides supported."

Test plan

• yarn build regenerates both tools.generated.ts (57 tools) and tools.v2.generated.ts (5 tools); working tree clean after commit.
• yarn lint clean.
• yarn test: 19 tests / 4 files pass, including new codegen.test.ts (in-memory OpenAPI doc with one GET/POST/PUT/DELETE; asserts all four derived hints per method, plus override cases including an explicit-false override) (A2).
• A1 comparison script output above.

[changeset-bot]

🦋 Changeset detected

Latest commit: 9652b50

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@taskade/mcp-openapi-codegen	Patch
@taskade/mcp-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[johnxie]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code