mcp-server-smartsheet-rm

📋 mcp-server-smartsheet-rm

Resource Management by Smartsheet（10,000ft API）向けのエンタープライズ Model Context Protocol（MCP）サーバーです。

AI コーディングエージェント、プランナー、アシスタント（Claude、Cortex、Antigravity、VS Code）から Smartsheet RM のパブリック REST API を利用できます。時間の記録とタイムシートの照合、リソースのスケジュール設定と割り当て、キャパシティプランニング、プロジェクトとフェーズの管理、休暇・休日の管理、経費の追跡、カスタムフィールドに対応しています。

---

🏗️ システムアーキテクチャ

graph TD
    Client["AI Agent (Claude / Cortex / Antigravity / Cursor)"] -->|"MCP Stdio / Streamable HTTP /mcp"| Server["Root Gateway create_server()"]
    Server --> Middle["Parent Middleware (ParentAudit / ReadOnly Gate)"]
    Middle --> SubTime["time namespace (time_* — 17 tools, incl. 1 bulk-gated)"]
    Middle --> SubProj["projects namespace (projects_* — 27 tools, incl. 1 bulk-gated)"]
    Middle --> SubAdmin["admin namespace (admin_* — 60 tools)"]
    SubTime --> Guards["Domain Guards"]
    SubProj --> Guards
    SubAdmin --> Guards
    Guards --> ClientPool["SmartsheetRMClient (httpx.AsyncClient Pool)"]
    ClientPool -->|"auth header + 429 Jitter Retry"| API["Smartsheet RM (10,000ft API)"]

create_server は FastMCP 4 の namespace= を使用して、時間、プロジェクト、管理の各サブサーバーをマウントします。そのため、tools/list の名前は time_*、projects_*、admin_* になります。従来の rm_* 名はゲートウェイに登録されません。

---

🚀 FastMCP 4 サーバーの構成

• ドメインのマウント（root.mount(..., namespace=...)）：
  • namespace="time" → time_*（17 個のツール。バルク操作ゲートで制限される time_bulk_delete_time_entries を含みます）。
  • namespace="projects" → projects_*（27 個のツール。バルク操作ゲートで制限される projects_bulk_delete_assignments を含みます）。
  • namespace="admin" → admin_*（60 個のツール）。
• 階層型ミドルウェア：
  • 親：ParentAuditMiddleware（処理時間、ライフサイクルログ、シークレットの秘匿）と ReadOnlyGateMiddleware（アノテーションに基づく読み取り専用ゲート。詳細は以下を参照）。
  • 子：TimeDomainGuardMiddleware（記録時間は 0～24 時間。バルク操作ゲートあり）、ProjectsDomainGuardMiddleware（プロジェクト名は空欄不可。バルク操作ゲートあり）、AdminDomainGuardMiddleware（per_page は 1000 以下である必要があります）。

プロファイル

--profile または SMARTSHEET_RM_PROFILE でプロファイルを選択します（デフォルトは full）。不明なプロファイル名を指定すると、起動時に ValueError が発生します。プロファイルには2種類あります。

• ドメインマウント型プロファイルは、ドメイン全体をマウントします。full、time、projects、admin、readonly があります。
• ジョブ型プロファイルは、すべてのドメインをマウントしたうえで、1つのジョブ用に明示されたツール名のリストだけを公開します。プロンプトとリソースは、すべてのジョブ型プロファイルと readonly で引き続き利用できます。ドメインマウント型プロファイルの time、projects、admin では、それぞれのドメインのプロンプトとリソースのみを利用できます。サーバーのビルド時に、リスト内の各名前が完全なカタログに照合されるため、誤記があると起動時に失敗します。

