Description
During integration testing of the dotCMS MCP server with Claude Code, the OpenAPI descriptions served at `/api/openapi.json` were found to be incomplete or inaccurate across multiple endpoints. This caused the AI agent to make incorrect assumptions — missing parameter constraints, undocumented behavioral edge cases, and misleading parameter descriptions — resulting in unexpected errors and failed calls that required manual intervention to diagnose.
This task tracks implementing all proposals from the feedback document by updating the Java OpenAPI annotations that feed `/api/openapi.json`.
Why this matters
The MCP server exposes dotCMS capabilities to AI agents using the OpenAPI spec as its source of truth. Inaccurate or incomplete descriptions directly degrade AI-assisted interactions: agents attempt invalid calls and cannot self-correct without accurate constraints and behavioral notes in the spec.
Common patterns found across endpoints
- Missing parameter constraints (e.g., accepted value types, format requirements)
- Undocumented edge cases and special values (e.g., root paths, default behaviors)
- Misleading parameter descriptions that imply behavior that does not exist
- Missing or incomplete error response documentation
Acceptance Criteria
Additional Context
Feedback document (source of truth for all proposals):
https://docs.google.com/document/d/1XwH3d8GL6dcBSApXz3hsb4xwpCkodShZjG7tuovPqLw/edit?tab=t.0#heading=h.eflbgemo69d1
The document was produced as a companion to MCP testing logs. For each affected endpoint it captures the exact problem with the current description and a proposed rewrite.
Spec served at: /api/openapi.json
Description
During integration testing of the dotCMS MCP server with Claude Code, the OpenAPI descriptions served at `/api/openapi.json` were found to be incomplete or inaccurate across multiple endpoints. This caused the AI agent to make incorrect assumptions — missing parameter constraints, undocumented behavioral edge cases, and misleading parameter descriptions — resulting in unexpected errors and failed calls that required manual intervention to diagnose.
This task tracks implementing all proposals from the feedback document by updating the Java OpenAPI annotations that feed `/api/openapi.json`.
Why this matters
The MCP server exposes dotCMS capabilities to AI agents using the OpenAPI spec as its source of truth. Inaccurate or incomplete descriptions directly degrade AI-assisted interactions: agents attempt invalid calls and cannot self-correct without accurate constraints and behavioral notes in the spec.
Common patterns found across endpoints
Acceptance Criteria
descriptionand@Parameterannotations for each affected endpoint are updated in the Java source to match the proposed rewrites/api/openapi.jsonreflects all updated descriptions after a build with no compilation errorsAdditional Context
Feedback document (source of truth for all proposals):
https://docs.google.com/document/d/1XwH3d8GL6dcBSApXz3hsb4xwpCkodShZjG7tuovPqLw/edit?tab=t.0#heading=h.eflbgemo69d1
The document was produced as a companion to MCP testing logs. For each affected endpoint it captures the exact problem with the current description and a proposed rewrite.
Spec served at:
/api/openapi.json