Smartsheet MCP Server

Smartsheet MCP 服务

一个模型上下文协议（MCP）服务，可与 Smartsheet 无缝集成，通过标准化接口在 Smartsheet 文档上执行自动化操作。该服务弥合了 AI 驱动的自动化工具与 Smartsheet 强大协作平台之间的差距。

概览

Smartsheet MCP 服务旨在促进与 Smartsheet 的智能交互，提供一套可靠的工具，用于文档管理、数据操作和列自定义。它是自动化工作流中的关键组件，使 AI 系统能够以编程方式与 Smartsheet 数据交互，同时保持数据完整性并强制执行业务规则。

主要优势

• 智能集成：将 AI 系统与 Smartsheet 协作平台无缝连接
• 数据完整性：在操作中强制执行验证规则并维护引用完整性
• 公式管理：自动保留并更新公式引用
• 灵活配置：支持各种列类型和复杂数据结构
• 错误恢复能力：在多个层级实现全面的错误处理和验证
• 医疗健康分析：针对临床和研究数据的专门分析能力
• 批处理：高效处理大型医疗健康数据集
• 自定义评分：为医疗健康项目和研究提供灵活的评分系统

使用场景

1. 临床研究分析

   • 方案合规性评分
   • 患者数据分析
   • 研究影响评估
   • 临床试验数据处理
   • 自动汇总研究笔记

2. 医院运营

   • 资源利用率分析
   • 患者满意度评分
   • 部门效率指标
   • 员工绩效分析
   • 质量指标追踪

3. 医疗健康创新

   • 儿科适配度评分
   • 创新影响评估
   • 研究优先级排序
   • 实施可行性分析
   • 临床价值评估

4. 自动化文档管理

   • 以编程方式修改工作表结构
   • 动态创建和管理列
   • 自动数据验证和格式设置

5. 数据操作

   • 通过完整性检查批量更新数据
   • 智能检测重复项
   • 感知公式的修改

6. 系统集成

   • AI 驱动的工作表自定义
   • 自动化报告工作流
   • 跨系统数据同步

集成点

该服务集成了：

• 用于数据操作的 Smartsheet API
• 用于标准化通信的 MCP 协议
• 通过 stdio 接口使用的本地开发工具
• 通过结构化日志对接的监控系统

功能

工具（34 个可用）

1. get_column_map（读取）

   • 从 Smartsheet 检索列映射和示例数据
   • 提供详细的列元数据，包括：
     • 列类型（系统列、公式、下拉列表）
     • 验证规则
     • 格式规范
     • 自动编号配置
   • 返回示例数据以提供上下文
   • 包含写入数据的使用示例

2. get_sheet_info（读取 - 别名）

   • get_column_map 的别名，功能完全相同
   • 保持与现有集成的向后兼容性

3. smartsheet_write（创建）

   • 向 Smartsheet 写入新行，并智能处理：
     • 系统管理的列
     • 多选选项列表值
     • 基于公式的列
   • 自动检测重复项
   • 将新行追加到工作表底部（现有条目之后）
   • 返回包含行 ID 的详细操作结果

4. smartsheet_update（更新）

   • 更新 Smartsheet 中的现有行
   • 支持部分更新（修改指定字段）
   • 通过验证维护数据完整性
   • 统一处理多选字段
   • 返回每行的成功／失败详情

5. smartsheet_delete（删除）

   • 删除 Smartsheet 中的行
   • 支持批量删除多行
   • 验证行是否存在及权限是否充足
   • 返回详细操作结果

6. smartsheet_search（搜索）

   • 跨工作表执行高级搜索
   • 支持多种搜索模式：
     • 支持正则表达式的文本搜索
     • 对 PICKLIST 列进行精确值匹配
     • 支持区分大小写和全词匹配选项
   • 支持按列搜索
   • 返回：
     • 匹配的行 ID（主要结果）
     • 详细的匹配信息
     • 搜索元数据和统计信息

7. smartsheet_add_column（列管理）

   • 向 Smartsheet 添加新列
   • 支持所有列类型：
     • TEXT_NUMBER
     • DATE
     • CHECKBOX
     • PICKLIST
     • CONTACT_LIST
   • 可配置选项：
     • 位置索引
     • 验证规则
     • 公式定义
     • 选项列表
   • 通过验证强制执行列数上限（400）
   • 返回详细的列信息

