fix: Enable javadoc generation for modules with OSGi metadata

[jonathanhefner]

DISCLAIMER: As part of an effort to publish API docs for all official MCP SDKs, I am trying to fix publishing of this SDK's Javadoc to javadoc.io. However, I am not a Java developer, and do not have a full understanding of the reason publishing is currently broken. This solution was written by Claude Code after a long conversation with me, but I am relying on the maintainers to judge whether it is a proper solution.

---

Problem:
The javadoc JARs published to Maven Central for mcp-core and other modules contain no HTML documentation (only META-INF directory structure). This prevents javadoc.io from automatically displaying API documentation for these modules.

Root cause:
The bnd-maven-plugin adds an Automatic-Module-Name entry to the JAR manifest for OSGi compatibility. When maven-javadoc-plugin detects this manifest entry, it switches from traditional classpath mode to JPMS (Java Platform Module System) module mode. In module mode, javadoc uses different command-line arguments (--module-path and --patch-module instead of -sourcepath), which fail to generate HTML output for automatic modules.

Considered solutions:

1. Remove Automatic-Module-Name from the manifest

   • Fixes javadoc generation
   • Current module name already invalid for JPMS (contains dash, see Invalid Automatic-Module-Name in mcp-core #560)
   • Would not break working JPMS usage (already broken)
   • Removes future option to support JPMS once module name is fixed

2. Add legacyMode=true to maven-javadoc-plugin

   • Forces pre-Java 9 classpath-based javadoc generation instead of module mode
   • No changes to manifest (preserves invalid module name as-is)
   • Maven documentation recommends legacyMode when automatic module detection causes build issues
   • Used by other projects with automatic modules (e.g., Apache Avro PR 3041)

Implementation:

• Upgraded maven-javadoc-plugin from 3.5.0 to 3.11.2 (legacyMode added in 3.6.0)
• Added <legacyMode>true</legacyMode> to force classpath-based generation

Both solutions were tested in separate git worktrees using Docker-based Maven builds. Both produce identical javadoc output (mcp-core: 558 bytes → 1.4 MB, 474 HTML files). Solution 2 was chosen to avoid breaking changes.

Fixes javadoc generation for mcp-core and other modules using bnd-maven-plugin.

🤖 Generated with Claude Code