Bug: create-a-comment (POST /v1/comments) 400s with missing_version — only op missing Notion-Version param after #320

[derrickshowers]

Summary

create-a-comment (POST /v1/comments) always fails with HTTP 400 missing_version ("Notion-Version header should be defined"). It is the only operation in the bundled OpenAPI spec that is missing its Notion-Version header parameter, so the server sends the request with no version header.

• Package version: @notionhq/notion-mcp-server@2.4.1
• Auth: NOTION_TOKEN (stdio) — but this is auth-independent; it reproduces regardless.

Root cause

Since #320 ("source Notion-Version per operation"), HttpClient.buildDefaultHeaders() derives Notion-Version from each operation's header-parameter default in scripts/notion-openapi.json. That works only if the operation actually declares the parameter.

In the shipped spec, every operation references the shared param except create-a-comment, whose parameters array is empty:

// GET /v1/comments  (retrieve-a-comment) — correct
"parameters": [ /* …query params… */, { "$ref": "#/components/parameters/notionVersion" } ]

// POST /v1/comments (create-a-comment) — BUG: no Notion-Version
"parameters": []

The shared component is present and fine:

"#/components/parameters/notionVersion": {
  "name": "Notion-Version", "in": "header", "required": false,
  "schema": { "type": "string", "default": "2025-09-03" },
  "description": "The Notion API version"
}

I scanned the whole spec: 24 operations, exactly 1 missing the param — POST /v1/comments. Even GET /v1/comments has it, so this looks like an oversight in #320 rather than intentional.

Reproduction

1. Configure the server with any valid integration token.
2. Call API-create-a-comment with a valid parent.page_id + rich_text.
3. Notion responds 400 / code: "missing_version".

(API-patch-block-children, API-retrieve-a-comment, etc. all work — they carry the version.)

Fix

Add the shared param to the create-a-comment operation in scripts/notion-openapi.json:

   "/v1/comments": {
     "post": {
       "operationId": "create-a-comment",
-      "parameters": []
+      "parameters": [
+        { "$ref": "#/components/parameters/notionVersion" }
+      ]

Workaround (for others hitting this)

Set a global version, which buildDefaultHeaders lets win for every operation:

"OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_…\",\"Notion-Version\":\"2025-09-03\"}"