@univerjs-pro/mcp 0.10.6-experimental.20250904-44da50e

package/lib/types/controllers/mcp-message.controller.d.ts

@@ -0,0 +1,111 @@
+import { IMCPMessage, MCPConnectionController } from './mcp-connection.controller';
+import { Disposable, ILogService } from '@univerjs/core';
+import { IMCPToolRegistry } from './mcp-tool-registry.controller';
+/**
+ * MCP Protocol message types
+ */
+export declare enum MCPMessageType {
+    REQUEST = "request",
+    RESPONSE = "response",
+    NOTIFICATION = "notification"
+}
+/**
+ * MCP Request message interface
+ */
+export interface IMCPRequest extends IMCPMessage {
+    id: string | number;
+    method: string;
+    params?: unknown;
+}
+/**
+ * MCP Response message interface
+ */
+export interface IMCPResponse extends IMCPMessage {
+    id: string | number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/**
+ * MCP Notification message interface (no response expected)
+ */
+export interface IMCPNotification extends IMCPMessage {
+    method: string;
+    params?: unknown;
+}
+/**
+ * Tool call parameters interface
+ */
+export interface IToolCallParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+/**
+ * MCP Message Controller
+ *
+ * Handles MCP protocol message processing:
+ * - Receives messages from MCP Server via WebSocket
+ * - Routes tool-call requests to appropriate tools
+ * - Validates message format and parameters
+ * - Sends responses back through WebSocket
+ * - Manages JSON-RPC 2.0 protocol compliance
+ */
+export declare class MCPMessageController extends Disposable {
+    private readonly _logService;
+    private readonly _connectionController;
+    private readonly _toolRegistry;
+    private readonly _destroy$;
+    constructor(_logService: ILogService, _connectionController: MCPConnectionController, _toolRegistry: IMCPToolRegistry);
+    /**
+     * Initialize message listener for incoming MCP messages
+     */
+    private _initMessageListener;
+    /**
+     * Handle incoming MCP messages
+     */
+    private _handleIncomingMessage;
+    /**
+     * Handle MCP request messages (expect response)
+     */
+    private _handleRequest;
+    /**
+     * Handle tool call request
+     */
+    private _handleToolCall;
+    /**
+     * Handle MCP response messages
+     */
+    private _handleResponse;
+    /**
+     * Handle MCP notification messages (no response expected)
+     */
+    private _handleNotification;
+    /**
+     * Send success response
+     */
+    private _sendSuccessResponse;
+    /**
+     * Send error response
+     */
+    private _sendErrorResponse;
+    /**
+     * Check if message is a request
+     */
+    private _isRequest;
+    /**
+     * Check if message is a response
+     */
+    private _isResponse;
+    /**
+     * Check if message is a notification
+     */
+    private _isNotification;
+    /**
+     * Convert Zod schema to JSON Schema (simplified)
+     * This is a basic implementation - a more robust solution would use a dedicated library
+     */
+    private _zodSchemaToJsonSchema;
+}

package/lib/types/controllers/mcp-tool-registry.controller.d.ts

@@ -0,0 +1,75 @@
+import { Disposable, ILogService } from '@univerjs/core';
+import { z } from 'zod';
+import { MCPUIEventService } from '../services/mcp-ui-event.service';
+/**
+ * MCP Tool definition interface
+ */
+export interface IMCPTool {
+    name: string;
+    description: string;
+    inputSchema: z.ZodSchema<any>;
+    execute: (params: any) => Promise<any>;
+}
+/**
+ * MCP Tool Registry interface
+ */
+export interface IMCPToolRegistry {
+    registerTool: (tool: IMCPTool) => void;
+    unregisterTool: (toolName: string) => void;
+    getTool: (toolName: string) => IMCPTool | undefined;
+    getAllTools: () => IMCPTool[];
+    validateToolCall: (toolName: string, params: unknown) => {
+        isValid: boolean;
+        error?: string;
+        validatedParams?: any;
+    };
+    executeTool: (toolName: string, params: any, callId?: string) => Promise<any>;
+}
+export declare const IMCPToolRegistry: import('@wendellhu/redi').IdentifierDecorator<IMCPToolRegistry>;
+/**
+ * MCP Tool Registry Controller
+ *
+ * Manages tool registration and execution for Univer MCP:
+ * - Provides API for registering and unregistering tools
+ * - Includes built-in eval_js tool for debugging
+ * - Validates tool call parameters using Zod schemas
+ * - Executes tool calls and handles errors
+ */
+export declare class MCPToolRegistryController extends Disposable implements IMCPToolRegistry {
+    private readonly _logService;
+    private readonly _mcpUIEventService;
+    private readonly _tools;
+    constructor(_logService: ILogService, _mcpUIEventService: MCPUIEventService);
+    /**
+     * Register a tool for MCP calls
+     */
+    registerTool(tool: IMCPTool): void;
+    /**
+     * Unregister a tool
+     */
+    unregisterTool(toolName: string): void;
+    /**
+     * Get a specific tool by name
+     */
+    getTool(toolName: string): IMCPTool | undefined;
+    /**
+     * Get all registered tools
+     */
+    getAllTools(): IMCPTool[];
+    /**
+     * Validate tool call parameters using Zod schema
+     */
+    validateToolCall(toolName: string, params: unknown): {
+        isValid: boolean;
+        error?: string;
+        validatedParams?: any;
+    };
+    /**
+     * Execute a tool call with parameter validation
+     */
+    executeTool(toolName: string, params: any, callId?: string): Promise<any>;
+    /**
+     * Register built-in tools
+     */
+    private _registerBuiltInTools;
+}

package/lib/types/facade/f-univer.d.ts

@@ -0,0 +1,41 @@
+import { IMCPTool } from '@univerjs-pro/mcp';
+import { FUniver } from '@univerjs/core/facade';
+/**
+ * @ignore
+ */
+interface IFUniverMCP {
+    /**
+     * Validate a tool call.
+     * @param toolName The name of the tool.
+     * @param params The parameters for the tool.
+     */
+    validateMCPToolCall(toolName: string, params: unknown): {
+        isValid: boolean;
+        error?: string;
+        validatedParams?: any;
+    };
+    /**
+     * Get all registered MCP tools.
+     */
+    getAllMCPTools(): IMCPTool[];
+    /**
+     * Call a registered MCP tool.
+     * @param toolName The name of the tool.
+     * @param params The parameters for the tool.
+     */
+    callMCPTool(toolName: string, params: unknown): Promise<any>;
+}
+export declare class FUniverMCPMixin extends FUniver implements IFUniverMCP {
+    validateMCPToolCall(toolName: string, params: unknown): {
+        isValid: boolean;
+        error?: string;
+        validatedParams?: any;
+    };
+    getAllMCPTools(): IMCPTool[];
+    callMCPTool(toolName: string, params: unknown): Promise<any>;
+}
+declare module '@univerjs/core/facade' {
+    interface FUniver extends IFUniverMCP {
+    }
+}
+export {};

package/lib/types/facade/index.d.ts

@@ -0,0 +1 @@
+import './f-univer';

package/lib/types/index.d.ts

@@ -0,0 +1,7 @@
+export type { IUniverMCPConfig } from './controllers/config.schema';
+export { MCP_PLUGIN_CONFIG_KEY, MCPConnectionError, MCPConnectionStatus } from './controllers/config.schema';
+export { MCPConnectionController } from './controllers/mcp-connection.controller';
+export { MCPMessageController } from './controllers/mcp-message.controller';
+export { type IMCPTool, IMCPToolRegistry, MCPToolRegistryController } from './controllers/mcp-tool-registry.controller';
+export { UniverMCPPlugin } from './plugin';
+export { type IConfigUpdateEvent, type IConnectionStatusEvent, type IMCPUIEvent, type IToolCallEvent, type IToolExecutionEvent, MCPUIEventId, MCPUIEventService } from './services/mcp-ui-event.service';

package/lib/types/plugin.d.ts

@@ -0,0 +1,28 @@
+import { IUniverMCPConfig } from './controllers/config.schema';
+import { IConfigService, Injector, Plugin } from '@univerjs/core';
+/**
+ *
+ * Agent (MCP Client / MCP Host) <-> Univer MCP Server Cloud <->  Univer MCP Plugin <-> Univer Instance
+ *
+ * Univer MCP Plugin is a bridge between Univer Instance and Univer MCP Server Cloud.
+ *
+ * What does this plugin do?
+ * 本插件为无UI部分，可以在node、browser等环节允许
+ * 业务逻辑在controllers实现
+ *
+ * 1. 开启安全校验时， 根据 api-key（从local-storage配置读取） /universer-api/user/session-ticket+(Authorization Bearer + api-key) 获取session-ticket
+ * 2. 根据session-ticket与Univer MCP Server Cloud /mcp-server-api/ws 建立连接
+ * 3. 意外断线时触发自动重连，最大重连次数3（成功清零），重复上述步骤
+ * 4. 提供管理（注册，注销） tool 的API， 本插件自身注册有一个 eval_js 的调试tool，使用Zod (已安装)，参数是字符串，返回值描述Any。
+ *    其它插件如果需要注册自己的 tool，可以通过调用 API 来注册
+ * 4. 接收来自Univer MCP Server Cloud的 tool-call 消息并执行，校验tool-call消息是否合法，并将执行结果通过 websocket 返回
+ *    合法包括是否存在该名称的key，参数定义是否匹配。
+ */
+export declare class UniverMCPPlugin extends Plugin {
+    private readonly _config;
+    protected readonly _injector: Injector;
+    private readonly _configService;
+    static pluginName: string;
+    constructor(_config: IUniverMCPConfig | undefined, _injector: Injector, _configService: IConfigService);
+    onStarting(): void;
+}

package/lib/types/services/mcp-ui-event.service.d.ts

@@ -0,0 +1,84 @@
+import { MCPConnectionError, MCPConnectionStatus } from '../controllers/config.schema';
+/**
+ * MCP UI event interface
+ */
+export interface IMCPUIEvent {
+    id: MCPUIEventId;
+    data?: unknown;
+}
+/**
+ * MCP UI event IDs for communication between MCP and MCP UI
+ */
+export declare enum MCPUIEventId {
+    CONNECTION_STATUS_CHANGED = "CONNECTION_STATUS_CHANGED",
+    CONNECTION_ERROR = "CONNECTION_ERROR",
+    AUTHENTICATION_FAILED = "AUTHENTICATION_FAILED",
+    SESSION_TICKET_EXPIRED = "SESSION_TICKET_EXPIRED",
+    TOOL_CALL_RECEIVED = "TOOL_CALL_RECEIVED",
+    TOOL_CALL_EXECUTED = "TOOL_CALL_EXECUTED",
+    TOOL_CALL_FAILED = "TOOL_CALL_FAILED",
+    CONFIG_UPDATED = "CONFIG_UPDATED",
+    API_KEY_UPDATED = "API_KEY_UPDATED"
+}
+/**
+ * Connection status change event data
+ */
+export interface IConnectionStatusEvent {
+    status: MCPConnectionStatus;
+    error?: MCPConnectionError;
+    message?: string;
+}
+/**
+ * Tool call event data
+ */
+export interface IToolCallEvent {
+    toolName: string;
+    parameters: unknown;
+    callId?: string;
+}
+/**
+ * Tool execution result event data
+ */
+export interface IToolExecutionEvent {
+    toolName: string;
+    callId?: string;
+    result?: unknown;
+    error?: string;
+}
+/**
+ * Configuration update event data
+ */
+export interface IConfigUpdateEvent {
+    key: string;
+    value: unknown;
+}
+/**
+ * MCP UI Event Service
+ *
+ * This service provides event communication between MCP core plugin
+ * and MCP UI plugin, similar to CollaborationUIEventService.
+ */
+export declare class MCPUIEventService {
+    private readonly _event$;
+    readonly event$: import('rxjs').Observable<IMCPUIEvent>;
+    /**
+     * Emit an MCP UI event
+     */
+    emitEvent(event: IMCPUIEvent): void;
+    /**
+     * Emit connection status change event
+     */
+    emitConnectionStatus(status: MCPConnectionStatus, error?: MCPConnectionError, message?: string): void;
+    /**
+     * Emit tool call received event
+     */
+    emitToolCallReceived(toolName: string, parameters: unknown, callId?: string): void;
+    /**
+     * Emit tool execution result event
+     */
+    emitToolExecuted(toolName: string, callId?: string, result?: unknown, error?: string): void;
+    /**
+     * Emit configuration update event
+     */
+    emitConfigUpdate(key: string, value: unknown): void;
+}

package/lib/umd/facade.js

@@ -0,0 +1 @@
+function _0x479a(_0x3989b9,_0x221fce){var _0x2273bf=_0x2273();return _0x479a=function(_0x479aa7,_0x4c5d82){_0x479aa7=_0x479aa7-0x187;var _0x1fc34d=_0x2273bf[_0x479aa7];return _0x1fc34d;},_0x479a(_0x3989b9,_0x221fce);}function _0x2273(){var _0x5c479e=['29264ffFKne','651EFcqzo','UniverCoreFacade','87831BWfGIy','getAllTools','301913NEsHDL','validateToolCall','executeTool','IMCPToolRegistry','4160732WUNkJW','59075196pCMjPu','UniverProMcp','@univerjs/core/facade','callMCPTool','_injector','3TQRuIF','12142174OvvsRO','extend','7497295ZEngwO','6eooRbl','function','10gyHxKs','object','FUniver','13vdlrfd','get','validateMCPToolCall','890uVsOAB'];_0x2273=function(){return _0x5c479e;};return _0x2273();}(function(_0x1c8db1,_0x163068){var _0x35afe6=_0x479a,_0x1977bb=_0x1c8db1();while(!![]){try{var _0x459683=-parseInt(_0x35afe6(0x199))/0x1*(parseInt(_0x35afe6(0x18d))/0x2)+-parseInt(_0x35afe6(0x187))/0x3*(parseInt(_0x35afe6(0x19d))/0x4)+parseInt(_0x35afe6(0x18a))/0x5*(-parseInt(_0x35afe6(0x18b))/0x6)+parseInt(_0x35afe6(0x195))/0x7*(-parseInt(_0x35afe6(0x194))/0x8)+parseInt(_0x35afe6(0x197))/0x9*(-parseInt(_0x35afe6(0x193))/0xa)+parseInt(_0x35afe6(0x188))/0xb+-parseInt(_0x35afe6(0x19e))/0xc*(-parseInt(_0x35afe6(0x190))/0xd);if(_0x459683===_0x163068)break;else _0x1977bb['push'](_0x1977bb['shift']());}catch(_0x471a6e){_0x1977bb['push'](_0x1977bb['shift']());}}}(_0x2273,0xbbb2f),function(_0x19607d,_0x577561){var _0x347f77=_0x479a;typeof exports==_0x347f77(0x18e)&&typeof module<'u'?_0x577561(require('@univerjs-pro/mcp'),require('@univerjs/core/facade')):typeof define==_0x347f77(0x18c)&&define['amd']?define(['@univerjs-pro/mcp',_0x347f77(0x1a0)],_0x577561):(_0x19607d=typeof globalThis<'u'?globalThis:_0x19607d||self,_0x577561(_0x19607d[_0x347f77(0x19f)],_0x19607d[_0x347f77(0x196)]));}(this,function(_0x39785b,_0x2ee111){'use strict';var _0x4c1b5b=_0x479a;class _0x1f1cda extends _0x2ee111[_0x4c1b5b(0x18f)]{[_0x4c1b5b(0x192)](_0x3fbed1,_0x75d419){var _0x232be7=_0x4c1b5b;return this[_0x232be7(0x1a2)][_0x232be7(0x191)](_0x39785b['IMCPToolRegistry'])[_0x232be7(0x19a)](_0x3fbed1,_0x75d419);}['getAllMCPTools'](){var _0x435467=_0x4c1b5b;return this['_injector'][_0x435467(0x191)](_0x39785b[_0x435467(0x19c)])[_0x435467(0x198)]();}[_0x4c1b5b(0x1a1)](_0x42ff63,_0x4c80fa){var _0xe7865e=_0x4c1b5b;return this[_0xe7865e(0x1a2)][_0xe7865e(0x191)](_0x39785b['IMCPToolRegistry'])[_0xe7865e(0x19b)](_0x42ff63,_0x4c80fa);}}_0x2ee111['FUniver'][_0x4c1b5b(0x189)](_0x1f1cda);}));