JinDaGe - smartsheet-server MCP Details

article

README

🚀 智能服务器开发文档

智能服务器是一个高度模块化的系统，专为处理复杂的数据操作和业务逻辑而设计。它支持多种编程语言（包括TypeScript和Python）的开发，并通过统一协议与MCP（机器学习控制协议）进行通信。

✨ 主要特性

多语言支持：
- 支持TypeScript和Python代码。
- 提供跨语言数据转换模块。
扩展机制：
- 插件式架构，便于功能扩展。
- 灵活性高，可定制性强。
协议兼容性：
- 与MCP协议完全兼容。
- 支持多种通信模式（包括长连接和轮询）。
性能优化：
- 内置数据缓存机制。
- 高效的任务处理能力。
错误处理：
- 分层错误处理架构。
- 详细的错误日志记录。

🚀 快速开始

📦 安装

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

💻 使用示例

基础用法

创建新服务

创建一个新的TypeScript模块：

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

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

创建对应的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"
    }
  ]
}

启动服务：

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()

示例：计算器服务

创建TypeScript实现：

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

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

定义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"
    }
  ]
}

启动服务：

mcp-server calculator.json

示例：数据转换服务

创建TypeScript模块：

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

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

定义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"
    }
  ]
}

启动服务：

mcp-server data_converter.json

🔧 技术细节

开发

自动重建开发环境：

npm run watch

调试

由于MCP服务器通过标准输入和输出进行通信，调试可能具有挑战性。服务器实现了全面的错误日志记录，并通过MCP协议提供详细的错误信息。关键调试功能包括：

错误信息记录到标准错误流
详细的MCP响应中的错误信息
多级类型验证
全面的操作结果报告
依赖项分析用于列操作
公式引用跟踪

错误处理

服务器采用多层错误处理方法：

MCP层：
- 验证工具参数
- 处理协议级别的错误
- 提供格式化的错误响应
- 管理超时和重试
CLI层：
- 验证输入参数
- 处理命令行错误
- 生成用户友好的错误消息
业务逻辑层：
- 自定义错误处理
- 数据验证
- 错误传播机制

smartsheet-server