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. 业务逻辑层：
   • 自定义错误处理
   • 数据验证
   • 错误传播机制