🔌 擴充功能開發指南

伺服器啟動 → 載入擴展配置 → MCP 就緒
                 ↓
         背景初始化（異步）
                 ↓
         啟動所有擴展程序 → 握手交換元資料
                                    ↓
MCP Client → extension(bind) → ExtensionSessionBridge ←─┘
                                    ↓
Session 變更 → DocumentConversionService → 快照
                                    ↓
                    Extension Process (Node.js/Python/etc.)
                                    ↓
                         接收快照 → 處理 → 回應 ACK

# 環境變數
ASPOSE_SESSION_ENABLED=true
ASPOSE_EXTENSION_ENABLED=true
ASPOSE_EXTENSION_CONFIG=/path/to/extensions.json

# 或命令行參數
./AsposeMcpServer --http \
    --session-enabled \
    --extension-enabled \
    --extension-config ./extensions.json

{
  "extensions": {
    "pdf-viewer": {
      "command": {
        "type": "node",
        "executable": "/path/to/index.js",
        "arguments": "--port 8080",
        "workingDirectory": "/path/to/extension",
        "environment": {
          "NODE_ENV": "production"
        }
      },
      "inputFormats": ["pdf"],
      "supportedDocumentTypes": ["word", "excel", "powerpoint", "pdf"],
      "transportModes": ["mmap", "stdin", "file"],
      "preferredTransportMode": "file",
      "capabilities": {
        "supportsHeartbeat": true,
        "frameIntervalMs": 100
      }
    },
    "cloud-sync": {
      "command": {
        "type": "python",
        "executable": "/path/to/main.py"
      },
      "inputFormats": ["pdf", "html"],
      "supportedDocumentTypes": ["word", "excel"],
      "transportModes": ["file"],
      "preferredTransportMode": "file",
      "capabilities": {
        "supportsHeartbeat": true,
        "idleTimeoutMinutes": 5
      }
    }
  }
}

MCP Server                                    Extension
    │                                              │
    │  1. 啟動擴展程序                              │
    │─────────────────────────────────────────────>│
    │                                              │
    │  2. {"type":"initialize","protocolVersion":"1.0"}
    │─────────────────────────────────────────────>│
    │                                              │
    │  3. {"type":"initialize_response","name":"...","version":"..."}
    │<─────────────────────────────────────────────│
    │                                              │
    │  4. {"type":"initialized"}                   │
    │─────────────────────────────────────────────>│
    │                                              │
    │  握手完成，開始正常運作                        │

{
  "operation": "list"
}

{
  "operation": "bind",
  "sessionId": "abc123",
  "extensionId": "pdf-viewer",
  "format": "pdf"
}

{
  "operation": "unbind",
  "sessionId": "abc123",
  "extensionId": "pdf-viewer"
}

{
  "operation": "status",
  "extensionId": "pdf-viewer"
}

{
  "operation": "set_format",
  "sessionId": "abc123",
  "extensionId": "pdf-viewer",
  "format": "html"
}

{
  "operation": "bindings",
  "sessionId": "abc123"
}

{
  "operation": "command",
  "sessionId": "abc123",
  "extensionId": "pdf-viewer",
  "command": "goto",
  "data": { "page": 5 }
}

const readline = require('readline');

let initialized = false;

const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    terminal: false
});

rl.on('line', (line) => {
    try {
        const message = JSON.parse(line);
        const msgType = message.type;

        switch (msgType) {
            // ===== 握手協議 =====
            case 'initialize':
                // 回應握手，提供擴展元資料
                const initResponse = {
                    type: 'initialize_response',
                    name: 'My Extension',
                    version: '1.0.0',
                    title: '我的擴展功能',
                    description: '提供自訂文件處理功能',
                    author: '開發者名稱',
                    websiteUrl: 'https://example.com'
                };
                console.log(JSON.stringify(initResponse));
                console.error('Handshake: sent initialize_response');
                break;

            case 'initialized':
                // 握手完成，開始正常運作
                initialized = true;
                console.error('Handshake completed, ready to receive messages');
                break;

            // ===== 正常運作消息 =====
            case 'snapshot':
                if (!initialized) {
                    console.error('Warning: received snapshot before initialization');
                    return;
                }
                // 處理快照
                console.error(`Received snapshot for session ${message.sessionId}`);
                console.error(`File: ${message.filePath}, Size: ${message.dataSize}`);

                // 驗證 checksum（可選但建議）
                // const data = fs.readFileSync(message.filePath);
                // if (crc32(data) !== message.checksum) { /* 處理錯誤 */ }

                // 發送 ACK
                const ack = {
                    type: 'ack',
                    sessionId: message.sessionId,
                    sequenceNumber: message.sequenceNumber,
                    success: true
                };
                console.log(JSON.stringify(ack));
                break;

            case 'heartbeat':
                // 回應心跳
                const response = {
                    type: 'heartbeat_response',
                    status: 'ok',
                    timestamp: new Date().toISOString()
                };
                console.log(JSON.stringify(response));
                break;

            case 'command':
                // 處理命令
                console.error(`Received command: ${message.commandType}`);
                console.error(`Payload: ${JSON.stringify(message.commandPayload)}`);
                break;

            case 'session_closed':
                // 清理 Session 資源
                console.error(`Session ${message.sessionId} closed`);
                break;

            case 'session_unbound':
                // Session 解除綁定（Session 仍存在，但不再綁定到此擴展）
                console.error(`Session ${message.sessionId} unbound`);
                break;

            case 'shutdown':
                // 準備關閉
                console.error('Shutdown requested');
                process.exit(0);
                break;
        }
    } catch (error) {
        console.error('Error processing message:', error);
    }
});

