Xalantis

@xalantis/mcp-server

Xalantis 用 MCP サーバーです。MCP 互換の AI クライアントが、公開 /api/v1 API を通じて Xalantis のビジネスデータを読み取り、操作できます。

リリース 0.3.0 では、公開 API の全 323 件の操作（コントラクト 2.11.0）に対応しました。頻繁に行われるタスクには専用ツールを用意し、それ以外は同梱の OpenAPI 仕様を利用する 4 つの汎用ツールで対応します。

レジストリ

公式 MCP Registry には io.github.xalantis-hub/xalantis-mcp として、また Glama に掲載されています。

インストール

npm install -g @xalantis/mcp-server

設定

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "xalantis": {
      "command": "npx",
      "args": ["-y", "@xalantis/mcp-server"],
      "env": {
        "XALANTIS_API_KEY": "sk_live_..."
      }
    }
  }
}

Claude Code

claude mcp add xalantis -- npx -y @xalantis/mcp-server

次に、MCP サーバーを起動するシェル／セッションで XALANTIS_API_KEY を設定します。

Cursor

.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "xalantis": {
      "command": "npx",
      "args": ["-y", "@xalantis/mcp-server"],
      "env": {
        "XALANTIS_API_KEY": "sk_live_..."
      }
    }
  }
}

対応分野

専用ツール：

• サポート／サービスデスク：チケット、返信、添付ファイル、レポート、リンク、ウォッチャー、時間記録、サブタスク、インシデント、サービスリクエスト、SLA、自動化、カテゴリ、タグ、サービスカタログ、エージェント。
• CRM：クライアント、担当者、連絡先、取引、パイプライン。
• ナレッジ：記事、検索、カテゴリ、管理対象の記事の下書きとレビュー。
• 請求：サブスクリプションと請求書。
• 財務：請求書と経費の読み取り専用 API。
• 契約：契約、コメント、交渉、義務、承認、署名、条項、リクエスト、PDF デザイン、アセット、割り当て。
• プロジェクト：プロジェクト、ステータス、タスク（一覧表示、読み取り、作成、更新、遷移）、タスクのコメント。

汎用ツールでは、Projects のその他の機能（スプリント、マイルストーン、リスト、ラベル、カスタムフィールド、ドキュメント、時間追跡、自動化、分析、エクスポート、インポート、クライアントポータル）、コンプライアンス案件、署名エンベロープ、契約の参照データ、CRM インポートなど、公開 API のその他すべての操作を利用できます。

汎用 API アクセス

専用ツールがない公開 API の操作は、次の 4 つのツールで利用できます。

1. search_operations：キーワード（すべて必須、アクセント記号は無視。概要はフランス語）、分野、HTTP メソッドで操作を検索します。引数を指定しない場合は、分野の一覧を返します。
2. describe_operation：1 つの操作のパス、クエリおよびヘッダーのパラメーター、ボディのスキーマ、スコープを返します。
3. read_operation：GET 操作を実行します。バイナリまたは CSV のレスポンスは、save_to を指定してローカルファイルに保存できます。
4. call_operation：POST、PUT、PATCH、または DELETE 操作を実行します。confirm: true が必要です。マルチパートアップロードでは、files にローカルパスを指定します。

{
  "operation_id": "post_projects_By_projectUuid_tasks_By_taskUuid_time_entries",
  "path_params": { "projectUuid": "project-uuid", "taskUuid": "task-uuid" },
  "body": { "duration_minutes": 45, "description": "Review" },
  "confirm": true
}

仕様はパッケージに同梱され（openapi/xalantis-openapi.json）、リリースごとに更新されます。200 KB を超えるテキストレスポンスは、ページネーションまたは save_to の使用を促すヒントとともに拒否されます。

すべての書き込みでは Idempotency-Key が送信されます。headers で指定されない場合は、呼び出しごとに生成されます。約 80 のルートでこのキーが必要で、同じキーで再実行すると、二重に処理されることなく最初のレスポンスが返されます。

