fix(mcp): rename wire fields to contract names before dispatch (#3215)

* fix(mcp): rename wire fields to contract names before dispatch

The MCP wire schema (generated from apps/cli operation params) exposes
PARAM_FLAG_OVERRIDES renames such as `commentId` → `id` and
`parentCommentId` → `parentId`. Without an inverse translation at
dispatch time, the contract validator rejects the wire field names
because it expects the canonical contract names — so
`superdoc_comment` actions `delete`/`get`/`update` fail with
`comments.<action> commentId must be a non-empty string` even when the
caller follows the documented schema.

The CLI applies the inverse rename in extractInvokeInput()
(apps/cli/src/lib/invoke-input.ts PARAM_RENAMES). This commit adds the
matching layer for the MCP path: a small `applyParamRenames` helper in
a standalone module, applied in `executeOperation` immediately before
`api.invoke`.

Affected operations: comments.create (parentId → parentCommentId),
comments.patch / comments.delete / comments.get (id → commentId),
getNodeById (id → nodeId).

Includes unit tests for the rename helper.

* review: fix comment count/style and document output-rename asymmetry

- param-renames.ts: fix "Three" → "Five" (5 operations, not 3) and
  replace em-dash per style rule (caio-pizzol review suggestion).
- intent.ts: add AIDEV-NOTE explaining why input renames are not
  inverted on output — canonical names in responses are usable directly,
  so inverting adds complexity for no practical benefit.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* review: clarify output-rename asymmetry is incidental, not deliberate

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Caio Pizzol <97641911+caio-pizzol@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

apps/mcp/src/__tests__/intent-param-renames.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'bun:test';
+import { applyParamRenames } from '../tools/param-renames.js';
+
+describe('applyParamRenames', () => {
+  it('renames id → commentId for comments.delete', () => {
+    expect(applyParamRenames('comments.delete', { id: 'c1' })).toEqual({ commentId: 'c1' });
+  });
+
+  it('renames id → commentId for comments.get', () => {
+    expect(applyParamRenames('comments.get', { id: 'c1' })).toEqual({ commentId: 'c1' });
+  });
+
+  it('renames id → commentId for comments.patch and preserves other fields', () => {
+    expect(applyParamRenames('comments.patch', { id: 'c1', text: 'updated', isInternal: true })).toEqual({
+      commentId: 'c1',
+      text: 'updated',
+      isInternal: true,
+    });
+  });
+
+  it('renames parentId → parentCommentId for comments.create', () => {
+    expect(applyParamRenames('comments.create', { text: 'reply', parentId: 'c1' })).toEqual({
+      text: 'reply',
+      parentCommentId: 'c1',
+    });
+  });
+
+  it('renames id → nodeId for getNodeById', () => {
+    expect(applyParamRenames('getNodeById', { id: 'n1' })).toEqual({ nodeId: 'n1' });
+  });
+
+  it('passes through unchanged for operations with no renames', () => {
+    expect(applyParamRenames('comments.list', { limit: 10 })).toEqual({ limit: 10 });
+    expect(applyParamRenames('getText', {})).toEqual({});
+  });
+
+  it('does not strip non-renamed keys when a rename map exists', () => {
+    expect(applyParamRenames('comments.create', { text: 'top-level' })).toEqual({ text: 'top-level' });
+  });
+});

apps/mcp/src/tools/intent.ts

@@ -12,6 +12,7 @@ import type { SessionManager } from '../session-manager.js';
 import type { DocumentApi, DynamicInvokeRequest } from '@superdoc/document-api';
 import { MCP_TOOL_CATALOG } from '../generated/catalog.js';
 import { dispatchIntentTool } from '../generated/intent-dispatch.generated.js';
+import { applyParamRenames } from './param-renames.js';
 
 // ---------------------------------------------------------------------------
 // Types for the generated catalog
@@ -121,7 +122,14 @@ function buildZodSchema(tool: CatalogTool): Record<string, z.ZodTypeAny> {
 function executeOperation(api: DocumentApi, operationId: string, input: Record<string, unknown>): unknown {
   // Generated dispatch uses 'doc.' prefix (e.g. 'doc.query.match'); strip it for DocumentApi.invoke()
   const opId = operationId.startsWith('doc.') ? operationId.slice(4) : operationId;
-  return api.invoke({ operationId: opId, input } as DynamicInvokeRequest);
+  // AIDEV-NOTE: renames are applied on input only — output is not inverted.
+  // This is incidental rather than deliberate: the fix only needed to address
+  // the input path. The asymmetry is harmless: the contract response uses
+  // canonical names (e.g. commentId), and agents can use either name on
+  // subsequent calls (canonical names pass through PARAM_RENAMES unchanged;
+  // short names are renamed here). A follow-up could invert on output for
+  // symmetry, but it is not load-bearing.
+  return api.invoke({ operationId: opId, input: applyParamRenames(opId, input) } as DynamicInvokeRequest);
 }
 
 // ---------------------------------------------------------------------------

apps/mcp/src/tools/param-renames.ts

@@ -0,0 +1,37 @@
+/**
+ * Wire → contract field-name renames for intent tool dispatch.
+ *
+ * The MCP wire schema (apps/mcp/src/generated/catalog.ts) is generated from
+ * apps/cli/src/cli/operation-params.ts, where PARAM_FLAG_OVERRIDES rewrites
+ * a handful of contract field names to shorter CLI flag names (e.g.
+ * `commentId` → `id`, `parentCommentId` → `parentId`). The same renamed
+ * names end up in the MCP wire schema. Without an inverse translation at
+ * dispatch time, the contract validator rejects the input because it expects
+ * the canonical field names.
+ *
+ * The CLI applies the inverse rename in extractInvokeInput()
+ * (apps/cli/src/lib/invoke-input.ts PARAM_RENAMES). This module is the MCP
+ * mirror, kept in lockstep by hand. Five operations are affected today
+ * (comments.delete, comments.get, comments.patch, comments.create's
+ * parentId, and getNodeById's id), so duplication is small.
+ *
+ * Keys are bare operation IDs (no `doc.` prefix) to match the form
+ * executeOperation passes to api.invoke().
+ */
+const PARAM_RENAMES: Record<string, Record<string, string>> = {
+  getNodeById: { id: 'nodeId' },
+  'comments.create': { parentId: 'parentCommentId' },
+  'comments.patch': { id: 'commentId' },
+  'comments.delete': { id: 'commentId' },
+  'comments.get': { id: 'commentId' },
+};
+
+export function applyParamRenames(opId: string, input: Record<string, unknown>): Record<string, unknown> {
+  const renames = PARAM_RENAMES[opId];
+  if (!renames) return input;
+  const renamed: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(input)) {
+    renamed[renames[key] ?? key] = value;
+  }
+  return renamed;
+}