プロファイル	対象とするジョブ	ツール	SMARTSHEET_RM_READONLY=1 の場合
full	省略なしの完全なカタログです。一括処理ツールも一覧に含まれますが、SMARTSHEET_RM_ALLOW_BULK_DESTRUCTIVE=1 が設定されていない限り、呼び出し時に拒否されます。Tool Search と Code Mode はこのプロファイルでのみ有効です。	104	39
time	時間記録、承認、タイムシートのレシピ（time ドメイン）。	17	4
projects	プロジェクト、フェーズ、アサインメント、プレースホルダー、サブタスク（projects ドメイン）。	27	10
admin	ユーザー、組織の参照データ、クライアント、経費、フィールド、レポート、ウェブフック（admin ドメイン）。	60	25
readonly	副作用を起こさずに確認できます。readOnlyHint=True と注釈されたすべてのツールを利用できます。	39	39
timesheets	チームメンバーまたはマネージャーが、アサインメントに基づいて週次の時間を記録、修正、提出、ロック、承認します。	24	12
staffing	リソースマネージャーが空き状況と稼働率を確認し、アサインメント、プレースホルダー、サブタスクを作成または調整します。	27	18
org_setup	リソース管理の管理者が、メンバーのオンボーディングを行い、組織の参照データ、カスタムフィールド定義、ユーザーのステータス、ウェブフックを管理します。	35	13
portfolio	PMO がプロジェクト、フェーズ、クライアント、経費、プロジェクトメタデータを設定・管理し、予算とレポートの合計値を確認します。	33	18

どのジョブ型プロファイルにも含まれないツールが7つあり、full（または対応するドメインマウント型プロファイル）でのみ利用できます。time_bulk_delete_time_entries、projects_bulk_delete_assignments、admin_delete_client、admin_delete_client_contact、admin_create_expense_category、admin_delete_expense_category、admin_delete_tag です。

読み取り専用の動作

• ツールが読み取り専用かどうかは、MCP の readOnlyHint 注釈のみで判断されます。すべてのツールに明示的な注釈があり、読み取り専用の39個には true、書き込み用の65個には false が設定されています。注釈がない場合、または readOnlyHint がない場合、そのツールは書き込み用として扱われます。
• --profile readonly または SMARTSHEET_RM_READONLY=1（どのプロファイルでも設定可能）を指定すると、読み取り専用ツールのみが一覧表示されます。さらに ReadOnlyGateMiddleware は、フィルターで非表示になった書き込みツールも含め、読み取り専用ではない実際のツールへの呼び出しを拒否します。拒否された場合、isError: true を含むツール結果が返されます。
• サーバー上に存在しない名前を指定すると、直接呼び出した場合も call_tool 経由の場合も、FastMCP の通常の Unknown tool エラーが返されます。そのため、誤記がブロックされたツールとして報告されることはありません。
• Tool Search が有効な場合、ゲートは call_tool がラップするツールを確認します。call_tool 経由の読み取りは実行され、書き込みは拒否されます。Tool Search が無効な場合、call_tool はサーバー上のツールではないため、呼び出すと Unknown tool: 'call_tool' が返されます。
• ゲートがサービングサーバーを確認できない場合、呼び出しは拒否されます。

一括処理のゲート

time_bulk_delete_time_entries と projects_bulk_delete_assignments は、full、time、projects に一覧表示されます。ドメインガードは、SMARTSHEET_RM_ALLOW_BULK_DESTRUCTIVE=1 が設定されていない限り、呼び出し時にこれらを拒否します（isError: true）。また、ハンドラーでは引き続き confirm=True が必要です。読み取り専用モードでは、これらのツールは非表示になり、呼び出しも拒否されます。

ツール検索とコードモード

tools/list はデフォルトでフラットです。検出機能はオプトインで、full の場合のみ有効になります。

• --enable-tool-search / SMARTSHEET_RM_ENABLE_TOOL_SEARCH=1 を指定すると、tools/list が search_tools と call_tool に置き換わります。バックエンドは regex（デフォルト）または bm25（--tool-search-backend / SMARTSHEET_RM_TOOL_SEARCH_BACKEND）です。
• --enable-code-mode / SMARTSHEET_RM_ENABLE_CODE_MODE=1 を指定すると、FastMCP の実験的なコードモード（search、get_schema、execute）が追加されます。コードモードには、パッケージの code-mode エクストラ（pydantic-monty を含む fastmcp[code-mode]）によって提供されるサンドボックスが必要です。pip install "mcp-server-smartsheet-rm[code-mode]" または uvx --from "mcp-server-smartsheet-rm[code-mode]" smartsheet-rm-mcp --enable-code-mode を実行してください。これがない場合、警告を表示してコードモードをスキップし、フラットなカタログを提供します。
• 両方を有効にすると ValueError が発生します。別のプロファイルでいずれかを要求すると、警告をログに記録し、フラットなリストを維持します。
• search_tools、search、get_schema はカタログのみを読み取り、readOnlyHint=True として注釈されています。読み取り専用モードでは、コードモードの execute は拒否されます。

