智能 MCP 服务器：Smartsheet 集成

项目概述

此项目提供了一个智能最小可行性产品 (MCP) 服务器，用于与 Smartsheet 集成，并支持通过 Claude for Desktop 进行交互。以下是项目的详细信息：

功能特性

核心功能

1. 直接 API 访问：通过 Smartsheet 直接 API 客户端实现对 Smartsheet 的操作。
2. 工具定义：在 src/index.ts 中定义 MCP 工具，支持多种操作如创建、读取、更新和删除数据。
3. 实用函数：提供通用操作的辅助函数，简化开发流程。

支持的操作

• 创建/读取/更新/删除 (CRUD)：对 Smartsheet 项目、任务、评论等进行 CRUD 操作。
• 复杂工作流：实现复杂的业务逻辑和自动化工作流。
• 数据导出与导入：支持数据的批量导出和导入功能。

快速开始

入门指南

1. 环境变量配置

   • 配置 SMARTSHEET_API_KEY 环境变量，用于 Smartsheet API 认证。
   • 可选：设置 ALLOW_DELETE_TOOLS 为 'true' 启用删除操作，默认禁用。

2. 安装依赖

   npm install
   

3. 运行开发环境

   npm run dev
   

4. 测试集成

   • 参考 Claude Desktop Quickstart 进行本地测试。
   • 使用 claude_desktop_config-example.json 作为配置模板，并根据需要调整环境变量。

项目结构

smartsheet-mcp/
├── src/
│   ├── index.ts                   # 主入口点和 MCP 工具定义
│   ├── smartsheet-direct-api.ts    # 直接 API 客户端实现
│   ├── smartsheet-utils.ts         # 公共辅助函数
│   ├── smartsheet-workflows.ts     # 复杂工作流实现
│   └── smartsheet-types.ts        # Smartsheet 对象类表示
├── tests/
│   ├── unit/                     # 单元测试文件
│   └── integration/              # 集成测试文件
├── scripts/                      # 工具脚本
├── examples/                     # 示例用法文件
├── .env                          # 环境变量配置文件
├── .env.example                 # 环境变量模板
└── claude_desktop_config-example.json # 示例 Claude Desktop 配置文件

文档与示例

示例代码

以下是一个使用 Smartsheet API 创建新项目的示例：

import { SmartsheetClient } from './src/smartsheet-direct-api';

const client = new SmartsheetClient(process.env.SMARTSHEET_API_KEY);

async function createProject() {
  const projectId = await client.createProject('My New Project');
  console.log(`Project created with ID: ${projectId}`);
}

createProject();

文档资源

• 官方文档：Smartsheet API 文档
• 项目 Wiki：查阅内部Wiki获取更多开发信息。
• 示例仓库：参考 examples/ 文件夹中的示例代码。

贡献指南

提交规范

遵循 Conventional Commits 规范，格式如下：

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

类型定义

• feat：新增功能（主版本号递增）
• fix：修复漏洞（补丁版本号递增）
• docs：文档更新
• style：代码格式调整
• refactor：代码重构，无新功能或修复
• perf：性能优化
• test：添加/修改测试用例
• chore：构建工具或其他辅助任务的调整

破坏性变更

通过在提交信息中添加 BREAKING CHANGE: 或在类型后加 ! 标记破坏性变更，例如：

feat!: 除过时 API 接口

开发流程

1. ** Fork 仓库**
2. ** 创建功能分支** (git checkout -b feature/amazing-feature)
3. ** 提交代码**：遵循提交规范进行 commits。
4. ** 提交 PR**：向主分支提交pull request，并附上详细说明。

许可证

项目使用 MIT License 开源协议，具体内容如下：

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

通过以上说明，您可以轻松上手并开始使用 Smartsheet MCP 服务器进行开发和集成。