8. smartsheet_delete_column（列管理）

   • 检查依赖关系后安全删除列
   • 删除前验证公式引用
   • 防止删除在公式中使用的列
   • 返回详细的依赖关系信息
   • 支持强制删除选项

9. smartsheet_rename_column（列管理）

   • 重命名列，同时保留关联关系
   • 自动更新公式引用
   • 维护数据完整性
   • 验证名称是否唯一
   • 返回详细的更新信息

10. smartsheet_bulk_update（条件更新）

    • 根据规则执行条件批量更新
    • 支持复杂的条件评估：
      • 多种运算符（equals、contains、greaterThan 等）
      • 特定类型的比较（文本、日期、数字）
      • 空值／非空值检查
    • 支持配置批次大小的批处理
    • 全面的错误处理和回滚
    • 详细跟踪操作结果

11. get_all_row_ids（实用工具）

    • 获取 Smartsheet 中的所有行 ID
    • 适用于批量操作和数据分析
    • 返回完整的行标识符列表
    • 高效支持大型工作表

12. start_batch_analysis（医疗保健分析）

    • 使用 AI 分析整个工作表或选定的行
    • 支持多种分析类型：
      • 临床笔记摘要
      • 患者反馈情感分析
      • 医疗保健项目的自定义评分
      • 研究影响评估
    • 功能：
      • 自动批处理（每批 3 行，以实现最佳性能）
      • 进度跟踪和状态监控
      • 错误处理和详细报告
      • 通过 Azure OpenAI 自定义分析目标
      • 支持多个源列
      • 针对长文本进行令牌感知内容分块

13. get_job_status（分析监控）

    • 跟踪批量分析进度
    • 提供详细的任务统计信息：
      • 待处理行总数
      • 已处理行数
      • 失败行数
      • 处理时间戳
    • 实时状态更新
    • 全面的错误报告

14. cancel_batch_analysis（作业控制）

    • 取消正在运行的批量分析作业
    • 平稳终止进程
    • 保持数据一致性
    • 返回最终作业状态

15. list_workspaces（工作区管理）

    • 列出所有可访问的工作区
    • 返回工作区 ID、名称和永久链接
    • 包含访问级别信息
    • 支持发现组织范围内的工作区

16. get_workspace（工作区管理）

    • 获取工作区详细信息
    • 返回其中包含的工作表、文件夹、报告和仪表板
    • 提供访问级别和权限详细信息
    • 支持探索工作区内容

17. create_workspace（工作区管理）

    • 创建具有指定名称的新工作区
    • 返回新工作区 ID 和确认信息
    • 支持以编程方式组织工作区
    • 支持从已弃用的文件夹端点迁移

18. create_sheet_in_workspace（工作区管理）

    • 直接在工作区中创建新工作表
    • 支持所有列类型和配置
    • 返回新工作表 ID 和详细信息
    • 支持以编程方式创建和组织工作表

19. list_workspace_sheets（工作区管理）

    • 列出指定工作区中的所有工作表
    • 返回工作表 ID、名称和永久链接
    • 包含创建和修改时间戳
    • 支持发现工作区内容

20. smartsheet_upload_attachment（附件管理）

    • 将文件上传到工作表、行或评论
    • 支持多种附件类型并验证文件大小
    • 返回附件元数据和上传状态

21. smartsheet_get_attachments（附件管理）

    • 列出工作表或行的所有附件
    • 返回完整的附件元数据
    • 包含文件 URL、大小和创建者信息

22. smartsheet_download_attachment（附件管理）

    • 将指定附件下载到本地文件系统
    • 按需创建目录并验证下载内容
    • 返回下载状态和文件信息

23. smartsheet_delete_attachment（附件管理）

    • 从工作表中移除附件
    • 验证权限并返回删除状态

24. smartsheet_create_discussion（讨论管理）

    • 在工作表或行上创建新的讨论帖
    • 支持初始评论和可选标题
    • 返回讨论元数据和创建状态

25. smartsheet_add_comment（讨论管理）

    • 向现有讨论添加评论
    • 保持对话的线程结构
    • 返回评论详情和时间戳

26. smartsheet_get_discussions（讨论管理）

    • 列出工作表或行的所有讨论
    • 可选择在响应中包含所有评论
    • 返回讨论元数据和参与者信息

