Smartsheet MCP Server

Smartsheet MCP サーバー

Smartsheet とシームレスに連携し、標準化されたインターフェースを通じて Smartsheet ドキュメントの操作を自動化する Model Context Protocol（MCP）サーバーです。このサーバーは、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 分析を使用して、シート全体または選択した行を処理します
    • 複数の分析タイプに対応します。
      • 臨床ノートの要約
      • 患者フィードバックの感情分析
      • ヘルスケア施策向けのカスタムスコアリング
      • 研究インパクトの評価
    • 主な機能：
      • バッチの自動処理（最適なパフォーマンスのため、1 バッチあたり 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 を使用した臨床記録の要約
  • 患者フィードバックの感情分析
  • プロトコル遵守度のスコアリング
  • 研究への影響の評価
  • リソース活用状況の分析
  • 最適化されたプロンプト生成によるカスタム分析

• バッチ処理

  • 行の自動バッチ処理（最適なパフォーマンスを実現するため、1 バッチあたり 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

設定

このサーバーでは、次の 2 つのトランスポートモードをサポートしています。

• STDIO トランスポート（デフォルト）：ローカル開発および CLI での使用向け
• HTTP トランスポート：ウェブベースのクライアントおよびネットワークアクセス向け

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 トランスポートを設定する

ウェブベースの 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 トランスポート

ウェブベースのクライアントまたはネットワークアクセス向け：

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 の両方のコンポーネントに対する包括的なテストカバレッジと品質保証を維持しています。

テストインフラストラクチャ

テスト状況：TypeScript テスト 54/54 件合格、Python テスト 5/5 件合格

包括的なテスト戦略には、以下が含まれます。

• 単体テスト：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. 数式参照が適切に処理されること