Add page-as-Markdown tools (retrieve + update)

[ksinder]

Summary

Adds the two page-content-as-Markdown endpoints from the public Notion API, which were missing from the spec and are the highest-value additions for agentic/MCP clients:

Tool	Method	Endpoint
retrieve-page-markdown	GET	/v1/pages/{page_id}/markdown
update-page-markdown	PATCH	/v1/pages/{page_id}/markdown

These read/write page content as enhanced Markdown instead of block JSON — far more token-efficient for LLMs (the README already advertises "editing pages in Markdown"; this makes it literally true via the dedicated endpoints).

update-page-markdown supports replace_content (overwrite whole page), update_content (targeted find-and-replace, up to 100 edits), and the deprecated insert_content / replace_content_range variants.

The version problem & how it's solved

The markdown endpoints require Notion-Version: 2026-03-11, but the rest of the API is on 2025-09-03. A global bump to 2026-03-11 is genuinely breaking (archived→in_trash, append-children after→position, transcription→meeting_notes) and would be a separate migration. Instead, this PR makes Notion-Version per-operation, sourced from the spec:

• HttpClient now applies each operation's Notion-Version header-parameter default as a real request header (resolving $ref'd params). Markdown ops pin 2026-03-11; everything else stays 2025-09-03. An explicitly-configured Notion-Version (via OPENAPI_MCP_HEADERS) still takes precedence.
• proxy.ts no longer hardcodes Notion-Version for the NOTION_TOKEN path — it comes from the spec.
• parser.ts no longer exposes header params as model-visible tool inputs. Previously Notion-Version appeared (inertly) on 21 of 22 tools as schema noise; now 0.

Empirically confirmed openapi-client-axios does not inject header-param defaults on its own, so this wiring is what actually puts the right version on the wire.

Tests

• http-client.headers.test.ts — per-operation version injection + user-override precedence.
• notion-markdown-tools.test.ts — markdown tools generate with correct inputs and no Notion-Version leakage, against the real spec.
• Full suite: 86 passing, build green. Spec diff is purely additive.

Notes for review

• No version bump here (kept independent, like the other feature PRs). This is a new feature and should ship under the next minor (e.g. fold into the 2.4.0 bump in Bump version to v2.4.0 #319, or bump separately).
• Interaction with Per-request Notion token passthrough for HTTP transport #315 (token passthrough): Per-request Notion token passthrough for HTTP transport #315's passthrough sets Notion-Version in the per-request headers, which would suppress the per-op default for markdown. When both land, reconcile by having Per-request Notion token passthrough for HTTP transport #315 omit Notion-Version (same fix applied here to the NOTION_TOKEN path) so the spec drives it.
• Other catalog gaps exist (views, file uploads, comment update/delete, meeting notes, admin API) — intentionally left out to keep the tool surface curated; happy to add any on request.

🤖 Generated with Claude Code

[ksinder]

Added a root-cause fix for the flaky server-based integration tests (was intermittently failing CI with socket hang up / ECONNRESET).

Three real races, now fixed via a shared startTestServer/stopTestServer helper:

1. Request-before-bind — tests issued requests before app.listen() finished binding. Now we await the listening event.
2. Port collisions — random 3000 + rand(1000) ports clashed across vitest's parallel workers. Now we bind to ephemeral port 0 (OS-assigned, guaranteed free).
3. Unawaited teardown — afterEach didn't await server.close(). Now it does.
   Also switched the base URL to 127.0.0.1 to avoid localhost → ::1 IPv4/IPv6 mismatch.

Verified with 5 consecutive local full-suite runs (89/89 each). This touches http-client.integration.test.ts (pre-existing) and the new header test only — no production code change beyond the markdown work.