27. smartsheet_get_comments（讨论管理）

    • 获取指定讨论帖中的所有评论
    • 如有附件，则包含附件信息
    • 返回按时间顺序排列的评论记录

28. smartsheet_delete_comment（讨论管理）

    • 从讨论中删除指定评论
    • 删除前验证权限
    • 返回删除确认信息

29. smartsheet_get_cell_history（单元格历史记录与审计）

    • 获取单个单元格的修改历史记录
    • 包含用户归属信息和时间戳
    • 跟踪值变更、公式和格式

30. smartsheet_get_row_history（单元格历史记录与审计）

    • 获取整行的变更历史记录
    • 按时间顺序提供所有单元格变更记录
    • 支持按指定列筛选和生成完整审计记录

31. smartsheet_get_sheet_cross_references（跨工作表引用）

    • 分析工作表中的所有跨工作表引用
    • 识别引用其他工作表的公式
    • 详细分析公式模式和依赖关系

32. smartsheet_find_sheet_references（跨工作表引用）

    • 查找所有引用特定目标工作表的工作表
    • 搜索整个工作区或所有可访问的工作表
    • 全面的引用映射和影响分析

33. smartsheet_validate_cross_references（跨工作表引用）

    • 验证所有跨工作表引用，检查是否存在失效链接
    • 找出无法访问或已删除的被引用工作表
    • 为失效引用推荐替代工作表

34. smartsheet_create_cross_reference（跨工作表引用）

    • 创建 INDEX_MATCH、VLOOKUP、SUMIF、COUNTIF 公式
    • 以编程方式构建跨工作表引用公式
    • 支持自定义公式模板和多种公式类型

资源（4 个静态资源 + 5 个动态模板）

该服务同时提供静态资源和动态资源模板，以增强数据访问能力并提供上下文信息。

静态资源

1. smartsheet://templates/project-plan - 项目计划模板

   • 预先构建的项目计划模板，包含最佳实践
   • 提供适用于任务管理的优化列结构
   • 提供有关依赖关系和资源分配的指导

2. smartsheet://templates/task-tracker - 任务跟踪模板

   • 适用于团队协作的简单任务跟踪模板
   • 专注于进度监控，不包含复杂的依赖关系
   • 非常适合敏捷团队和简单工作流

3. smartsheet://schemas/column-types - 列类型参考

   • 完整介绍所有受支持的 Smartsheet 列类型
   • 包含各类型的 API 支持级别（完全支持、有限支持、只读）
   • 对于了解列的功能和限制至关重要

4. smartsheet://best-practices/formulas - 公式最佳实践

   • 常见公式模式和计算示例
   • 有关性能和可维护性的最佳实践
   • 跨工作表引用指南

动态资源模板

1. smartsheet://{sheet_id}/summary - 工作表摘要

   • 自动生成的摘要，包含关键指标和健康状态
   • 进度指标和完成情况统计
   • 对工作表数据进行实时分析

2. smartsheet://{sheet_id}/gantt-data - 甘特图数据

   • 标准化的甘特图数据格式，便于可视化
   • 针对项目管理工具优化的时间线数据
   • 依赖关系和关键路径信息

3. smartsheet://{workspace_id}/overview - 工作区概览

   • 全面的工作区内容概览
   • 以结构化格式展示所有工作表、报告和仪表板
   • 访问级别和组织层级

4. smartsheet://{sheet_id}/dependencies - 依赖关系图

   • 项目工作表的可视化依赖关系映射
   • 任务关系和关键路径分析
   • 瓶颈识别和优化建议

5. smartsheet://{sheet_id}/health-report - 工作表健康报告

   • 识别数据质量问题的健康分析
   • 检测缺失数据并识别失效公式
   • 优化机会和建议

提示词（6 个可用）

智能提示词模板，为常见的 Smartsheet 操作和分析提供引导式帮助。

1. create_project_plan - 项目计划创建指南

   • 按照最佳实践引导创建项目计划
   • 根据项目类型和工期提供模板建议
   • 提供工作分解结构建议

2. analyze_project_status - 项目健康度分析

   • 全面分析项目健康度并提供建议
   • 提供时间进度和资源利用率方面的洞察
   • 识别风险并提供缓解策略

