refactor(controller): host-agnostic MCP register via McpRouter boundary

The MCP controller register mixed record collection with egg-specific
transport (routes on app.router, ctxStorage, middleware, SSE/stream
state), and the egg host threaded its Application into the module
inner-object DI graph as a PRIVATE `eggApp` provided object so the
register could reach it — a host-boundary leak that undermines the
host-agnostic module-plugin goal.

Extract a `McpRouter` transport boundary (controller-core): the shared
`MCPControllerRegister` now only COLLECTS tool/resource/prompt records
and delegates transport to an injected router via `registerServer()`.
The egg node-HTTP transport moves to `EggMcpRouter` (constructed
imperatively in app.ts, which already holds `app`), and the service
worker fetch transport to `ServiceWorkerMcpRouter`; both provide the
`mcpRouter` DI name (the two host plugins are never used together, so no
qualifier is needed). MCPServerHelper was already host-agnostic and is
unchanged.

With the register no longer needing `app`, the `eggApp` provided inner
object is removed from ModuleHandler and EggControllerRegisterFactory
drops its host generic/injection — Egg Application leaves the DI graph.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: gxkl

tegg/plugin/controller/package.json

@@ -51,6 +51,8 @@
     "./lib/impl/http/HTTPMethodRegister": "./src/lib/impl/http/HTTPMethodRegister.ts",
     "./lib/impl/http/HTTPMethodRegisterBase": "./src/lib/impl/http/HTTPMethodRegisterBase.ts",
     "./lib/impl/http/Req": "./src/lib/impl/http/Req.ts",
+    "./lib/impl/mcp/EggMcpRouter": "./src/lib/impl/mcp/EggMcpRouter.ts",
+    "./lib/impl/mcp/McpRouter": "./src/lib/impl/mcp/McpRouter.ts",
     "./lib/impl/mcp/MCPConfig": "./src/lib/impl/mcp/MCPConfig.ts",
     "./lib/impl/mcp/MCPControllerRegister": "./src/lib/impl/mcp/MCPControllerRegister.ts",
     "./lib/impl/mcp/MCPServerHelper": "./src/lib/impl/mcp/MCPServerHelper.ts",

tegg/plugin/controller/src/app.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert';
 
-import { ControllerMetaBuilderFactory, ControllerType } from '@eggjs/controller-decorator';
+import { ControllerMetaBuilderFactory, ControllerType, type MCPControllerMeta } from '@eggjs/controller-decorator';
 import { EggPrototypeFactory, GlobalGraph, type LoadUnitLifecycleContext } from '@eggjs/metadata';
 import {
   EggContainerFactory,
@@ -15,13 +15,14 @@ import { AgentControllerProto } from './lib/AgentControllerProto.ts';
 import { CONTROLLER_LOAD_UNIT, ControllerLoadUnit } from './lib/ControllerLoadUnit.ts';
 import { ControllerLoadUnitHandler } from './lib/ControllerLoadUnitHandler.ts';
 import { ControllerMetadataManager } from './lib/ControllerMetadataManager.ts';
+import { ControllerRegisterDefaults } from './lib/ControllerRegisterDefaults.ts';
 import type { ControllerRegisterFactory } from './lib/ControllerRegisterFactory.ts';
 import { EggControllerLoader } from './lib/EggControllerLoader.ts';
 import { HTTPControllerRegister } from './lib/impl/http/HTTPControllerRegister.ts';
+import { EggMcpRouter } from './lib/impl/mcp/EggMcpRouter.ts';
 import { MCPControllerRegister } from './lib/impl/mcp/MCPControllerRegister.ts';
 import { middlewareGraphHook } from './lib/MiddlewareGraphHook.ts';
 import type { RootProtoManager } from './lib/RootProtoManager.ts';
-import { ControllerRegisterDefaults } from './lib/ControllerRegisterDefaults.ts';
 
 // Load Controller process
 // 1. await add load unit is ready, controller may depend other load unit
@@ -60,8 +61,13 @@ export default class ControllerAppBootHook implements ILifecycleBoot {
       return new EggControllerLoader(unitPath);
     });
     // Drained by the module factory proto when the InnerObjectLoadUnit
