feat: add mcp stateless (#309)

<!--
Thank you for your pull request. Please review below requirements.
Bug fixes and new features should include tests and possibly benchmarks.
Contributors guide:
https://github.com/eggjs/egg/blob/master/CONTRIBUTING.md

感谢您贡献代码。请确认下列 checklist 的完成情况。
Bug 修复和新功能必须包含测试，必要时请附上性能测试。
Contributors guide:
https://github.com/eggjs/egg/blob/master/CONTRIBUTING.md
-->

##### Checklist
<!-- Remove items that do not apply. For completed items, change [ ] to
[x]. -->

- [ ] `npm test` passes
- [ ] tests and/or benchmarks are included
- [ ] documentation is changed or added
- [ ] commit message follows commit guidelines

##### Affected core subsystem(s)
<!-- Provide affected core subsystem(s). -->


##### Description of change
<!-- Provide a description of the change below this comment. -->

<!--
- any feature?
- close https://github.com/eggjs/egg/ISSUE_URL
-->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Introduced stateless stream transport support for MCP controllers,
accessible via a new endpoint for streamable HTTP interactions.
- Added centralized configuration for MCP controller endpoints and
stream transport options.
- **Documentation**
- Expanded documentation to include detailed guidance and examples on
MCP annotations, controller setup, and usage of new stream endpoints.
- **Bug Fixes**
- Middleware updated to properly handle request body parsing for the new
stateless stream endpoint.
- **Tests**
- Added comprehensive tests to verify stateless streamable MCP
controller functionality.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: akitaSummer

plugin/controller/README.md

@@ -211,3 +211,126 @@ export class FooController {
   }
 }
 ```
+
+### MCP 注解
+
+#### MCPController/MCPPrompt/MCPTool/MCPResource
+
+`@MCPController` 注解用来声明当前类是一个 MCP controller。
+通过使用装饰器 `@MCPPrompt` `@MCPTool` `@MCPResource` 来声明对应的 MCP 类型。
+使用 `@ToolArgsSchema` `@PromptArgsSchema` `@Extra` 来 schema 和 extra。
+
+```ts
+import {
+  MCPController,
+  PromptArgs,
+  ToolArgs,
+  MCPPromptResponse,
+  MCPToolResponse,
+  MCPResourceResponse,
+  MCPPrompt,
+  MCPTool,
+  MCPResource,
+  PromptArgsSchema,
+  Logger,
+  Inject,
+  ToolArgsSchema,
+} from '@eggjs/tegg';
+import z from 'zod';
+
+export const PromptType = {
+  name: z.string(),
+};
+
+export const ToolType = {
+  name: z.string({
+    description: 'npm package name',
+  }),
+};
+
+
+@MCPController()
+export class McpController {
+
+  @Inject()
+  logger: Logger;
+
+  @MCPPrompt()
+  async foo(@PromptArgsSchema(PromptType) args: PromptArgs<typeof PromptType>): Promise<MCPPromptResponse> {
+    this.logger.info('hello world');
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Generate a concise but descriptive commit message for these changes:\n\n${args.name}`,
+          },
+        },
+      ],
+    };
+  }
+
+  @MCPTool()
+  async bar(@ToolArgsSchema(ToolType) args: ToolArgs<typeof ToolType>): Promise<MCPToolResponse> {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `npm package: ${args.name} not found`,
+        },
+      ],
+    };
+  }
+
+
+  @MCPResource({
+    template: [
+      'mcp://npm/{name}{?version}',
+      {
+        list: () => {
+          return {
+            resources: [
+              { name: 'egg', uri: 'mcp://npm/egg?version=4.10.0' },
+              { name: 'mcp', uri: 'mcp://npm/mcp?version=0.10.0' },
+            ],
+          };
+        },
+      },
+    ],
+  })
+  async car(uri: URL): Promise<MCPResourceResponse> {
+    return {
+      contents: [{
+        uri: uri.toString(),
+        text: 'MOCK TEXT',
+      }],
+    };
+  }
+}
+
+```
+
+#### MCP 地址
+MCP controller 完整的实现了 SSE / streamable HTTP / streamable stateless HTTP 三种模式，默认情况下，他们的路径分别是 `/mcp/init` `/mcp/stream` `/mcp/stateless/stream`, 你可以根据你所需要的场景，灵活使用对应的接口。 
+
+``` ts
+// config.{env}.ts
+import { randomUUID } from 'node:crypto';
+
+export default () => {
+
+  const config = {
+    mcp: {
+      sseInitPath: '/mcp/init', // SSE path
+      sseMessagePath: '/mcp/message', // SSE message path
+      streamPath: '/mcp/stream', // streamable path
+      statelessStreamPath: '/mcp/stateless/stream', // stateless streamable path
+      sessionIdGenerator: randomUUID, 
+    },
+  };
+
+  return config;
+};
+
+```

plugin/controller/app.ts

@@ -73,6 +73,7 @@ export default class ControllerAppBootHook {
             this.app.config.mcp.sseInitPath,
             this.app.config.mcp.sseMessagePath,
             this.app.config.mcp.streamPath,
+            this.app.config.mcp.statelessStreamPath,
             ...(Array.isArray(this.app.config.security.csrf.ignore)
               ? this.app.config.security.csrf.ignore
               : [ this.app.config.security.csrf.ignore ]),
@@ -83,6 +84,7 @@ export default class ControllerAppBootHook {
           this.app.config.mcp.sseInitPath,
           this.app.config.mcp.sseMessagePath,
           this.app.config.mcp.streamPath,
+          this.app.config.mcp.statelessStreamPath,
         ];
       }
     }
@@ -108,6 +110,9 @@ export default class ControllerAppBootHook {
     // The HTTPControllerRegister will collect all the methods
     // and register methods after collect is done.
     HTTPControllerRegister.instance?.doRegister(this.app.rootProtoManager);
+    if (this.app.mcpProxy) {
+      MCPControllerRegister.connectStatelessStreamTransport();
+    }
   }
 
   async beforeClose() {

plugin/controller/app/middleware/mcp_body_middleware.ts

@@ -3,7 +3,7 @@ import pathToRegexp from 'path-to-regexp';
 
 export default () => {
   return async function mcpBodyMiddleware(ctx: EggContext, next: Next) {
-    const arr = [ ctx.app.config.mcp.sseInitPath, ctx.app.config.mcp.sseMessagePath, ctx.app.config.mcp.streamPath ];
+    const arr = [ ctx.app.config.mcp.sseInitPath, ctx.app.config.mcp.sseMessagePath, ctx.app.config.mcp.streamPath, ctx.app.config.mcp.statelessStreamPath ];
     const res = arr.some(igPath => {
       const match = pathToRegexp(igPath, [], {
         end: false,

plugin/controller/config/config.default.ts

@@ -7,6 +7,7 @@ export default () => {
       sseInitPath: '/mcp/init',
       sseMessagePath: '/mcp/message',
       streamPath: '/mcp/stream',
+      statelessStreamPath: '/mcp/stateless/stream',
       sessionIdGenerator: randomUUID,
     },
   };

plugin/controller/lib/impl/mcp/MCPConfig.ts

@@ -0,0 +1,61 @@
+import { randomUUID } from 'node:crypto';
+import { EventStore } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { InMemoryEventStore } from '@modelcontextprotocol/sdk/examples/shared/inMemoryEventStore.js';
+
+export interface MCPConfigOptions {
+  sseInitPath: string;
+  sseMessagePath: string;
+  streamPath: string;
+  statelessStreamPath: string;
+  sessionIdGenerator?: () => string;
+  eventStore?: EventStore;
+  sseHeartTime?: number;
+}
+
+export class MCPConfig {
+  private _sseInitPath: string;
+  private _sseMessagePath: string;
+  private _streamPath: string;
+  private _statelessStreamPath: string;
+  private _sessionIdGenerator: () => string;
+  private _eventStore: EventStore;
+  private _sseHeartTime: number;
+
+  constructor(options: MCPConfigOptions) {
+    this._sessionIdGenerator = options.sessionIdGenerator ?? randomUUID;
+    this._sseInitPath = options.sseInitPath;
+    this._sseMessagePath = options.sseMessagePath;
+    this._streamPath = options.streamPath;
+    this._statelessStreamPath = options.statelessStreamPath;
+    this._eventStore = options.eventStore ?? new InMemoryEventStore();
+    this._sseHeartTime = options.sseHeartTime ?? 25000;
+  }
+
+  get sseInitPath() {
+    return this._sseInitPath;
+  }
+
+  get sseMessagePath() {
+    return this._sseMessagePath;
+  }
+
+  get streamPath() {
+    return this._streamPath;
+  }
+
+  get statelessStreamPath() {
+    return this._statelessStreamPath;
+  }
+
+  get sessionIdGenerator() {
+    return this._sessionIdGenerator;
+  }
+
+  get eventStore() {
+    return this._eventStore;
+  }
+
+  get sseHeartTime() {
+    return this._sseHeartTime;
+  }
+}