3. optimize_workflow - 工作流优化

   • 提供改进工作表结构和工作流的建议
   • 发现自动化机会并提升效率
   • 提供改善用户体验的建议

4. generate_insights - 数据洞察提取

   • 从工作表数据中提取关键洞察和模式
   • 分析趋势并检测异常
   • 提供可操作的情报和决策支持

5. create_dashboard_summary - 高管仪表板创建

   • 根据多个工作表生成高管摘要
   • 跟踪高层级 KPI 并提供战略洞察
   • 提供面向领导层的报告和建议

6. setup_conditional_formatting - 条件格式设置指南

   • 逐步指导设置条件格式
   • 提供数据可视化最佳实践
   • 配置状态指示器和进度跟踪

主要功能

• 列类型管理

  • 处理系统列类型（AUTO_NUMBER、CREATED_DATE 等）
  • 支持公式解析和依赖关系跟踪
  • 管理选项列表和多选值
  • 提供全面的列操作（添加、删除、重命名）
  • 保留并更新公式引用

• 数据验证

  • 自动检测重复项
  • 验证列类型
  • 验证数据格式
  • 分析列依赖关系
  • 验证名称唯一性

• 搜索功能

  • 高级搜索功能
  • 类型感知搜索：
    • 对 PICKLIST 值进行精确匹配
    • 对文本字段进行模式匹配
    • 进行数值比较
  • 可配置的搜索选项：
    • 区分大小写
    • 全字匹配
    • 按列筛选
  • 全面的搜索结果：
    • 匹配行的 ID
    • 详细的匹配上下文
    • 搜索统计信息

• 元数据处理

  • 提取并处理列元数据
  • 处理验证规则
  • 管理格式规范
  • 跟踪公式依赖关系
  • 维护列之间的关系

• 医疗健康分析

  • 使用 Azure OpenAI 汇总临床笔记
  • 分析患者反馈情绪
  • 评估协议合规性
  • 评估研究影响
  • 分析资源利用率
  • 通过优化提示词生成进行自定义分析

• 批处理

  • 自动分批处理行（每批 3 行，以实现最佳性能）
  • 跟踪和监控进度
  • 错误处理和恢复
  • 可自定义的处理目标
  • 支持多列分析
  • 面向大文本的令牌感知内容分块
  • 使用 ThreadPoolExecutor 进行后台作业处理

• 作业管理

  • 实时状态监控
  • 详细的进度跟踪
  • 错误报告和日志记录
  • 支持取消作业
  • 批量操作控制

• 跨工作表引用

  • 公式分析和依赖关系映射
  • 检测并验证跨工作表引用
  • 识别失效链接并提供修复建议
  • 自动生成公式（INDEX_MATCH、VLOOKUP、SUMIF、COUNTIF）
  • 分析工作区中的引用影响
  • 支持自定义公式模板

设置

先决条件

• Node.js 和 npm
• Conda（用于环境管理）
• Smartsheet API 访问令牌
• Azure OpenAI API 访问权限（用于批量分析功能）

环境设置

1. 创建专用的 conda 环境：

conda create -n cline_mcp_env python=3.12 nodejs -y
conda activate cline_mcp_env

2. 安装 Node.js 依赖：

npm install

3. 安装 Python 依赖：

cd smartsheet_ops
pip install -e .
cd ..

注意：Python 软件包包含以下依赖：

• smartsheet-python-sdk - Smartsheet API 客户端
• python-dotenv - 环境变量管理
• openai - Azure OpenAI 集成
• tiktoken - AI 分析的令牌计数

4. 构建 TypeScript 服务：

npm run build

配置

该服务支持两种传输模式：

• STDIO 传输（默认）：用于本地开发和 CLI 使用
• HTTP 传输：用于基于 Web 的客户端和网络访问

1. 获取 Smartsheet API 密钥

1. 登录 Smartsheet
2. 前往 Account → Personal Settings → API Access
3. 生成新的访问令牌

2. 配置 STDIO 传输（Cline/本地）

配置路径取决于你的操作系统：

macOS：

~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Windows：

%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Linux：