---

⚡ ツール概要

このサーバーは、プロジェクト、リソース、タイムシート、キャパシティを扱うツールを提供します。以下の名前空間付きの名前を呼び出してください。

• デフォルト登録：full では 104 個のツールが利用できます（破壊的な一括操作ツール 2 個は一覧に表示されますが、SMARTSHEET_RM_ALLOW_BULK_DESTRUCTIVE=1 を設定しない限り、呼び出し時に拒否されます）。
• 読み取り専用モード：39 個のツール（readOnlyHint=true）。
• 破壊的操作の制限：明示的に confirm=True を必要とする 21 個のツール（標準 19 個＋一括操作 2 個）。
• べき等操作：idempotentHint=true を持つ 43 個のツール（読み取り専用の 39 個に加え、time_update_time_approval_status、time_lock_timesheet、admin_set_custom_field_values、admin_set_user_status）。

ドメインの概要

エージェントは、これらのtools/list名を呼び出します。時間とプロジェクトの件数には、バルク操作の利用制限があるツールも含まれます。

1. 時間（time_*、17個のツール）：time_list_time_entries、time_get_time_entry、time_create_time_entry、time_create_user_time_entry、time_create_project_time_entry、time_update_time_entry、time_delete_time_entry、time_list_user_suggestions、time_update_time_approval_status、time_lock_timesheet、time_fill_weekly_timesheet、time_confirm_suggested_hours、time_reconcile_and_submit_week、time_list_approvals、time_create_approval、time_delete_approval。バルク操作の利用制限あり：time_bulk_delete_time_entries。
2. プロジェクト（projects_*、27個のツール）：projects_list_projects、projects_get_project、projects_create_project、projects_update_project、projects_delete_project、projects_list_project_users、projects_list_project_phases、projects_get_project_phase、projects_create_project_phase、projects_update_project_phase、projects_delete_project_phase、projects_list_assignments、projects_get_assignment、projects_create_assignment、projects_create_project_assignment、projects_create_user_assignment、projects_update_assignment、projects_delete_assignment、projects_clone_project_schedule、projects_list_status_options、projects_list_placeholder_resources、projects_create_placeholder_resource、projects_delete_placeholder_resource、projects_list_assignment_subtasks、projects_create_assignment_subtask、projects_delete_assignment_subtask。バルク操作の利用制限あり：projects_bulk_delete_assignments。
3. 管理（admin_*、60個のツール）：
   • ユーザー、ロール、専門分野、キャパシティ：admin_list_users、admin_get_user、admin_create_user、admin_update_user、admin_delete_user、admin_list_user_bill_rates、admin_create_user_bill_rate、admin_get_user_availability、admin_get_user_utilization、admin_list_roles、admin_create_role、admin_update_role、admin_delete_role、admin_list_disciplines、admin_create_discipline、admin_update_discipline、admin_delete_discipline。
   • クライアントと連絡先：admin_list_clients、admin_get_client、admin_create_client、admin_update_client、admin_delete_client、admin_list_client_contacts、admin_create_client_contact、admin_delete_client_contact。
   • 休暇と休日：admin_list_leave_types、admin_get_leave_type、admin_create_leave_type、admin_update_leave_type、admin_delete_leave_type、admin_list_holidays、admin_get_holiday、admin_create_holiday、admin_update_holiday、admin_delete_holiday。
   • 経費：admin_list_expenses、admin_get_expense、admin_create_expense、admin_update_expense、admin_delete_expense、admin_list_expense_categories、admin_create_expense_category、admin_delete_expense_category。
   • タグとカスタムフィールド：admin_list_tags、admin_create_tag、admin_delete_tag、admin_list_custom_fields、admin_get_custom_field、admin_create_custom_field、admin_update_custom_field、admin_delete_custom_field、admin_list_custom_field_values、admin_set_custom_field_values。
   • ステータス、レポート、ウェブフック：admin_get_user_statuses、admin_set_user_status、admin_get_report_rows、admin_get_report_totals、admin_list_webhooks、admin_create_webhook、admin_delete_webhook。

ドキュメント化されていないルート

