fix(build): ship the MCP compat shim, and stop its absence being silent (#112)

class-saddle-mcp-compat.php was excluded from the shared build list, and the
selfhosted channel only ever re-added the updater — so the ChatGPT fix from
#80/#81 has been in no zip on any channel since it was written.

It was reachable the whole time: adapter_available() tests for
\WP\MCP\Core\McpAdapter, not for our bundled copy, so a site running the
official MCP Adapter plugin takes the adapter path on any channel, finds
class_exists( 'Saddle_MCP_Compat' ) false, and gets an app that connects and
then reports no callable actions.

The shim now ships on both channels. It is our own code with no library behind
it and applies_to() already no-ops without SessionManager, so a .org build pays
nothing for it; unlike the updater, its absence is not a guarantee we make to
anyone. The selfhosted branch additionally re-adds includes/lib/** and the
bundled-adapter loader, which the exclusion comment has asked for since the
channel landed.

And the guard no longer fails quietly. A false class_exists() branch with no
outward signal is why this survived a release, so it now marks the health
record degraded. Noted rather than recorded at the point of discovery: the
health option is rewritten wholesale on mcp_adapter_init, later in the same
request, so a direct write there would be erased on exactly the sites that
have the adapter.

Refs #111


Claude-Session: https://claude.ai/code/session_01AnLWpPkeyppYfTuKEPhTM2

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ifahimreza

Gruntfile.js

@@ -128,13 +128,30 @@ module.exports = function ( grunt ) {
 							// the self-hosted channel lands, re-include it there the
 							// same way that branch re-includes the updater.
 							'!includes/lib/**',
-							// The two files that exist only to serve it: the
-							// loader (which declares the library's own reserved
-							// WP_MCP_* constants) and the shim for its session
-							// strictness. Both are guarded with file_exists()/
-							// class_exists() and degrade to no-ops.
+							// The loader that declares the library's own reserved
+							// WP_MCP_* constants. Useless without the library, and
+							// guarded with class_exists() at the call site.
 							'!includes/class-saddle-bundled-adapter.php',
-							'!includes/class-saddle-mcp-compat.php',
+							// class-saddle-mcp-compat.php is deliberately NOT
+							// excluded, on either channel. It used to be, and that
+							// is how the ChatGPT fix in #80/#81 shipped to nobody
+							// for a month (#111).
+							//
+							// The trap: adapter_available() tests for
+							// \WP\MCP\Core\McpAdapter, not for OUR bundled copy. A
+							// site that installs the official MCP Adapter plugin
+							// takes the adapter path on ANY channel, including
+							// .org — and then class_exists( 'Saddle_MCP_Compat' )
+							// is false, the shim never registers, and the owner
+							// gets an app that connects and reports no callable
+							// actions. Excluding it never made a build safer; it
+							// only made that failure reachable.
+							//
+							// It is ~300 lines of our own code with no library
+							// behind it, and applies_to() already no-ops when
+							// SessionManager is absent, so it costs a .org build
+							// nothing. Unlike the updater, its absence is not a
+							// guarantee we are making to anyone.
 							// WP.org listing assets — go to SVN assets/, never in the zip.
 							'!.wordpress.org/**',
 							// Lint config — dev-only.
@@ -257,11 +274,20 @@ module.exports = function ( grunt ) {
 			}
 
 			if ( 'selfhosted' === channel ) {
-				// Put the updater back by appending an un-negated pattern after
-				// the exclusion — grunt-contrib-copy applies src patterns in
-				// order, so the later include wins.
+				// Put the self-hosted-only files back by appending un-negated
+				// patterns after the exclusions — grunt-contrib-copy applies src
+				// patterns in order, so the later include wins.
+				//
+				// The adapter belongs here and did not arrive with the updater:
+				// the exclusion list has said "re-include it there the same way
+				// that branch re-includes the updater" since the channel landed,
+				// and this branch only ever pushed the updater (#111). Every
+				// build shipped so far therefore runs the JSON-RPC transport
+				// unless the site installs the official adapter plugin itself.
 				const files = grunt.config.get( 'copy.dist.files' );
 				files[ 0 ].src.push( 'includes/class-saddle-updater.php' );
+				files[ 0 ].src.push( 'includes/lib/**' );
+				files[ 0 ].src.push( 'includes/class-saddle-bundled-adapter.php' );
 				grunt.config.set( 'copy.dist.files', files );
 			}
 

includes/class-saddle-mcp-diagnostics.php

@@ -43,6 +43,29 @@ class Saddle_MCP_Diagnostics {
 	 */
 	const TRACE_OPTION = 'saddle_mcp_trace';
 
+	/**
+	 * Whether the adapter path is running without Saddle_MCP_Compat.
+	 *
+	 * Set during transport setup and merged into the health record by
+	 * {@see self::record_health()}. It is request state, not stored state: the
+	 * next request re-derives it from whether the class loaded.
+	 *
+	 * @var bool
+	 */
+	private static $compat_missing = false;
+
+	/**
+	 * Note that the adapter is serving requests without its compatibility shim.
+	 *
+	 * This is a build fault, not a configuration one — the shim was excluded
+	 * from every zip for a month while the adapter path stayed reachable through
+	 * the official MCP Adapter plugin, and the only outward symptom was a client
+	 * connecting and then finding no callable tools (#111).
+	 */
+	public static function note_compat_missing() {
+		self::$compat_missing = true;
+	}
+
 	/**
 	 * Option holding the unix timestamp recording stops at.
 	 */
@@ -153,6 +176,14 @@ public static function record_health( array $facts ) {
 		$facts['recorded_at'] = time();
 		$facts['init_fired']  = did_action( 'init' ) > 0;
 
+		// Merged into every write rather than recorded on its own, because this
+		// option is replaced wholesale and the adapter writes it later in the
+		// request than the point where the shim's absence is discovered.
+		if ( self::$compat_missing ) {
+			$facts['compat_missing'] = true;
+			$facts['degraded']       = true;
+		}
+
 		$previous = get_option( self::HEALTH_OPTION );
 		if ( is_array( $previous ) ) {
 			// Ignore the timestamp when deciding whether anything changed, or a

saddle.php

@@ -290,10 +290,23 @@ public static function setup_mcp_transport() {
 			// it. Reached only when that plugin is present.
 			add_action( 'mcp_adapter_init', array( 'Saddle_MCP', 'register_adapter_server' ) );
 
-			// Shims the adapter's session and protocol-header strictness; it has
-			// no purpose without the adapter, so it ships with it.
+			// Shims the adapter's session and protocol-header strictness.
+			//
+			// The guard stays — it is the house rule — but it no longer fails
+			// quietly. This exact class_exists() returned false in every build
+			// for a month because the zip excluded the file, and the only
+			// symptom reachable from outside was ChatGPT reporting that the
+			// site has no callable actions (#111). A guard whose false branch
+			// is invisible is how that lasted, so the false branch now says so
+			// where the owner and a support conversation can both see it.
 			if ( class_exists( 'Saddle_MCP_Compat' ) ) {
 				Saddle_MCP_Compat::register();
+			} else {
+				// Noted, not recorded: the health record is rewritten wholesale
+				// on mcp_adapter_init, a few hooks later, so anything written
+				// here would be erased on precisely the sites where the adapter
+				// is present — the only sites where this matters.
+				Saddle_MCP_Diagnostics::note_compat_missing();
 			}
 		} else {
 			add_action( 'rest_api_init', array( 'Saddle_MCP', 'register_routes' ) );