プロジェクトのルートには、ワークスペースのメンバーに紐づいた API キー（Developers 設定から作成したキーが該当します）と、対応する projects:* スコープが必要です。

確認モデル

データを変更する、または機密データを公開する可能性があるツールでは、confirm: true 引数が必要です。AI クライアントは、ユーザーが明示的に操作を確認した後にのみ、この引数を渡す必要があります。

確認が必要な操作の例：

• レコードの作成、更新、削除。
• 公開チケット返信の送信。
• サービスリクエストの承認、却下、履行、再開。
• チケットの統合、分割、アーカイブ、削除。
• 契約署名のリクエスト。
• 添付ファイルまたはレポートのダウンロード。
• ファイルのアップロード。

確認が指定されていない場合、ツールは確認が必要であることを説明するエラーを返します。

ファイル転送ツール

バイナリエンドポイントは、ファイル対応ツールでサポートされています。

{
  "ticket_uuid": "ticket-uuid",
  "file_path": "/local/path/evidence.pdf",
  "confirm": true
}

ダウンロードデータは、Base64 で返すか、ローカルパスに書き込むことができます。

{
  "ticket_uuid": "ticket-uuid",
  "attachment_uuid": "attachment-uuid",
  "output_path": "/tmp/evidence.pdf",
  "confirm": true
}

output_path を省略すると、ツールはメタデータと Base64 コンテンツを返します。

プロンプトの例

接続すると、MCP 互換のアシスタントは次のようなプロンプトに回答したり、操作を実行したりできます。

• 「未解決の緊急チケットを一覧表示し、最も古いものを要約してください。」
• 「クライアントの Acme を検索して、関連する連絡先を表示してください。」
• 「SLA 設定をナレッジベースで検索してください。」
• 「この Knowledge の下書きを作成し、私の確認後に編集レビューに提出してください。」
• 「公開済みのこの Knowledge 記事を更新してください。承認されるまで公開中のバージョンは変更しないでください。」
• 「私の確認後に、このインシデントのチケットを作成してください。」
• 「このチケットに内部メモを追加してください。」
• 「今月が期限の契約上の義務を表示してください。」
• 「確認後に、この契約を承認に提出してください。」
• 「このチケットレポートを /tmp/report.xlsx にダウンロードしてください。」
• 「プロジェクト MXA の期限超過タスクを一覧表示し、私が選んだものを Done に移動してください。」
• 「このタスクに45分を記録して、スプリントのバーンダウンを表示してください。」

環境変数

変数	必須	説明
XALANTIS_API_KEY	はい	Xalantis の /api/v1 リクエストで使用するテナント API キーです。
XALANTIS_BASE_URL	いいえ	Xalantis インスタンスのオリジンまたは API ベース URL です。例：https://app.example.com。デフォルトは https://xalantis.com/api/v1 です。

セキュリティに関する注意

• MCP サーバーは、Xalantis のバックエンド権限、プランによる制限、テナントスコープ、レート制限を回避しません。
• 破壊的な操作や外部に公開される操作には、confirm: true が必要です。
• ファイルのダウンロードには機密性の高いテナントデータが含まれる場合があります。output_path は慎重に使用してください。
• API キーはプロンプトではなく、MCP クライアントの環境設定に保存してください。

開発

npm ci
npm run lint
npm test            # compiles, then checks every tool against the bundled spec
npm run sync-openapi -- path/to/openapi.json

npm test は偽のトランスポートを使ってすべてのツールを呼び出し、仕様に宣言されていないルートを対象にしたり、Idempotency-Key を付けずに書き込みを送信したりした場合に失敗します。リリース前に sync-openapi を実行してください（デフォルトのソース：兄弟ディレクトリにある xalantis-application/storage/app/openapi.json）。

ライセンス

MIT