~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "smartsheet": {
      "command": "/Users/[username]/anaconda3/envs/cline_mcp_env/bin/node",
      "args": [
        "/path/to/smartsheet-server/build/index.js",
        "--transport",
        "stdio"
      ],
      "env": {
        "PYTHON_PATH": "/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3",
        "SMARTSHEET_API_KEY": "your-api-key",
        "AZURE_OPENAI_API_KEY": "your-azure-openai-key",
        "AZURE_OPENAI_API_BASE": "your-azure-openai-endpoint",
        "AZURE_OPENAI_API_VERSION": "your-api-version",
        "AZURE_OPENAI_DEPLOYMENT": "your-deployment-name"
      },
      "disabled": false,
      "autoApprove": [
        "get_column_map",
        "smartsheet_write",
        "smartsheet_update",
        "smartsheet_delete",
        "smartsheet_search",
        "smartsheet_add_column",
        "smartsheet_delete_column",
        "smartsheet_rename_column",
        "smartsheet_bulk_update",
        "start_batch_analysis",
        "get_job_status",
        "cancel_batch_analysis",
        "get_all_row_ids",
        "list_workspaces",
        "get_workspace",
        "create_workspace",
        "create_sheet_in_workspace",
        "list_workspace_sheets"
      ]
    }
  }
}

3. 配置 HTTP 传输

对于基于 Web 的 MCP 客户端或网络访问，请使用 HTTP 传输模式：

启动服务：

# Start with default port (3000)
SMARTSHEET_API_KEY=your-api-key PYTHON_PATH=/path/to/python smartsheet-server --transport http

# Start with custom port
SMARTSHEET_API_KEY=your-api-key PYTHON_PATH=/path/to/python smartsheet-server --transport http --port 8080

客户端配置：

{
  "mcpServers": {
    "smartsheet-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-optional-auth-token"
      }
    }
  }
}

健康检查：

HTTP 服务提供健康检查端点：

curl http://localhost:3000/health
# Response: {"status":"ok","server":"smartsheet-mcp"}

启动服务

STDIO 传输（默认）

当 Cline 或 Claude Desktop 需要时，服务会自动启动。不过，你也可以手动启动以进行测试。

macOS/Linux：

# Activate the environment
conda activate cline_mcp_env

# Start with STDIO transport (default)
PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js

# Or explicitly specify STDIO transport
PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js --transport stdio

Windows：

:: Activate the environment
conda activate cline_mcp_env

:: Start with STDIO transport
set PYTHON_PATH=C:\Users\[username]\anaconda3\envs\cline_mcp_env\python.exe
set SMARTSHEET_API_KEY=your-api-key
node build\index.js --transport stdio

HTTP 传输

对于基于 Web 的客户端或网络访问：

macOS/Linux：

# Activate the environment
conda activate cline_mcp_env

# Start HTTP server on default port (3000)
PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js --transport http

# Start HTTP server on custom port
PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js --transport http --port 8080

Windows：

:: Activate the environment
conda activate cline_mcp_env

:: Start HTTP server
set PYTHON_PATH=C:\Users\[username]\anaconda3\envs\cline_mcp_env\python.exe
set SMARTSHEET_API_KEY=your-api-key
node build\index.js --transport http --port 3000

命令行选项

# View help
node build/index.js --help

# Available options:
--transport <type>    # "stdio" (default) or "http"
--port <number>       # HTTP port (default: 3000, only used with --transport http)
--help, -h            # Show help message

验证安装

STDIO 传输

1. 服务启动时应输出 "Smartsheet MCP server running on stdio"
2. 使用任意 MCP 工具（例如 get_column_map）测试连接

HTTP 传输

1. 服务启动时应输出 "Smartsheet MCP server running on HTTP port 3000"
2. 测试健康检查端点：curl http://localhost:3000/health
3. 预期响应：{"status":"ok","server":"smartsheet-mcp"}

Python 环境

检查 Python 环境是否已安装所需的软件包：

conda activate cline_mcp_env
pip show smartsheet-python-sdk openai tiktoken python-dotenv

Python 软件包应包含以下关键依赖：

• smartsheet-python-sdk>=2.105.1 - Smartsheet API 客户端
• openai>=1.0.0 - Azure OpenAI 集成
• tiktoken>=0.5.0 - AI 分析的令牌计数
• python-dotenv>=1.0.0 - 环境变量管理

使用示例

获取列信息（读取）

// Get column mapping and sample data
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_column_map",
  arguments: {
    sheet_id: "your-sheet-id",
  },
});

写入数据（创建）