console.error('Extension started, waiting for handshake...');

import sys
import json
from datetime import datetime

initialized = False

def main():
    global initialized
    print("Extension started, waiting for handshake...", file=sys.stderr)

    for line in sys.stdin:
        try:
            message = json.loads(line.strip())
            msg_type = message.get('type')

            # ===== 握手協議 =====
            if msg_type == 'initialize':
                # 回應握手，提供擴展元資料
                init_response = {
                    'type': 'initialize_response',
                    'name': 'My Extension',
                    'version': '1.0.0',
                    'title': '我的擴展功能',
                    'description': '提供自訂文件處理功能',
                    'author': '開發者名稱',
                    'websiteUrl': 'https://example.com'
                }
                print(json.dumps(init_response))
                sys.stdout.flush()
                print("Handshake: sent initialize_response", file=sys.stderr)

            elif msg_type == 'initialized':
                # 握手完成，開始正常運作
                initialized = True
                print("Handshake completed, ready to receive messages", file=sys.stderr)

            # ===== 正常運作消息 =====
            elif msg_type == 'snapshot':
                if not initialized:
                    print("Warning: received snapshot before initialization", file=sys.stderr)
                    continue
                # 處理快照
                session_id = message['sessionId']
                file_path = message['filePath']
                data_size = message['dataSize']
                seq_num = message['sequenceNumber']
                print(f"Received snapshot: {file_path} ({data_size} bytes)", file=sys.stderr)

                # 驗證 checksum（可選但建議）
                # checksum = message['checksum']
                # with open(file_path, 'rb') as f:
                #     if crc32(f.read()) != checksum: handle_error()

                # 發送 ACK
                ack = {
                    'type': 'ack',
                    'sessionId': session_id,
                    'sequenceNumber': seq_num,
                    'success': True
                }
                print(json.dumps(ack))
                sys.stdout.flush()

            elif msg_type == 'heartbeat':
                # 回應心跳
                response = {
                    'type': 'heartbeat_response',
                    'status': 'ok',
                    'timestamp': datetime.utcnow().isoformat() + 'Z'
                }
                print(json.dumps(response))
                sys.stdout.flush()

            elif msg_type == 'command':
                # 處理命令
                cmd_type = message.get('commandType')
                payload = message.get('commandPayload', {})
                print(f"Received command: {cmd_type}, payload: {payload}", file=sys.stderr)

            elif msg_type == 'session_closed':
                # 清理資源
                print(f"Session {message['sessionId']} closed", file=sys.stderr)

            elif msg_type == 'session_unbound':
                # Session 解除綁定（Session 仍存在，但不再綁定到此擴展）
                print(f"Session {message['sessionId']} unbound", file=sys.stderr)

            elif msg_type == 'shutdown':
                # 準備關閉
                print("Shutdown requested", file=sys.stderr)
                sys.exit(0)

        except json.JSONDecodeError as e:
            print(f"JSON parse error: {e}", file=sys.stderr)
        except Exception as e:
            print(f"Error: {e}", file=sys.stderr)

if __name__ == '__main__':
    main()

{
  "extensions": {
    "preview": {
      "command": {
        "type": "npx",
        "executable": "aspose-mcp-preview",
        "arguments": "--port 3000"
      },
      "inputFormats": ["png", "html", "pdf"],
      "supportedDocumentTypes": ["word", "excel", "powerpoint", "pdf"],
      "transportModes": ["stdin", "file", "mmap"],
      "preferredTransportMode": "stdin",
      "capabilities": {
        "supportsHeartbeat": true,
        "idleTimeoutMinutes": 0
      }
    }
  }
}