Sai MCP

🚀 使用 WebAssembly Go 實現的 SAI MCP 服務器

本項目藉助 WebAssembly，採用 Go 語言實現了一個管理控制協議（MCP）服務器。該服務器可執行 "sai" 命令，處理其輸出與退出碼，且與 wpcli 框架兼容。

🚀 快速開始

SAI MCP 服務器是一個 WebAssembly 模塊，為從 JavaScript 執行 SAI 命令行工具提供了接口。其主要功能如下：

1. 執行帶有指定參數的 "sai" 命令。
2. 分別捕獲標準輸出（stdout）、標準錯誤輸出（stderr）和退出碼。
3. 解析輸出格式（支持 YAML、JSON 或純文本）。
4. 將結構化結果返回至 JavaScript 環境。

✨ 主要特性

• 提供從 JavaScript 執行 SAI 命令的接口。
• 能分別捕獲命令的 stdout、stderr 和退出碼。
• 支持解析多種輸出格式（YAML、JSON、純文本）。
• 與 wpcli 框架兼容。

📦 安裝指南

構建 WebAssembly 模塊

要構建 WebAssembly 模塊，可使用以下命令：

GOOS=js GOARCH=wasm go build -o sai_mcp.wasm ./cmd/main

此命令將生成一個 WebAssembly 文件（sai_mcp.wasm），該文件可由 wpcli 框架加載。

與 wpcli 集成

若要與 wpcli 框架集成，可按以下步驟操作：

1. 將 WebAssembly 模塊放置在合適的插件目錄中。
2. 創建一個定義可用命令的配置文件。
3. 將插件註冊到 wpcli 框架。

示例配置如下：

name: sai
description: SAI 命令行工具集成
uuid: sai-plugin-uuid
versions:
  - version: 1.0.0
    wasm: sai_mcp.wasm
    conf: sai_config.yaml
commands:
  - name: install
    description: 安裝軟件
    usage: install <software> [options]
    args:
      - name: software
        type: string
        description: 要安裝的軟件名稱
        required: true
  # 其他命令...

💻 使用示例

基礎用法

以下是從 JavaScript 執行 SAI 命令的示例：

// 執行 SAI 命令
const result = executeSai("install", "nginx");

// 檢查結果
console.log("退出碼:", result.exitCode);
console.log("輸出:", result.stdout);
if (result.stderr) {
  console.error("錯誤:", result.stderr);
}

// 如果有解析的輸出則訪問
if (result.parsedOutput) {
  console.log("解析的輸出:", result.parsedOutput);
}

📚 詳細文檔

項目結構

sai_mcp/
├── cmd/
│   └── main/
│       ├── main.go           # WebAssembly 入口點和 JavaScript 接口
│       ├── sai_executor.go   # SAI 命令執行邏輯
│       ├── parser.go         # 輸出格式解析（YAML、JSON）
│       └── main_test.go      # 實現的測試用例
└── go.mod                    # Go 模塊定義

實現細節

WebAssembly 接口

WebAssembly 模塊暴露了一個 JavaScript 函數 executeSai，該函數接受命令參數，並返回一個包含以下屬性的對象：

• stdout：標準輸出。
• stderr：標準錯誤輸出。
• exitCode：退出碼（0 表示成功，非零表示錯誤）。
• parsedOutput：（可選）若檢測到格式，則解析輸出。
• format：（可選）檢測到的輸出格式（json、yaml、文本）。

SAI 命令執行

SaiExecutor 組件負責實際執行 SAI 命令，具體操作如下：

• 為 SAI 命令創建新進程。
• 分別捕獲 stdout 和 stderr。
• 從進程提取退出碼。
• 妥善處理執行錯誤。

輸出解析

本項目實現了針對不同輸出格式的解析器：

• JSON：將 JSON 輸出解析為結構化對象。
• YAML：將 YAML 輸出解析為結構化對象。
• 文本：將純文本作為原始文本返回。

輸出格式會基於命令和輸出內容自動檢測。

錯誤處理

本實現處理了多種錯誤場景：

• 命令未找到：在 stderr 中返回適當的錯誤，並使用非零退出碼。
• 命令執行失敗：捕獲錯誤消息，並在 stderr 中返回實際退出碼。
• 輸出解析錯誤：忽略無法解析的輸出。

🔧 技術細節

術語表

1. WebAssembly：一種二進制指令格式，可在瀏覽器和非瀏覽器環境中以近似於 C++ 等效的速度運行。
2. Go：由 Google 開發的開源編程語言，注重效率、安全性和可維護性。
3. MCP 協議：管理控制協議，用於管理和控制分佈式系統中的組件。
4. wpcli：一個用於構建和管理命令行界面的 PHP 庫。

通過上述實現，藉助 WebAssembly 和 Go 的結合，可為 SAI 命令提供高效的執行和管理。