simple-support-system-mcp

simple-support-system-mcp

Concrete CMS 用 Simple Support System アドオンの REST API に接続するローカル MCP サーバー（stdio）です。アシスタントが人間と同じようにサポートキューを操作できます。チケットを見つけ、履歴とともに読み、返信を書き、次の状態に移動できます。プロジェクト、添付ファイル、モデレーションにも対応しています。

このサーバーは、パッケージを実行している任意のサイトと通信します。値がハードコードされることはなく、サイト URL と API キーは環境変数から取得されます。stdio のみで通信し、ポートを開くことはありません。

インストール

npm install
npm run build

Claude Code にサーバーを登録します。

claude mcp add simple-support-system \
  -e SIMPLE_SUPPORT_SYSTEM_BASE_URL=https://support.example.com \
  -e SIMPLE_SUPPORT_SYSTEM_API_KEY=your-api-key \
  -- node "/absolute/path/to/simple-support-system-mcp/dist/src/index.js"

または、~/.claude.json / claude_desktop_config.json に登録します。

{
  "mcpServers": {
    "simple-support-system": {
      "command": "node",
      "args": ["/absolute/path/to/simple-support-system-mcp/dist/src/index.js"],
      "env": {
        "SIMPLE_SUPPORT_SYSTEM_BASE_URL": "https://support.example.com",
        "SIMPLE_SUPPORT_SYSTEM_API_KEY": "your-api-key"
      }
    }
  }
}

環境変数

変数	用途
SIMPLE_SUPPORT_SYSTEM_BASE_URL	必須。Concrete CMS サイトのベース URL です。例：https://support.example.com。API パス /index.php/api/v1 は自動的に追加されます。すでに /api/v1 で終わる URL はそのまま使用されます。
SIMPLE_SUPPORT_SYSTEM_API_KEY	インストール環境の API キーです。X-Api-Key ヘッダーとして送信されます。これがない場合、API の公開部分にのみアクセスできます。
SIMPLE_SUPPORT_SYSTEM_API_PATH	任意。index.php ディスパッチャーを使用しないサイト向けに、デフォルトの API パスを上書きします。例：/api/v1。
SIMPLE_SUPPORT_SYSTEM_PROJECT_TOKEN	任意。プライベートプロジェクト用のデフォルトのアクセストークンです。ツール呼び出しで個別のトークンが渡されない場合に使用されます。
SIMPLE_SUPPORT_SYSTEM_PROJECT_ID	任意。サーバーをこの 1 つのプロジェクトに制限します。詳しくはサーバーを 1 つのプロジェクトに制限するを参照してください。
SIMPLE_SUPPORT_SYSTEM_TIMEOUT_MS	任意。リクエストのタイムアウト時間（ミリ秒）です。デフォルトは 30000 です。

API キーはパッケージのインストール時に生成され、サイト設定の simple_support_system.api_key に保存されます。API キーなしの呼び出しは匿名訪問者として実行されます。公開プロジェクトと承認済みチケットの閲覧、チケットの作成、コメントの投稿は引き続き可能ですが、状態の変更、削除、承認、プロジェクトの操作などの管理機能は利用できません。

ツール

日常的に使う3つのツールは、list_tickets、get_ticket、reply_to_ticketです。チケットを次の状態に進めるには、set_ticket_stateを使います。

ツール	用途
list_tickets	プロジェクト、状態、種類、優先度、担当者、テキスト検索、変更日で絞り込み、並べ替えとページ分けを行ってチケットを一覧表示します。デフォルトでは簡潔な要約を表示します。
get_ticket	1件のチケットとその添付ファイルを読み取ります。無効にしない限り、すべてのコメントも読み取ります。
reply_to_ticket	チケットにコメントとして返信を投稿し、通知メールを送信します。
set_ticket_state	チケットを別のワークフロー状態に移し、関係者全員に通知します。
create_ticket	プロジェクトIDまたはプロジェクトハンドルを指定してプロジェクトにチケットを作成します。アップロード済みファイルも指定できます。
update_ticket	タイトル、内容、種類、優先度、担当者を変更します。指定したフィールドのみが更新されます。
approve_ticket	モデレーション対象のチケットを承認します。
delete_ticket	すべてのコメントと添付ファイルのリンクを含めてチケットを削除します。取り消しできません。confirm: trueが必要です。
list_ticket_comments	チケットのコメントを一覧表示します。
update_comment	コメントのテキストを置き換えます。
approve_comment	モデレーション対象のコメントを承認します。
delete_comment	コメントを削除します。取り消しできません。confirm: trueが必要です。
list_projects	サポートプロジェクトを一覧表示します。APIキーが設定されている場合はアクセストークンも表示します。
get_project	IDを指定して1つのプロジェクトを読み取ります。
create_project	プロジェクトを作成します。非公開プロジェクトには生成されたアクセストークンが付与されます。
update_project	プロジェクトの名前、ハンドル、公開範囲を変更します。
delete_project	プロジェクト内のすべてのチケットとコメントを含めてプロジェクトを削除します。取り消しできません。confirm: trueが必要です。
list_ticket_attachments	チケットに添付されたファイルを一覧表示します。
upload_attachment	ローカルファイルをファイルマネージャーにアップロードし、ファイルIDを返します。
add_ticket_attachments	アップロード済みファイルのIDをチケットに関連付けます。
download_attachment	添付ファイルのダウンロードURLを取得し、ローカルパスに保存することもできます。
delete_attachment	チケットからファイルを削除します。取り消しできません。confirm: trueが必要です。
get_server_info	設定済みのAPI URL、キーの有無、受け付ける状態、種類、優先度を表示します。キー自体は返されません。