-    // materializes (before any business load unit).
-    ControllerRegisterDefaults.enqueue(ControllerType.HTTP, HTTPControllerRegister.create);
+    // materializes (before any business load unit). The creators close over
+    // `this.app` (rather than the DI-threaded host) so the egg app never has to
+    // be provided as an inner object — HTTP registers mount on `app.router`,
+    // the MCP router captures the app imperatively.
+    ControllerRegisterDefaults.enqueue(ControllerType.HTTP, (proto, meta) =>
+      HTTPControllerRegister.create(proto, meta, this.app),
+    );
     this.app.loadUnitFactory.registerLoadUnitCreator(
       CONTROLLER_LOAD_UNIT,
       (ctx: LoadUnitLifecycleContext): ControllerLoadUnit => {
@@ -97,7 +103,18 @@ export default class ControllerAppBootHook implements ILifecycleBoot {
     // init http root proto middleware
     this.prepareMiddleware(this.app.config.coreMiddleware);
     if (this.mcpEnable()) {
-      ControllerRegisterDefaults.enqueue(ControllerType.MCP, MCPControllerRegister.create);
+      // One EggMcpRouter + one collect-only MCPControllerRegister per app,
+      // created lazily on the first MCP controller proto (during didLoad, when
+      // app.router/app.config.mcp are ready). The router owns all egg transport;
+      // the register only collects records and delegates to the router.
+      let eggMcpRouter: EggMcpRouter | undefined;
+      let mcpRegister: MCPControllerRegister | undefined;
+      ControllerRegisterDefaults.enqueue(ControllerType.MCP, (proto, meta) => {
+        eggMcpRouter ??= new EggMcpRouter(this.app);
+        mcpRegister ??= new MCPControllerRegister(meta as MCPControllerMeta, eggMcpRouter);
+        mcpRegister.addControllerProto(proto);
+        return mcpRegister;
+      });
       // Don't let the mcp's body be consumed
       this.app.config.coreMiddleware.unshift('mcpBodyMiddleware');
 
@@ -168,7 +185,7 @@ export default class ControllerAppBootHook implements ILifecycleBoot {
       // and register methods after collect is done.
       HTTPControllerRegister.instance?.doRegister(this.app.rootProtoManager);
 
-      this.app.config.mcp.hooks = MCPControllerRegister.hooks;
+      this.app.config.mcp.hooks = EggMcpRouter.hooks;
     });
   }
 
@@ -190,7 +207,8 @@ export default class ControllerAppBootHook implements ILifecycleBoot {
       // InnerObjectLoadUnit teardown.
       ControllerMetadataManager.instance.clear();
       HTTPControllerRegister.clean();
-      MCPControllerRegister.clean();
+      // The MCP register/router are per-boot closures (no static instance to
+      // clean); the scope-backed hook list is torn down with the app bag.
     });
   }
 }

tegg/plugin/controller/src/index.ts

@@ -12,4 +12,5 @@ export * from './lib/RootProtoManager.ts';
 export * from './lib/errors.ts';
 export * from './lib/impl/http/HTTPControllerRegisterBase.ts';
 export * from './lib/impl/http/HTTPMethodRegisterBase.ts';
+export * from './lib/impl/mcp/McpRouter.ts';
 export * from './lib/impl/mcp/MCPServerHelper.ts';

tegg/plugin/controller/src/lib/ControllerModule.ts

@@ -1,13 +1,6 @@
 import { LifecyclePostInject } from '@eggjs/lifecycle';
-import {
-  EggPrototypeLifecycleProto,
-  Inject,
-  InjectOptional,
-  InnerObjectProto,
-  LoadUnitLifecycleProto,
-} from '@eggjs/tegg';
+import { EggPrototypeLifecycleProto, Inject, InnerObjectProto, LoadUnitLifecycleProto } from '@eggjs/tegg';
 import { AccessLevel } from '@eggjs/tegg-types';
-import type { Application } from 'egg';
 
 import { ControllerLoadUnitHook } from './ControllerLoadUnitHook.ts';
 import { ControllerPrototypeHook } from './ControllerPrototypeHook.ts';
@@ -28,13 +21,11 @@ import { RootProtoManager } from './RootProtoManager.ts';
 export class EggRootProtoManager extends RootProtoManager {}
 
 @InnerObjectProto({ name: 'controllerRegisterFactory', accessLevel: AccessLevel.PUBLIC })
-export class EggControllerRegisterFactory extends ControllerRegisterFactory<Application | undefined> {
-  // The egg host provides `eggApp` as a PRIVATE inner object (transport
-  // registers mount routes on app.router); standalone provides none and the
-  // fetch creators ignore the host argument.
-  constructor(@InjectOptional() eggApp?: Application) {
-    super(eggApp);
-  }
+export class EggControllerRegisterFactory extends ControllerRegisterFactory {
+  // No host is threaded through the DI graph: egg's transport creators close
+  // over `app` imperatively (see app.ts), the fetch creators are container
+  // citizens. Both register through ControllerRegisterDefaults / the injected
+  // factory directly.
 
   /**
    * Apply the transport creators the host enqueued imperatively before this