// Write new rows to Smartsheet
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "smartsheet_write",
  arguments: {
    sheet_id: "your-sheet-id",
    column_map: {
      "Column 1": "1234567890",
      "Column 2": "0987654321",
    },
    row_data: [
      {
        "Column 1": "Value 1",
        "Column 2": "Value 2",
      },
    ],
  },
});

搜索数据

// Basic text search
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "smartsheet_search",
  arguments: {
    sheet_id: "your-sheet-id",
    pattern: "search text",
    options: {
      case_sensitive: false,
      whole_word: false,
      columns: ["Column1", "Column2"], // Optional: limit search to specific columns
    },
  },
});

// Search PICKLIST column with exact matching
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "smartsheet_search",
  arguments: {
    sheet_id: "your-sheet-id",
    pattern: "In Progress",
    options: {
      columns: ["Status"], // PICKLIST column
      case_sensitive: true,
      whole_word: true,
    },
  },
});

更新数据（更新）

// Update existing rows
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "smartsheet_update",
  arguments: {
    sheet_id: "your-sheet-id",
    column_map: {
      Status: "850892021780356",
      Notes: "6861293012340612",
    },
    updates: [
      {
        row_id: "7670198317295492",
        data: {
          Status: "In Progress",
          Notes: "Updated via MCP server",
        },
      },
    ],
  },
});

删除数据（删除）

// Delete rows from Smartsheet
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "smartsheet_delete",
  arguments: {
    sheet_id: "your-sheet-id",
    row_ids: ["7670198317295492", "7670198317295493"],
  },
});

医疗保健分析示例

// Example 1: Pediatric Innovation Scoring
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "start_batch_analysis",
  arguments: {
    sheet_id: "your-sheet-id",
    type: "custom",
    sourceColumns: ["Ideas", "Implementation_Details"],
    targetColumn: "Pediatric_Score",
    rowIds: ["row1", "row2", "row3"], // Optional: specify rows, or omit for all rows
    customGoal:
      "Score each innovation 1-100 based on pediatric healthcare impact. Consider: 1) Direct benefit to child patients, 2) Integration with pediatric workflows, 3) Implementation feasibility in children's hospital, 4) Safety considerations for pediatric use. Return only a number.",
  },
});

// Example 2: Clinical Note Summarization
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "start_batch_analysis",
  arguments: {
    sheet_id: "your-sheet-id",
    type: "summarize",
    sourceColumns: ["Clinical_Notes"],
    targetColumn: "Note_Summary",
    rowIds: ["row1", "row2"], // Optional: specify rows, or omit for all rows
  },
});

// Example 3: Patient Satisfaction Analysis
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "start_batch_analysis",
  arguments: {
    sheet_id: "your-sheet-id",
    type: "sentiment",
    sourceColumns: ["Patient_Feedback"],
    targetColumn: "Satisfaction_Score",
    rowIds: ["row1", "row2"], // Optional: specify rows, or omit for all rows
  },
});

// Example 4: Get All Row IDs for Batch Processing
const allRows = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_all_row_ids",
  arguments: {
    sheet_id: "your-sheet-id",
  },
});

// Example 5: Monitor Analysis Job Progress
const jobStatus = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_job_status",
  arguments: {
    sheet_id: "your-sheet-id",
    jobId: "job-uuid-from-start-analysis",
  },
});

工作区管理示例

// List all accessible workspaces
const workspaces = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "list_workspaces",
  arguments: {},
});

// Get details of a specific workspace
const workspace = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_workspace",
  arguments: {
    workspace_id: "6621332407379844",
  },
});

// Create a new workspace
const newWorkspace = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "create_workspace",
  arguments: {
    name: "Project Management",
  },
});

// Create a sheet in a workspace
const newSheet = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "create_sheet_in_workspace",
  arguments: {
    workspace_id: "6621332407379844",
    name: "Task Tracker",
    columns: [
      { title: "Task Name", type: "TEXT_NUMBER" },
      { title: "Due Date", type: "DATE" },
      {
        title: "Status",
        type: "PICKLIST",
        options: ["Not Started", "In Progress", "Completed"],
      },
    ],
  },
});

// List all sheets in a workspace
const sheets = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "list_workspace_sheets",
  arguments: {
    workspace_id: "6621332407379844",
  },
});

资源使用示例