読み取りツールには読み取り専用の注釈が付いており、4つのdelete_ツールには破壊的操作の注釈が付いています。これらのツールはすべて、さらにconfirm: trueが必要なため、曖昧な指示の副作用として削除が実行されることはありません。API側にはゴミ箱も復元機能もありません。削除されたチケット、コメント、プロジェクトは完全に失われます。

チケットへの対応

list_tickets   { "state": "open", "sortBy": "updatedAt" }
get_ticket     { "ticketId": 42 }
reply_to_ticket{ "ticketId": 42, "comment": "Thanks for the report, we are on it." }
set_ticket_state { "ticketId": 42, "state": "in_progress" }

list_ticketsでは、projectIdの代わりにprojectHandleも指定でき、最初にプロジェクト一覧を使って解決します。

APIで受け付ける値

• 状態：new、open、in_progress、on_hold、resolved、duplicate、invalid、wont_fix、closed。set_ticket_stateはnewを除くすべてを受け付けます。newはチケット作成時にのみ設定されます。
• 種類：bug、enhancement、proposal、task
• 優先度：trivial、minor、major、critical、blocker
• 状態がclosedまたはinvalidのチケットはロックされます。状態が変更されるまで、APIはチケット、そのコメント、添付ファイルの編集を拒否します。

添付ファイル

upload_attachment      { "filePath": "/tmp/screenshot.png" }      -> fileId
add_ticket_attachments { "ticketId": 42, "fileIds": [123] }

upload_attachmentはファイルをサイトのファイルマネージャーに保存しますが、どこにも関連付けません。2回目の呼び出しで添付します。create_ticketでは、同じIDをattachmentFileIdsに指定できます。

非公開プロジェクト

非公開プロジェクトにアクセスするには、そのアクセストークンが必要です。呼び出しごとにtokenとして渡すか、デフォルトとしてSIMPLE_SUPPORT_SYSTEM_PROJECT_TOKENを設定してください。APIキーを使用する場合、キーによってすでに完全なアクセス権が付与されるため、トークンは不要です。

サーバーを1つのプロジェクトに制限する

SIMPLE_SUPPORT_SYSTEM_PROJECT_ID を設定すると、通常はそのプロジェクトのアクセストークンと組み合わせ、API キーなしで、サーバーを1つのプロジェクトだけで作業する人に渡せます。プロジェクトが指定されていない場合、list_tickets と create_ticket はこのプロジェクトを使用し、list_projects にはこのプロジェクトだけが表示されます。また、チケット ID を受け取るすべてのツールは、まずチケットがこのプロジェクトに属していることを確認します。別のプロジェクト ID またはハンドルは拒否されます。API キーがない場合、サイト自体が他の非公開プロジェクトへのアクセスをすでに制限していますが、この設定を追加すると、インストール内の公開プロジェクトも表示されなくなります。

API に関する注意事項

このパッケージはいくつかの形式で応答しますが、サーバーがすべてを正規化するため、ツールはリソース本体を返します。

• コレクションは通常の配列として返され、単一のチケットとコメントは ticket または comment キーの中に、添付ファイルは data の中に返されます。
• エラーは {"errors": [...]} として届く場合と、error フラグを持つ Concrete の EditResponse として届く場合があります。後者はステータス 200 で返されることがあるため、200 だけでは成功とみなしません。すべてのエラーは、API から送信されたメッセージとともにツールエラーになります。
• create_ticket は新しいレコードではなくステータスを示すエンベロープを返すため、新しく作成したチケットの ID は list_tickets で確認する必要があります。
• download_attachment は API が返すリダイレクトをたどり、解決された URL を報告します。

検証

npm run build
npm test

テストはスタブ化された HTTP レイヤーに対して実行され、実際のサイトには一切アクセスせず、認証情報も必要ありません。PHP コントローラーが想定する URL とフォームのエンコード（PHP のブール値と配列表記を含む）、レスポンスのエンベロープ、エラーマッピング、list_tickets のフィルタリングと並べ替え、破壊的なツールのガードレールを対象としています。

ライセンス

MIT。詳細は LICENSE を参照してください。