@cocos/cocos-cli-types 0.0.1-alpha.21.1 → 0.0.1-alpha.21.2

package/index.d.ts

@@ -2,6 +2,9 @@
 
 import { ChunkInfo } from '@cocos/creator-programming-quick-pack/lib/loader';
 import { EventEmitter } from 'events';
+import { NextFunction } from 'express';
+import { Request as Request_2 } from 'express';
+import { Response as Response_2 } from 'express';
 
 /** 动画剪辑资源的 userData */
 declare interface AnimationClipAssetUserData {
@@ -669,13 +672,27 @@ declare function getMetadata(): Promise<ICocosConfigurationNode[]>;
 declare function getProgrammingFacet(): Promise<ProgrammingFacet>;
 
 /**
- * Get the MCP server status.
+ * Get the MCP registration status.
  */
 declare function getStatus(): {
+    registered: boolean;
+    url?: string;
+};
+
+/**
+ * Get the server running status.
+ */
+declare function getStatus_2(): {
     running: boolean;
     url?: string;
 };
 
+/**
+ * Get the current server base URL.
+ * Returns undefined if the server is not running.
+ */
+declare function getUrl(): string | undefined;
+
 /** glTF 动画资源的 userData */
 declare interface GltfAnimationAssetUserData {
     gltfIndex: number;
@@ -1247,6 +1264,11 @@ declare type IFlags = Record<string, boolean | number>;
 
 declare type IFlags_2 = Record<string, boolean | number>;
 
+declare interface IGetPostConfig {
+    url: string | RegExp;
+    handler: (req: Request_2, res: Response_2, next?: NextFunction) => Promise<void>;
+}
+
 declare interface IInitEngineInfo {
     importBase: string;
     nativeBase: string;
@@ -1302,6 +1324,13 @@ declare interface ImageMeta {
     remap?: string;
 }
 
+declare interface IMiddlewareContribution {
+    get?: IGetPostConfig[];
+    post?: IGetPostConfig[];
+    staticFiles?: IStaticFileConfig[];
+    socket?: ISocketConfig;
+}
+
 declare interface IModuleConfig {
     moduleTreeDump: {
         default: IModules;
@@ -1465,6 +1494,11 @@ declare interface IRedirectInfo {
     uuid: string;
 }
 
+declare interface ISocketConfig {
+    connection: (socket: any) => void;
+    disconnect: (socket: any) => void;
+}
+
 declare interface ISplashBackgroundColor {
     x: number;
     y: number;
@@ -1491,6 +1525,11 @@ declare interface ISplashSetting {
     }
 }
 
+declare interface IStaticFileConfig {
+    url: string;
+    path: string;
+}
+
 declare type ISupportCreateCCType =
 | 'cc.AnimationClip'        // 动画剪辑
 | 'cc.Script'               // 脚本（TypeScript/JavaScript）
@@ -1602,8 +1641,8 @@ declare type MakeRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
 
 export declare namespace Mcp {
     export {
-        startServer,
-        stopServer,
+        register,
+        unregister,
         getStatus
     };
 }
@@ -2118,6 +2157,36 @@ declare function queryUUID(urlOrPath: string): Promise<string | null>;
  */
 declare function refresh(dir: string): Promise<number>;
 
+/**
+ * MCP Facade Module
+ *
+ * Called by the cocos-code utility process to register MCP middleware
+ * in an already-initialized environment.
+ * Prerequisite: the Server module must be started before calling this module.
+ * This module only handles MCP-specific work: populating the toolRegistry
+ * and registering MCP routes on the running server.
+ */
+/**
+ * Register MCP middleware on the running server.
+ *
+ * Note: the Express server must already be started via the Server module.
+ * This function only:
+ * 1. Imports API modules to populate the toolRegistry (@tool decorator side-effects)
+ * 2. Creates McpMiddleware and registers routes on the server
+ *
+ * @returns MCP endpoint URL (e.g. http://localhost:9527/mcp)
+ */
+declare function register(): Promise<string>;
+
+/**
+ * Register a middleware contribution (routes, static files, sockets)
+ * on the running server.
+ *
+ * @param name   Middleware identifier
+ * @param module Middleware contribution config
+ */
+declare function register_2(name: string, module: IMiddlewareContribution): Promise<void>;
+
 /**
  * Reimport Asset // 重新导入资源
  */
@@ -2188,6 +2257,16 @@ declare interface SerializedAssetFinder {
     scenes?: Array<string | null>;
 }
 
+export declare namespace Server {
+    export {
+        start_2 as start,
+        stop_2 as stop,
+        getUrl,
+        register_2 as register,
+        getStatus_2 as getStatus
+    };
+}
+
 declare function set<T>(key: string, value: T, scope?: ConfigurationScope): Promise<boolean>;
 
 declare interface SharedSettings {
@@ -2282,37 +2361,26 @@ declare interface SpriteFrameVertices {
 declare function start(): Promise<void>;
 
 /**
- * 在独立的子进程中运行项目脚本编译
- * 以避免阻塞主进程
- */
-declare function startCompileScript(assetChanges?: AssetChangeInfo[]): Promise<void>;
-
-declare function startEngineCompilation(force?: boolean): Promise<void>;
-
-/**
- * MCP Server Facade Module
+ * Server Facade Module
  *
- * Called by the cocos-code utility process to start the MCP server
- * in an already-initialized environment.
- * Prerequisite: core modules (project/engine/assets/scripting/builder)
- * have been initialized via their respective lib modules.
- * This module only handles MCP-specific work: populating the toolRegistry,
- * starting Express, and registering MCP routes.
+ * Provides a simplified interface for managing the Express HTTP server.
+ * Wraps the core server service with startup guards and status tracking.
  */
 /**
- * Start the MCP server.
- *
- * Note: does NOT call CocosAPI.startup() / Launcher because
- * core modules are already initialized by the utility process.
- * This function only:
- * 1. Imports API modules to populate the toolRegistry (@tool decorator side-effects)
- * 2. Starts the Express HTTP server
- * 3. Creates McpMiddleware and registers routes
+ * Initialize and start the Express HTTP server.
  *
  * @param port Optional port number; auto-selected if omitted
- * @returns MCP server URL (e.g. http://localhost:9527/mcp)
+ * @returns The server base URL (e.g. http://localhost:9527)
  */
-declare function startServer(port?: number): Promise<string>;
+declare function start_2(port?: number): Promise<string>;
+
+/**
+ * 在独立的子进程中运行项目脚本编译
+ * 以避免阻塞主进程
+ */
+declare function startCompileScript(assetChanges?: AssetChangeInfo[]): Promise<void>;
+
+declare function startEngineCompilation(force?: boolean): Promise<void>;
 
 /**
  * Start the scene worker process.
@@ -2322,9 +2390,9 @@ declare function startServer(port?: number): Promise<string>;
 declare function startupWorker(projectPath: string): Promise<void>;
 
 /**
- * Stop the MCP server.
+ * Stop the Express HTTP server.
  */
-declare function stopServer(): Promise<void>;
+declare function stop_2(): Promise<void>;
 
 /** 支持创建的资源类型常量数组（用于 Zod enum 和 TypeScript type） */
 declare const SUPPORT_CREATE_TYPES: readonly ['animation-clip', 'typescript', 'auto-atlas', 'effect', 'scene', 'prefab', 'material', 'terrain', 'physics-material', 'label-atlas', 'render-texture', 'directory', 'effect-header'];
@@ -2388,6 +2456,12 @@ declare interface ThumbnailInfo {
     value: string; // 具体 icon 名字或者 image 路径，image 路径支持绝对路径、 db:// 、 project:// 、和 packages:// 下的路径
 }
 
+/**
+ * Clean up MCP state.
+ * Note: does NOT stop the Express server — use the Server module for that.
+ */
+declare function unregister(): Promise<void>;
+
 /**
  * Update Asset User Data // 更新资源用户数据
  */

package/package.json

@@ -2,7 +2,7 @@
     "name": "@cocos/cocos-cli-types",
     "description": "types for cocos cli",
     "author": "cocos cli",
-    "version": "0.0.1-alpha.21.1",
+    "version": "0.0.1-alpha.21.2",
     "main": "index.d.ts",
     "types": "index.d.ts",
     "exports": {