@opentiny/next-sdk 0.2.9 → 0.3.0-alpha.0

package/dist/page-tools/bridge.d.ts

@@ -4,16 +4,17 @@ import { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { WebMcpServer } from '../WebMcpServer';
 import { ToolInvokeEffectConfig } from './effects';
 
-/** 页面卸载广播，供 pageToolsOnDemand 模式监听 */
+/** 页面卸载广播消息 */
 export declare const MSG_PAGE_LEAVE = "next-sdk:page-leave";
 /** iframe 内 Remoter 就绪后向父窗口发送，父窗口回传 route-state-initial */
 export declare const MSG_REMOTER_READY = "next-sdk:remoter-ready";
-/** 父窗口向 iframe Remoter 回传的初始路由状态（toolRouteMap + activeRoutes） */
+/** 历史兼容消息类型（当前简化方案不再使用） */
 export declare const MSG_ROUTE_STATE_INITIAL = "next-sdk:route-state-initial";
+/** 工具目录发生变更（新增/删除/路由重绑定） */
+export declare const MSG_TOOL_CATALOG_CHANGED = "next-sdk:tool-catalog-changed";
 /**
  * 获取通过 withPageTools + RouteConfig 注册的全部工具路由映射。
- * 返回的是内部 Map 的只读快照，可安全遍历。
- * @returns toolName → route 的只读 Map
+ * 为保持向后兼容，仍保留该 API；简化模式下不再维护此映射，始终返回空 Map。
  */
 export declare function getToolRouteMap(): ReadonlyMap<string, string>;
 /**
@@ -22,6 +23,23 @@ export declare function getToolRouteMap(): ReadonlyMap<string, string>;
  * @returns 当前激活路由的 Set 快照
  */
 export declare function getActiveRoutes(): Set<string>;
+/**
+ * 获取当前已激活页面上的工具清单快照。
+ * key 为 route，value 为该页面当前可执行的工具名数组。
+ */
+export declare function getActivePageTools(): ReadonlyMap<string, string[]>;
+export declare function isBuiltinWebMcpSupported(): boolean;
+export declare function registerBuiltinWebMcpTool(options: {
+    name: string;
+    description?: string;
+    inputSchema?: ZodRawShape;
+    execute: (params: Record<string, unknown>) => unknown | Promise<unknown>;
+}): Promise<boolean>;
+export declare function unregisterBuiltinWebMcpTool(name: string): Promise<boolean>;
+export declare function hasBuiltinWebMcpTool(name: string): boolean;
+export declare function forceResetBuiltinWebMcpTools(): Promise<void>;
+export declare function listBuiltinWebMcpTools(): Promise<unknown[]>;
+export declare function executeBuiltinWebMcpTool(name: string, input: Record<string, unknown>): Promise<unknown>;
 /**
  * 注册应用的导航函数，通常在应用入口（如 main.ts）调用一次。
  * @param fn 导航函数，接收路由路径并执行跳转（如 router.push）
@@ -45,6 +63,16 @@ export type RouteConfig = {
      */
     invokeEffect?: boolean | ToolInvokeEffectConfig;
 };
+export type WithPageToolsOptions = {
+    /**
+     * Chrome 内置 WebMCP 兼容模式。
+     * - auto（默认）：检测到 navigator.modelContext 时，同步注册内置工具（同时保留 next-sdk 现有链路）
+     * - disabled：关闭内置兼容，仅使用 next-sdk 现有链路
+     */
+    nativeWebMcp?: {
+        mode?: 'auto' | 'disabled';
+    };
+};
 export type { ToolInvokeEffectConfig };
 /**
  * PageAwareServer 的 registerTool 配置对象类型，与 WebMcpServer.registerTool 保持一致。
@@ -63,7 +91,49 @@ type RegisterToolConfig<InputArgs extends ZodRawShape, OutputArgs extends ZodRaw
  */
 export type PageAwareServer = Omit<WebMcpServer, 'registerTool'> & {
     registerTool<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape>(name: string, config: RegisterToolConfig<InputArgs, OutputArgs>, handlerOrRoute: ((...args: any[]) => any) | RouteConfig): RegisteredTool;
+    unregisterTool(name: string): boolean;
+};
+export type PageToolDefinition<InputArgs extends ZodRawShape = ZodRawShape, OutputArgs extends ZodRawShape = ZodRawShape> = {
+    /** 工具名称 */
+    name: string;
+    /** 工具声明配置（title/description/schema/annotations） */
+    config: RegisterToolConfig<InputArgs, OutputArgs>;
+    /** 工具绑定路由 */
+    route: string;
+    /** 页面响应超时（ms） */
+    timeout?: number;
+    /** 页面调用特效 */
+    invokeEffect?: boolean | ToolInvokeEffectConfig;
+    /** 工具执行回调（可选 context，便于页面注入运行时依赖） */
+    handler: (input: any, context?: unknown) => any | Promise<any>;
+};
+export declare function definePageTool<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape>(definition: PageToolDefinition<InputArgs, OutputArgs>): PageToolDefinition<InputArgs, OutputArgs>;
+/**
+ * 批量注册页面工具声明（schema/route）到 MCP Server。
+ * 可与 mountPageTools 配套使用，实现“声明与执行回调在同一工具定义对象内”。
+ */
+export declare function registerPageTools(server: PageAwareServer, definitions: PageToolDefinition[]): RegisteredTool[];
+/**
+ * 使用 PageToolDefinition 快速在页面侧挂载 handlers（声明与执行同源）。
+ * 等价于 registerPageTool({ tools, route?, context? })
+ */
+export declare function mountPageTools(options: MountPageToolsOptions): () => void;
+export type RegisterRuntimePageToolsOptions = MountPageToolsOptions & {
+    /**
+     * 是否在页面卸载时自动移除工具声明。
+     * - true（默认）：页面即工具，离开页面后从 MCP 工具目录移除
+     * - false：只卸载 handler，工具声明保留（适合希望工具常驻目录的场景）
+     */
+    removeOnUnmount?: boolean;
 };