以下のツールは、Smartsheet のResource Management API リファレンス（OpenAPI JSON）にも、アーカイブ済みの10,000ft API ドキュメントにも記載されていないルートを呼び出します。このようなメソッドとパスの組み合わせは 46 件あります。一部のドキュメントに記載された同等のルートではリクエストの形式が異なるため、ツールが送信する内容を変えてしまうルートへの切り替えは行わず、これらのツールはそのまま残しています。Smartsheet は予告なく、ドキュメントに記載されていないルートを変更または削除する場合があります。各ツールの説明にはその旨が記載されています。該当する場合は、ドキュメントに記載されたルートを使うツールを優先してください。たとえば、time_create_time_entry の代わりに time_create_user_time_entry または time_create_project_time_entry を使用してください。これらのクライアント呼び出しにはそれぞれ # drift-ignore: undocumented route が付けられており、scripts/check_openapi_drift.py は、公開仕様に記載されていないその他の呼び出しがあると失敗します。

ツール	ドキュメントに記載されていないルート	ドキュメントに記載されている同等のもの
time_create_time_entry	POST /time_entries	POST /users/{user_id}/time_entries（time_create_user_time_entry）および POST /projects/{project_id}/time_entries（time_create_project_time_entry）。
time_update_time_entry	PUT /time_entries/{id}	PUT /users/{user_id}/time_entries/{id}。
time_delete_time_entry	DELETE /time_entries/{id}	DELETE /users/{user_id}/time_entries/{id}。
time_update_time_approval_status	PUT /users/{user_id}/time_entries/approval_status	該当なし。
time_lock_timesheet	POST /users/{user_id}/time_entries/lock	該当なし。
time_fill_weekly_timesheet	POST /time_entries	POST /users/{user_id}/time_entries。
time_confirm_suggested_hours	PUT /time_entries/{id}	PUT /users/{user_id}/time_entries/{id}。
time_reconcile_and_submit_week	PUT /users/{user_id}/time_entries/approval_status	該当なし（auto_submit=True の場合にのみ呼び出されます）。
time_bulk_delete_time_entries	DELETE /time_entries/{id}	DELETE /users/{user_id}/time_entries/{id}。
projects_get_project_phase	GET /projects/{project_id}/phases/{phase_id}	リファレンスにはこのパスの PUT と DELETE のみ記載されています。GET /projects/{project_id}/phases でフェーズを一覧表示できます。
admin_list_user_bill_rates	GET /users/{user_id}/bill_rates	GET /bill_rates および GET /projects/{project_id}/bill_rates。
admin_create_user_bill_rate	POST /users/{user_id}/bill_rates	リファレンスに記載されている請求レートのパスは /bill_rates と /projects/{project_id}/bill_rates のみで、作成用のパスはありません。
admin_get_user_availability	GET /users/{user_id}/availability	GET /users/{user_id}/availabilities。
admin_get_user_utilization	GET /users/{user_id}/utilization	該当なし。
admin_create_role	POST /roles	リファレンスにはロールの GET のみ記載されています。
admin_update_role	PUT /roles/{id}	リファレンスにはロールの GET のみ記載されています。
admin_delete_role	DELETE /roles/{id}	リファレンスにはロールの GET のみ記載されています。
admin_create_discipline	POST /disciplines	リファレンスには職種の GET のみ記載されています。
admin_update_discipline	PUT /disciplines/{id}	リファレンスには職種の GET のみ記載されています。
admin_delete_discipline	DELETE /disciplines/{id}	リファレンスには職種の GET のみ記載されています。
admin_list_clients	GET /clients	該当なし。
admin_get_client	GET /clients/{id}	該当なし。
admin_create_client	POST /clients	該当なし。
admin_update_client	PUT /clients/{id}	該当なし。
admin_delete_client	DELETE /clients/{id}	該当なし。
admin_list_client_contacts	GET /clients/{id}/contacts	該当なし。
admin_create_client_contact	POST /clients/{id}/contacts	該当なし。
admin_delete_client_contact	DELETE /clients/{id}/contacts/{contact_id}	該当なし。
admin_create_leave_type	POST /leave_types	リファレンスには休暇タイプの GET のみ記載されています。
admin_update_leave_type	PUT /leave_types/{id}	リファレンスには休暇タイプの GET のみ記載されています。
admin_delete_leave_type	DELETE /leave_types/{id}	リファレンスには休暇タイプの GET のみ記載されています。
admin_get_holiday	GET /holidays/{id}	リファレンスには GET /holidays のみ記載されています。
admin_create_holiday	POST /holidays	リファレンスには GET /holidays のみ記載されています。
admin_update_holiday	PUT /holidays/{id}	リファレンスには GET /holidays のみ記載されています。
admin_delete_holiday	DELETE /holidays/{id}	リファレンスには GET /holidays のみ記載されています。
admin_list_expenses	GET /expenses、GET /projects/{project_id}/expenses、GET /users/{user_id}/expenses	GET /users/{user_id}/expense_items および GET /projects/{project_id}/expense_items。
admin_get_expense	GET /expenses/{id}	GET /users/{user_id}/expense_items/{expense_item_id} および GET /projects/{project_id}/expense_items/{expense_item_id}。
admin_create_expense	POST /expenses	POST /users/{user_id}/expense_items。
admin_update_expense	PUT /expenses/{id}	PUT /users/{user_id}/expense_items/{expense_item_id}。
admin_delete_expense	DELETE /expenses/{id}	DELETE /users/{user_id}/expense_items/{expense_item_id}。
admin_list_expense_categories	GET /expense_categories	GET /expense_item_categories。
admin_create_expense_category	POST /expense_categories	リファレンスには GET /expense_item_categories のみ記載されています。
admin_delete_expense_category	DELETE /expense_categories/{id}	リファレンスには GET /expense_item_categories のみ記載されています。
admin_list_tags	GET /tags	GET /projects/{project_id}/tags および GET /users/{user_id}/tags。
admin_create_tag	POST /tags	POST /projects/{project_id}/tags および POST /users/{user_id}/tags。
admin_delete_tag	DELETE /tags/{id}	DELETE /projects/{project_id}/tags/{tag_id} および DELETE /users/{user_id}/tags/{tag_id}。
admin_list_custom_field_values	GET /custom_field_values	GET /projects/{project_id}/custom_field_values および GET /users/{user_id}/custom_field_values。
admin_set_custom_field_values	PUT /custom_field_values	PUT /projects/{project_id}/custom_field_values/{custom_field_value_id} および PUT /users/{user_id}/custom_field_values/{custom_field_value_id}。

