Smar MCP

🚀 智能 MCP 服務器：Smartsheet 集成

本項目打造了一個智能最小可行性產品 (MCP) 服務器，可與 Smartsheet 無縫集成，還支持通過 Claude for Desktop 進行交互，為開發和集成工作提供了極大便利。

🚀 快速開始

入門指南

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 作為配置模板，並根據需要調整環境變量。

✨ 主要特性

核心功能

1. 直接 API 訪問：藉助 Smartsheet 直接 API 客戶端，可輕鬆實現對 Smartsheet 的操作。
2. 工具定義：在 src/index.ts 中定義 MCP 工具，支持創建、讀取、更新和刪除數據等多種操作。
3. 實用函數：提供通用操作的輔助函數，大大簡化開發流程。

支持的操作

• 創建/讀取/更新/刪除 (CRUD)：可對 Smartsheet 項目、任務、評論等進行 CRUD 操作。
• 複雜工作流：能夠實現複雜的業務邏輯和自動化工作流。
• 數據導出與導入：支持數據的批量導出和導入功能。

📦 安裝指南

環境變量配置

• 配置 SMARTSHEET_API_KEY 環境變量，用於 Smartsheet API 認證。
• 可選：設置 ALLOW_DELETE_TOOLS 為 'true' 啟用刪除操作，默認禁用。

安裝依賴

npm install

運行開發環境

npm run dev

💻 使用示例

基礎用法

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-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 文檔
• 項目 Wiki：查閱內部Wiki獲取更多開發信息。
• 示例倉庫：參考 examples/ 文件夾中的示例代碼。

📄 許可證

項目使用 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 服務器進行開發和集成。

🔧 貢獻指南

提交規範

遵循 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，並附上詳細說明。