// Access static resources
const projectTemplate = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://templates/project-plan",
});

const columnTypes = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://schemas/column-types",
});

const formulaGuide = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://best-practices/formulas",
});

// Access dynamic resources
const sheetSummary = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://8596778555232132/summary",
});

const ganttData = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://8596778555232132/gantt-data",
});

const workspaceOverview = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://6621332407379844/overview",
});

const dependencyMap = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://8596778555232132/dependencies",
});

const healthReport = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://8596778555232132/health-report",
});

提示词使用示例

// Project plan creation guidance
const projectPlanPrompt = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_prompt",
  arguments: {
    name: "create_project_plan",
    arguments: {
      project_name: "Website Redesign",
      project_type: "software",
      duration_estimate: "3 months",
    },
  },
});

// Project health analysis
const analysisPrompt = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_prompt",
  arguments: {
    name: "analyze_project_status",
    arguments: {
      sheet_id: "8596778555232132",
      focus_area: "timeline",
    },
  },
});

// Workflow optimization suggestions
const optimizationPrompt = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_prompt",
  arguments: {
    name: "optimize_workflow",
    arguments: {
      sheet_id: "8596778555232132",
      workflow_type: "approval",
    },
  },
});

// Data insights extraction
const insightsPrompt = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_prompt",
  arguments: {
    name: "generate_insights",
    arguments: {
      sheet_id: "8596778555232132",
      insight_type: "bottlenecks",
    },
  },
});

// Executive dashboard creation
const dashboardPrompt = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_prompt",
  arguments: {
    name: "create_dashboard_summary",
    arguments: {
      workspace_id: "6621332407379844",
      summary_focus: "risks",
    },
  },
});

// Conditional formatting setup
const formattingPrompt = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_prompt",
  arguments: {
    name: "setup_conditional_formatting",
    arguments: {
      sheet_id: "8596778555232132",
      formatting_goal: "status indicators",
    },
  },
});

开发

启用自动重新构建进行开发：

npm run watch

CI/CD 流水线

本项目通过 GitHub Actions 实现了全面的 8 阶段 CI/CD 流水线，确保所有组件的代码质量、安全性和可靠性。

流水线架构

CI/CD 流水线由 8 个协同作业组成，这些作业以并行和串行方式运行，以实现最佳效率：

1. TypeScript 质量检查 - ESLint、类型检查、格式验证
2. Python 质量检查 - Black、Flake8、MyPy 类型检查
3. TypeScript 测试 - 在 Node.js 16、18、20 上进行矩阵测试，并收集覆盖率
4. Python 测试 - 在 Python 3.8、3.9、3.10、3.11 上进行矩阵测试，并收集覆盖率
5. 合并覆盖率 - 统一覆盖率报告并集成 Codecov
6. 集成测试 - 端到端验证和 MCP 服务启动验证
7. 安全扫描 - npm audit、Python safety、Bandit 安全分析
8. 构建和打包 - 创建构件并验证部署

流水线核心功能

质量保证：

• 多语言支持：全面覆盖 TypeScript 和 Python 流水线
• 矩阵测试：验证跨平台兼容性
• 代码质量门禁：ESLint、Black、Flake8、MyPy、TypeScript 严格模式
• 覆盖率管控：自动验证覆盖率阈值
• 安全扫描：使用 safety 和 Bandit 定期评估漏洞

性能优化：

• 并行执行：独立作业并发运行，加快反馈
• 智能缓存：跨运行缓存 Node 模块和 Python 依赖项
• 条件执行：仅在 PR 上运行性能测试，在 main 上运行完整覆盖率测试
• 制品管理：构建制品保留 7-30 天

集成和部署：

• MCP 协议验证：测试服务启动和协议合规性
• Docker 支持：多平台容器构建（linux/amd64、linux/arm64）
• 自动发布：按版本标签发布，并生成变更日志
• 依赖项管理：每周安全审计和自动更新

工作流触发条件

# Comprehensive testing on main branches
- push: [main, develop]
- pull_request: [main, develop]

# Additional workflows
- release: version tags (v*.*.*)
- security: weekly dependency scans
- performance: PR-specific testing

状态监控

该流水线提供全面的通知和制品管理，确保所有相关人员都能了解构建状态、测试结果和部署准备情况。

测试与质量保证