---

🚀 クイックスタートとインストール

1. uvx で実行

[project.scripts] のコンソールスクリプトはどちらも smartsheet_rm_mcp.server:main を呼び出します。smartsheet-rm-mcp（以下で使用）と mcp-server-smartsheet-rm です。インストール例ではバージョンを固定していません。リリースを固定するには、リリースに記載されているバージョンを指定してください。

uvx --from mcp-server-smartsheet-rm smartsheet-rm-mcp

アップグレード後は、MCP ホストを再読み込みしてください。稼働中のプロセスの開始時刻が新しいバイナリの mtime より後になっている必要があります（古いプロセス ≠ 新しいパッケージ）。

2. インストール

# Using uv (recommended)
uv pip install mcp-server-smartsheet-rm

# Or standard pip
pip install mcp-server-smartsheet-rm

3. 環境変数

変数	説明	デフォルト
SMARTSHEET_RM_API_TOKEN	Smartsheet RM（10,000ft）API トークン（必須）	-
SMARTSHEET_RM_BASE_URL	ベース API URL	https://api.rm.smartsheet.com/api/v1
SMARTSHEET_RM_PROFILE	プロファイル：full、time、projects、admin、readonly、timesheets、staffing、org_setup、portfolio（プロファイルを参照）	full
SMARTSHEET_RM_READONLY	1 に設定すると、readOnlyHint=true のツールのみを一覧表示し、それ以外のすべての呼び出しを拒否します	0
SMARTSHEET_RM_ALLOW_BULK_DESTRUCTIVE	1 に設定すると、一覧表示される2つの一括削除ツールの実行を許可します	0
SMARTSHEET_RM_ENABLE_TOOL_SEARCH	Tool Search を full で有効にするには、1（または --enable-tool-search）に設定します	0
SMARTSHEET_RM_TOOL_SEARCH_BACKEND	Tool Search バックエンド：regex または bm25（または --tool-search-backend）	regex
SMARTSHEET_RM_ENABLE_CODE_MODE	full で実験的な Code Mode を有効にするには、1（または --enable-code-mode）に設定します。Tool Search とは併用できません	0
SMARTSHEET_RM_MCP_AUTH_TOKEN	HTTP トランスポートで必要な共有ベアラートークン（stdio では無視されます）	未設定
SMARTSHEET_RM_MCP_ALLOW_UNAUTHENTICATED_BIND	1 に設定すると、localhost 以外のホストへのトークンなし HTTP バインドを許可します	未設定
SMARTSHEET_RM_LOG_FORMAT	Datadog／CloudWatch 用の構造化ログを使用するには、json に設定します	text
SMARTSHEET_RM_ALLOWED_HOSTS	ベース URL の上書きで許可するホスト名をカンマ区切りで指定します。空白以外の値を指定すると、デフォルト値が置き換えられます。ループバックおよびプライベートな宛先は引き続きブロックされます。	api.rm.smartsheet.com
SMARTSHEET_RM_GOV_SMARTSHEET_API_TOKEN	Smartsheet Gov 専用の Smartsheet API トークン。Authorization: Bearer として送信され、app.smartsheetgov.com にのみ送信されます（Smartsheet Govを参照）	未設定

