Smartsheet Server

🚀 智能服務器開發文檔

智能服務器是一個高度模塊化的系統，專為處理複雜的數據操作和業務邏輯而設計。它支持多種編程語言（包括TypeScript和Python）的開發，並通過統一協議與MCP（機器學習控制協議）進行通信。

✨ 主要特性

1. 多語言支持：
   • 支持TypeScript和Python代碼。
   • 提供跨語言數據轉換模塊。
2. 擴展機制：
   • 插件式架構，便於功能擴展。
   • 靈活性高，可定製性強。
3. 協議兼容性：
   • 與MCP協議完全兼容。
   • 支持多種通信模式（包括長連接和輪詢）。
4. 性能優化：
   • 內置數據緩存機制。
   • 高效的任務處理能力。
5. 錯誤處理：
   • 分層錯誤處理架構。
   • 詳細的錯誤日誌記錄。

🚀 快速開始

📦 安裝

npm install mcp-server --save
pip install mcp-server

💻 使用示例

基礎用法

創建新服務

1. 創建一個新的TypeScript模塊：

// Calculator.ts
export class Calculator {
    add(a: number, b: number): number {
        return a + b;
    }

    multiply(a: number, b: number): number {
        return a * b;
    }
}

2. 創建對應的MCP配置文件：

// calculator.json
{
  "name": "Calculator",
  "description": "Basic arithmetic operations.",
  "operations": [
    {
      "name": "add",
      "parameters": [
        { "type": "number", "name": "a" },
        { "type": "number", "name": "b" }
      ],
      "returns": "number"
    },
    {
      "name": "multiply",
      "parameters": [
        { "type": "number", "name": "a" },
        { "type": "number", "name": "b" }
      ],
      "returns": "number"
    }
  ]
}

3. 啟動服務：

mcp-server calculator.json

高級用法

批處理

服務器支持通過batchSize參數進行批量處理，默認為500。例如：

const result = await mcpClient.processBatch(batchData, {
  batchSize: 100,
  lenientMode: true
});

多線程支持

Python版本支持多線程處理，通過配置threadCount參數可以控制線程數量：

from mcp_server import Server

server = Server(thread_count=5)
server.start()

示例：計算器服務

1. 創建TypeScript實現：

class Calculator {
    add(a: number, b: number): number {
        return a + b;
    }

    multiply(a: number, b: number): number {
        return a * b;
    }
}

2. 定義MCP配置文件：

{
  "name": "Calculator",
  "description": "Basic arithmetic operations.",
  "operations": [
    {
      "name": "add",
      "parameters": [
        { "type": "number", "name": "a" },
        { "type": "number", "name": "b" }
      ],
      "returns": "number"
    },
    {
      "name": "multiply",
      "parameters": [
        { "type": "number", "name": "a" },
        { "type": "number", "name": "b" }
      ],
      "returns": "number"
    }
  ]
}

3. 啟動服務：

mcp-server calculator.json

示例：數據轉換服務

1. 創建TypeScript模塊：

class DataConverter {
    toUpperCase(str: string): string {
        return str.toUpperCase();
    }

    reverseString(str: string): string {
        return str.split('').reverse().join('');
    }
}

2. 定義MCP配置文件：

{
  "name": "DataConverter",
  "description": "String manipulation operations.",
  "operations": [
    {
      "name": "toUpperCase",
      "parameters": [
        { "type": "string", "name": "str" }
      ],
      "returns": "string"
    },
    {
      "name": "reverseString",
      "parameters": [
        { "type": "string", "name": "str" }
      ],
      "returns": "string"
    }
  ]
}

3. 啟動服務：

mcp-server data_converter.json

🔧 技術細節

開發

自動重建開發環境：

npm run watch

調試

由於MCP服務器通過標準輸入和輸出進行通信，調試可能具有挑戰性。服務器實現了全面的錯誤日誌記錄，並通過MCP協議提供詳細的錯誤信息。 關鍵調試功能包括：

• 錯誤信息記錄到標準錯誤流
• 詳細的MCP響應中的錯誤信息
• 多級類型驗證
• 全面的操作結果報告
• 依賴項分析用於列操作
• 公式引用跟蹤

錯誤處理

服務器採用多層錯誤處理方法：

1. MCP層：
   • 驗證工具參數
   • 處理協議級別的錯誤
   • 提供格式化的錯誤響應
   • 管理超時和重試
2. CLI層：
   • 驗證輸入參數
   • 處理命令行錯誤
   • 生成用戶友好的錯誤消息
3. 業務邏輯層：
   • 自定義錯誤處理
   • 數據驗證
   • 錯誤傳播機制