本项目通过自动化 CI/CD 流水线，为 TypeScript 和 Python 组件提供全面的测试覆盖率和质量保证。

测试基础设施

测试状态：54/54 个 TypeScript 测试通过，5/5 个 Python 测试通过

我们的全面测试策略包括：

• 单元测试：TypeScript 使用 Jest（54 个测试），Python 使用 pytest（5 个核心测试）
• 集成测试：跨组件测试和 MCP 协议验证
• 代码质量：ESLint、TypeScript 检查、Black、Flake8、MyPy
• 安全扫描：npm audit、Python safety 检查、Bandit 分析
• 覆盖率分析：结合 Codecov 集成生成覆盖率报告
• 性能测试：启动时间测量和基准跟踪

测试覆盖率概览

当前覆盖率指标：

• TypeScript 覆盖率：全面覆盖 MCP 服务实现
• Python 覆盖率：核心操作和 CLI 功能
• 综合报告：统一分析两种语言的覆盖率
• 自动跟踪：通过 Codecov 实时监控覆盖率

快速测试命令

# Essential testing commands for daily development
npm run ci:check          # Pre-commit validation (recommended before push)
npm run test:all          # Run all tests with coverage
npm run coverage          # Full coverage analysis with combined reporting
npm run coverage:open     # View coverage reports in browser

# Individual test suites
npm test                  # TypeScript tests only
npm run test:python       # Python tests only
npm run test:coverage     # TypeScript with coverage
npm run test:python:coverage  # Python with coverage

# Development testing
npm run test:watch        # Watch mode for continuous testing
npm run coverage:clean    # Coverage without external uploads

全面测试命令

# Quality assurance
npm run lint              # ESLint for TypeScript
npm run lint:fix          # Auto-fix linting issues
npm run format            # Prettier code formatting
npm run typecheck         # TypeScript type validation

# Coverage and reporting  
npm run badges:update     # Generate coverage badges
npm run coverage:ci       # CI-optimized coverage reporting
npm run coverage:view     # Open all coverage reports
npm run coverage:combined # View combined coverage report

# Build and validation
npm run build             # Build TypeScript
npm run watch             # Development build with watch
npm run inspector         # MCP inspector for tool testing

测试报告和制品

运行测试后，可查看详细报告：

• TypeScript 覆盖率：./coverage/index.html
• Python 覆盖率：./smartsheet_ops/coverage/index.html
• 综合覆盖率：./coverage-combined/index.html
• 测试制品：可在 CI/CD 流水线运行记录中查看

质量阈值

本项目执行严格的质量标准：

• TypeScript 覆盖率：最低 60%（可按组件配置）
• Python 覆盖率：总体达到 80%，并提供逐行报告
• 代码质量：ESLint 规则、TypeScript 严格模式、Python Black/Flake8
• 安全性：定期进行依赖项审计和漏洞扫描
• 性能：监控启动时间并检测回归

Docker 支持

构建并运行容器化版本：

# Build Docker image
docker build -t smartsheet-server .

# Run with environment variables
docker run -e SMARTSHEET_API_KEY=your_key -e PYTHON_PATH=/usr/local/bin/python smartsheet-server

调试

由于 MCP 服务通过 stdio 通信，调试可能颇具挑战。服务实现了全面的错误日志记录，并通过 MCP 协议提供详细的错误消息。

主要调试功能：

• 将错误记录到 stderr
• 在 MCP 响应中提供详细的错误消息
• 在多个层级进行类型验证
• 全面报告操作结果
• 分析列操作的依赖关系
• 跟踪公式引用

错误处理

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

1. MCP 层

   • 验证工具参数
   • 处理协议级错误
   • 提供格式化的错误响应
   • 管理超时和重试

2. CLI 层

   • 验证命令参数
   • 处理执行错误
   • 将错误消息格式化为 JSON
   • 验证列操作

3. 操作层

   • 处理 Smartsheet API 错误
   • 验证数据类型和格式
   • 提供详细的错误上下文
   • 管理列依赖关系
   • 验证公式引用
   • 确保数据完整性

贡献

欢迎贡献！请确保：

1. TypeScript/Python 代码遵循现有风格
2. 新功能包含适当的错误处理
3. 更改保持向后兼容
4. 更新包含适当的文档
5. 列操作保持数据完整性
6. 妥善处理公式引用