Smartsheet Gov

Smartsheet Gov はオプトイン方式です。デフォルトのベース URL と許可リストは変更されません。Smartsheet の RM API の概要および認証のページによると、Gov のベース URL は https://app.smartsheetgov.com/2.0/rm/api/v1 であり、すべてのリクエストに auth の RM トークンと Authorization: Bearer の Smartsheet API トークンの両方が必要です。使用するには、次のようにします。

export SMARTSHEET_RM_BASE_URL='https://app.smartsheetgov.com/2.0/rm/api/v1'
export SMARTSHEET_RM_ALLOWED_HOSTS='app.smartsheetgov.com'
export SMARTSHEET_RM_API_TOKEN='your_rm_api_token'
export SMARTSHEET_RM_GOV_SMARTSHEET_API_TOKEN='your_smartsheet_api_token'

Gov ホストにも、他のベース URL と同じ HTTPS、SSRF、許可リスト、DNS ピン留めの検証が適用されます。クライアントは、Smartsheet トークンがない場合、Gov ホストへの接続を開始しません。また、そのトークンを他のホストに送信することもありません。HTTP トランスポートでは、呼び出し元が独自の auth または x-smartsheet-rm-token ヘッダーを送信する場合、独自の x-smartsheet-gov-api-token ヘッダーも送信する必要があります。環境変数の Gov トークンが、呼び出し元の RM トークンと組み合わされることはありません。

---

💻 クライアント設定

Google Antigravity（~/.gemini/antigravity-cli/mcp_config.json）

{
  "mcpServers": {
    "smartsheet-rm": {
      "command": "uvx",
      "args": ["--from", "mcp-server-smartsheet-rm", "smartsheet-rm-mcp"],
      "env": {
        "SMARTSHEET_RM_API_TOKEN": "your-api-token"
      },
      "lazy": true
    }
  }
}

Snowflake Cortex（~/.snowflake/cortex/mcp.json）

