smart-sheet-mcp

v1.0.0

Published

8 months ago

智能表格添加记录功能的MCP服务

0High
0Medium
0Low

lewluo

smartsheet mcp model-context-protocol enterprise-wechat wechat-work

智能表格 MCP 服务

通过Model Context Protocol (MCP)协议暴露智能表格（Smartsheet）添加记录功能的服务。

功能概述

本服务封装了智能表格的"添加记录"API，通过MCP协议标准化接口，使开发者和AI客户端可以通过统一接口调用智能表格的添加记录能力。

核心功能

添加记录工具（addRecords）：向智能表格子表添加新记录
- 支持批量添加多条记录（单次最多40000条）
- 支持多种字段类型（文本、数字、日期等）
- 提供友好的错误处理和响应

安装与使用

作为NPM包使用

安装

npm install smart-sheet-mcp

使用方法

// 引入库
const { SmartsheetMcpService } = require('smart-sheet-mcp');
// 或者使用ES模块导入
// import { SmartsheetMcpService } from 'smart-sheet-mcp';

// 创建服务实例
const service = new SmartsheetMcpService({
  accessToken: '企业微信获取的access_token' // 可选，也可以通过环境变量设置
});

// 调用添加记录方法
async function addRecords() {
  try {
    const result = await service.addRecords({
      docid: '文档ID',
      sheet_id: '子表ID',
      records: [
        {
          values: {
            '标题': [{ type: 'text', text: '测试记录' }],
            '数量': [{ type: 'number', value: 100 }]
          }
        }
      ]
    });
    
    console.log('添加成功:', result);
  } catch (error) {
    console.error('添加失败:', error.message);
  }
}

addRecords();

TypeScript支持

import { SmartsheetMcpService, AddRecordsParams } from 'smart-sheet-mcp';

const params: AddRecordsParams = {
  docid: '文档ID',
  sheet_id: '子表ID',
  records: [
    {
      values: {
        '标题': [{ type: 'text', text: '测试记录' }]
      }
    }
  ]
};

const service = new SmartsheetMcpService({ accessToken: 'your_token' });
service.addRecords(params)
  .then(result => console.log(result))
  .catch(err => console.error(err));

作为独立服务使用

环境要求

Node.js >= 14.0.0
npm >= 6.0.0

安装依赖

npm install

配置环境变量

创建.env文件，配置必要的环境变量：

# 企业微信 Access Token
ACCESS_TOKEN=your_access_token_here

# 服务配置
PORT=3000
NODE_ENV=development

ACCESS_TOKEN 获取方法

ACCESS_TOKEN是企业微信智能表格API的访问凭证，获取方法如下：

登录企业微信管理后台
进入"应用管理" -> "自建应用"
创建或选择已有应用
在应用详情页获取"Secret"
使用Secret调用企业微信接口获取ACCESS_TOKEN：

curl -X GET "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=YOUR_CORPID&corpsecret=YOUR_SECRET"

返回结果示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "access_token": "accesstoken000001",
  "expires_in": 7200
}

注意：ACCESS_TOKEN有效期为7200秒（2小时），需要定期刷新。

构建项目

npm run build

运行服务

npm start

MCP服务调用方式

启动服务后，服务会监听标准输入输出（stdio）
通过MCP协议向服务发送请求，例如：

{
  "tool": "addRecords",
  "params": {
    "docid": "doc123456",
    "sheet_id": "sheet789",
    "records": [
      {
        "values": {
          "标题": [{ "type": "text", "text": "测试记录" }],
          "数量": [{ "type": "number", "value": 100 }]
        }
      }
    ]
  }
}

服务会返回标准化的响应：

{
  "content": [
    {
      "type": "text",
      "text": "添加成功，共添加 1 条记录，记录ID: rec_001"
    }
  ]
}

参数说明

addRecords方法/工具

| 参数名 | 类型 | 必填 | 说明 | | ---------- | -------- | ---- | ------------------------------------------------------------------------ | | docid | string | 是 | 文档ID，从智能表格URL中获取，例如：https://qy.weixin.qq.com/wedoc/sheet/doc123456 | | sheet_id | string | 是 | 子表ID，从智能表格URL中获取，例如：https://qy.weixin.qq.com/wedoc/sheet/doc123456/sheet789 | | key_type | string | 否 | 字段标识类型，可选值：CELL_VALUE_KEY_TYPE_FIELD_TITLE（默认）、CELL_VALUE_KEY_TYPE_FIELD_ID | | records | array | 是 | 记录数组，每个元素代表一条记录 | | values | object | 是 | 字段值映射，key为字段名/ID，value为字段值数组 |

字段值类型

| 类型 | 参数结构 | 说明 | | --------- | ------------------------------------ | ---------- | | 文本 | { type: 'text', text: string } | 文本类型 | | 数字 | { type: 'number', value: number } | 数字类型 | | 日期 | { type: 'date', timestamp: number} | 日期类型 | | 布尔 | { type: 'boolean', value: boolean} | 布尔类型 | | 人员 | { type: 'person', userid: string } | 人员类型 |

SmartsheetMcpService API

构造函数

constructor(options?: { accessToken?: string })

| 参数名 | 类型 | 必填 | 说明 | |------------|--------|------|------------------------------------------------| | accessToken | string | 否 | 企业微信ACCESS_TOKEN。如不提供，将尝试从环境变量读取 |

方法

addRecords

添加记录到智能表格。

async addRecords(params: AddRecordsParams): Promise<ApiResponse>

参数与返回值说明同上。

startServer

启动MCP服务器。

async startServer(): Promise<void>

此方法会启动一个MCP服务，监听标准输入输出。

服务打包方式比较

独立服务 vs NPM库

| 特性 | 独立服务 | NPM库 | |------|---------|-------| | 部署方式 | 需要单独部署和运行 | 作为依赖集成到项目中 | | 使用场景 | 适合作为独立服务供多个客户端调用 | 适合在特定项目中使用 | | 维护成本 | 需要单独维护和更新 | 随项目一起更新 | | 性能 | 可能有网络延迟 | 直接调用，无网络延迟 | | 安全性 | 需要单独管理ACCESS_TOKEN | ACCESS_TOKEN在项目内管理 |

测试

执行单元测试：

npm test

错误处理

服务会返回标准化的错误信息，常见错误码：

400 - 请求参数错误（如字段类型不匹配）
403 - 权限不足
404 - 文档或子表不存在
500 - 服务内部错误

协议与版本

MCP协议版本：v1.0+
TypeScript SDK版本：≥1.0.0