+/**
+ * 在业务页面内“一处定义 + 一处生效”：
+ * 1) 注册工具声明（name/description/schema/route）
+ * 2) 同时挂载工具 handler（页面生命周期内生效）
+ *
+ * 该能力与“分离式 mcp-servers + registerPageTool”并存，不会破坏原有写法。
+ */
+export declare function registerRuntimePageTools(server: PageAwareServer, options: RegisterRuntimePageToolsOptions): () => void;
 /**
  * 注册一个通用的页面跳转工具（navigate_to_page），供大模型在需要时主动跳转到指定路由。
  *
@@ -95,6 +165,7 @@ export declare function registerNavigateTool(server: WebMcpServer, options?: Nav
  *   先导航到目标路由，再通过 postMessage 与页面通信
  */
 export declare function withPageTools(server: WebMcpServer): PageAwareServer;
+export declare function withPageTools(server: WebMcpServer, options: WithPageToolsOptions): PageAwareServer;
 /**
  * 在目标页面激活工具处理器（框架无关的纯 JS 函数）。
  *
@@ -105,7 +176,10 @@ export declare function withPageTools(server: WebMcpServer): PageAwareServer;
  *
  * 返回 cleanup 函数，页面销毁时调用。
  */
-export declare function registerPageTool(options: {
+type PageToolHandlers = {
+    [toolName: string]: (input: any) => Promise<any> | any;
+};
+export type RegisterPageToolByHandlersOptions = {
     /**
      * 目标路由路径，与 RouteConfig.route 保持一致。
      * 省略时自动读取 window.location.pathname。
@@ -120,5 +194,18 @@ export declare function registerPageTool(options: {
      *（如 `async ({ productId }: { productId: string }) => ...`）无法通过类型检查，
      * 破坏现有调用方代码的开发体验。运行时输入由 MCP inputSchema 保证类型安全。
      */
-    handlers: Record<string, (input: any) => Promise<any>>;
-}): () => void;
+    handlers: PageToolHandlers;
+};
+export type MountPageToolsOptions = {
+    /**
+     * 待激活的工具定义（定义中同时包含 schema + handler）。
+     * 若 route 省略且 tools 包含多个路由，将抛出错误提示显式指定 route。
+     */
+    tools: PageToolDefinition[];
+    /** 可选：覆盖 route（只激活该路由下的工具定义） */
+    route?: string;
+    /** 运行时上下文，会作为第二参数透传给 definition.handler */
+    context?: unknown;
+};
+export declare function registerPageTool(options: RegisterPageToolByHandlersOptions): () => void;
+export declare function registerPageTool(options: MountPageToolsOptions): () => void;

package/dist/remoter/createRemoter.d.ts

@@ -49,8 +49,9 @@ declare class FloatingBlock {
     private renderItem;
     /**
      * 合并菜单项配置。
-     * - 有 sessionId：使用默认菜单 + 用户配置（可定制每一项的 show/text/icon 等）
-     * - 无 sessionId：不渲染任何下拉菜单，仅保留点击浮标打开对话框的能力
+     * - 用户明确传入 menuItems：直接使用用户配置，不受 sessionId 限制；未传 icon 时自动补充默认图标
+     * - 有 sessionId 且未传 menuItems：使用默认菜单
+     * - 无 sessionId 且未传 menuItems：不渲染任何下拉菜单，仅保留点击浮标打开对话框的能力
      */
     private mergeMenuItems;
     private init;

package/dist/transport/ExtensionPageServerTransport.d.ts

@@ -19,7 +19,6 @@ export declare class ExtensionPageServerTransport implements Transport {
     onerror?: (error: Error) => void;
     onclose?: () => void;
     readonly sessionId: string;
-    private _messageListener1;
     private _messageListener2;
     private _isStarted;
     private _isClosed;