{
  "servers": {
    "smartsheet-rm": {
      "command": "uvx",
      "args": ["--from", "mcp-server-smartsheet-rm", "smartsheet-rm-mcp"],
      "env": {
        "SMARTSHEET_RM_API_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "smartsheet-rm": {
      "command": "uvx",
      "args": ["--from", "mcp-server-smartsheet-rm", "smartsheet-rm-mcp"],
      "env": {
        "SMARTSHEET_RM_API_TOKEN": "your-api-token"
      }
    }
  }
}

ストリーミング可能な HTTP

ストリーミング可能な HTTP を推奨します。--transport sse は非推奨です（MCP 仕様 SEP-2577）。main() は移行に関する警告をログに記録し、クライアントの接続先として /sse を案内しません。

uvx --from mcp-server-smartsheet-rm smartsheet-rm-mcp --transport streamable-http --host 127.0.0.1 --port 8000

クライアントは http://127.0.0.1:8000/mcp（FastMCP のデフォルトのストリーミング可能な HTTP パス）に接続してください。run(transport="streamable-http") はカスタムパスを設定しません。0.0.0.0 または :: にバインドするには、明示的な --allowed-host が必要です（ワイルドカード * は拒否されます）。

デフォルトの（ステートフルな）HTTP モードでは、30 分間アイドル状態のセッションは期限切れになります。次のリクエストは HTTP 404 を返し、クライアントは新しいセッションを開始する必要があります。FastMCP の session_idle_timeout（http_app() で設定）または FASTMCP_HTTP_SESSION_IDLE_TIMEOUT（秒単位、または期限切れにしない場合は none）で変更できます。FastMCP 4.1.0 リリースおよび #5229を参照してください。

HTTP 認証。 SMARTSHEET_RM_MCP_AUTH_TOKEN を設定すると、すべての HTTP リクエストで Authorization: Bearer <token> が必要になります。トークンがない場合、または正しくない場合は 401 が返されます。トークンの前後の空白は削除され、空白のみの値は未設定として扱われます。サーバーの構築時に適用されるため、smartsheet-rm-mcp、fastmcp run、および mcp.http_app() をマウントする ASGI ホストのすべてで認証が適用されます。stdio では使用されません。

トークンが設定されていない場合、HTTP を 127.0.0.1、::1、または localhost にバインドすると、認証なしで起動し、警告が記録されます。トークンなしでそれ以外のホストにバインドすると、コード 2 で終了します。トークンを設定するか、localhost にバインドするか、SMARTSHEET_RM_MCP_ALLOW_UNAUTHENTICATED_BIND に 1、true、yes、または on を設定すると、認証なしのパブリックバインドが許可されます（それ以外の値では拒否されます）。イメージを HTTP 経由で提供するには、コマンドラインではなく、環境変数または env ファイルからトークンを渡してください。

# export SMARTSHEET_RM_API_TOKEN and SMARTSHEET_RM_MCP_AUTH_TOKEN first, or use --env-file .env
docker run --rm -p 8000:8000 -e SMARTSHEET_RM_API_TOKEN -e SMARTSHEET_RM_MCP_AUTH_TOKEN \
  ghcr.io/christianclaudio/mcp-server-smartsheet-rm:latest \
  --transport streamable-http --host 0.0.0.0 --allowed-host localhost:8000

---

🛡️ 安全性と信頼性

• シークレットのマスキング：API トークン、ベアラーヘッダー、機密キーは、エラーやログから自動的に削除されます。
• 破壊的操作のゲート：すべての削除ツールでは confirm: bool = False が宣言されており、呼び出し元が明示的に confirm=True を渡さない限り変更は行われません。指定がない場合、ツールは "status": "confirmation_required" と confirm=true を指定して再度呼び出すよう促すメッセージを含む通常の結果（isError: false）を返します。これは意図された 2 段階の処理であり、エラーではありません。
• 入力検証：引数が不足している場合や無効な場合（たとえば、フィールドを指定しない更新や、不正な形式の日付）は、モデルが修正できるツールエラー（isError: true、"type": "invalid_request"）を返します。これは、入力検証エラーに関する MCP 仕様の説明に沿った動作です。
• 一括処理の結果：time_fill_weekly_timesheet、time_confirm_suggested_hours、time_bulk_delete_time_entries、projects_bulk_delete_assignments は共通の形式を使用します。"status": "success" または "partial_success"、成功件数（filled_count / confirmed_count / deleted_count）、failed_count、results、errors が含まれます。成功項目は {id|date, status, result}、失敗項目は {id|date, status: "failed", error} です。error には必ず message が含まれます（API エラーは to_dict() 経由、その他の例外はマスキング済みメッセージを含む "type": "internal"）。以前のリリースで使用されていたフィールド名も引き続き含まれます。time_fill_weekly_timesheet は days_filled、created_count、entries（作成されたエントリー）も返し、time_confirm_suggested_hours は confirmed_entries を返します。すべての項目が失敗した場合、呼び出しはツールエラー（isError: true、"type": "batch_failed"）になります。
• プロファイル：必要なジョブのツール（timesheets、staffing、org_setup、portfolio）またはドメイン（time、projects、admin）だけを読み込むことで、トークンの使用量を最小限に抑えます。
• 読み取り専用ゲート：readOnlyHint によって判断され、それ以外はすべて isError: true で拒否されます。
• レジリエンス：HTTP 429 のレート制限に対し、ランダムなジッターを加えた指数バックオフを行います。

---

🧪 テストと検証

# Run tests with 100% coverage requirement
pytest --cov=src/smartsheet_rm_mcp --cov-fail-under=100 -v

# Run Tool Contract verification
python scripts/check_tool_contract.py

# Run OpenAPI Drift check against Smartsheet's published spec (or --spec-file for a local copy)
python scripts/check_openapi_drift.py --spec-url https://developers.smartsheet.com/_spec/api/resource_management/openapi.json