smart-sheet-mcp/README.md

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

# 智能表格 MCP 服务

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

## 功能概述

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

### 核心功能

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

## 安装与使用

### 作为NPM包使用

#### 安装

```bash
npm install smart-sheet-mcp
```

#### 使用方法

```javascript
// 引入库
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支持

```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

#### 安装依赖

```bash
npm install
```

#### 配置环境变量

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

```
# 企业微信 Access Token
ACCESS_TOKEN=your_access_token_here

# 服务配置
PORT=3000
NODE_ENV=development
```

#### ACCESS_TOKEN 获取方法

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

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



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

返回结果示例：
```json
{
  "errcode": 0,
  "errmsg": "ok",
  "access_token": "accesstoken000001",
  "expires_in": 7200
}
```

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

#### 构建项目

```bash
npm run build
```

#### 运行服务

```bash
npm start
```

### MCP服务调用方式

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

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

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

```json
{
  "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

### 构造函数

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

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

### 方法

#### addRecords

添加记录到智能表格。

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

参数与返回值说明同上。

#### startServer

启动MCP服务器。

```typescript
async startServer(): Promise<void>
```

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

## 服务打包方式比较

### 独立服务 vs NPM库

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

### 推荐使用场景

- **独立服务**：适合以下场景
  - 需要为多个客户端提供统一接口
  - 需要集中管理ACCESS_TOKEN
  - 需要独立扩展和维护

- **NPM库**：适合以下场景
  - 在特定项目中使用智能表格功能
  - 需要更灵活的定制和扩展
  - 希望减少部署复杂度

## 测试

执行单元测试：

```bash
npm test
```

## 错误处理

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

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

## 协议与版本

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