# Xserver MCP

XServer API を **読み取り専用** でラップした MCP サーバーです。Claude との会話から
サーバーの状況（ディスク使用量・ドメイン・メール・cron など）を確認できます。

```
あなた: サーバーのディスク、あとどれくらい空いてる？
Claude: [xserver_server_status を実行]
        xs123456.xsrv.jp: 42.1 GB / 300 GB (14.0%)、ファイル数 128,430
        ドメイン 7、サブドメイン 12、メールアカウント 23、MySQL 4
```

## 重要な前提

- **このサーバーは GET しか発行しません。** 設定変更・削除は一切できません。
- **お手元のマシンで動かす前提です。** Claude Desktop / ローカルの `claude` CLI に
  stdio で接続します。Claude Code on the web のリモートセッションからは
  `api.xserver.ne.jp` に到達できないため、そちらでは動きません。
- **エンドポイントは実アカウントで検証済みです。** 公式リファレンス
  （https://developer.xserver.ne.jp/api/server/ ）を参照できない状態で実装したため
  当初は推測を含んでいましたが、`npm run check` による実測で確定させました。
  一部は 404 で存在しないことが判明しています。下記「エンドポイントの検証状況」を参照してください。

## セットアップ

必要環境: Node.js 20 以上。

```bash
git clone <このリポジトリ>
cd Xserver_MCP
npm install
npm run build
```

### APIキーの発行

1. Xserver のサーバーパネルにログイン
2. 「アカウント」→「APIキー設定」
3. 「APIキー発行」をクリックしてキーをコピー

キーは**チャットに貼らず**、環境変数として渡してください。

### 動作確認

MCP クライアントに繋ぐ前に、接続チェックを実行します。

```bash
XSERVER_API_KEY='発行したキー' npm run check
```

`/me` の疎通、サーバー名の解決、各エンドポイントの到達性を順に確認し、
`ok` / `miss` で一覧表示します。`miss` になったパスは実在しない（＝推測が外れた）
ということなので、公式リファレンスで正しいパスを確認してください。

## Claude Desktop への登録

設定ファイル（macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`、
Windows: `%APPDATA%\Claude\claude_desktop_config.json`）に追記します。

```json
{
  "mcpServers": {
    "xserver": {
      "command": "node",
      "args": ["/absolute/path/to/Xserver_MCP/dist/index.js"],
      "env": {
        "XSERVER_API_KEY": "発行したキー",
        "XSERVER_SERVERNAME": "xs123456.xsrv.jp"
      }
    }
  }
}
```

`args` は**絶対パス**にしてください。設定後、Claude Desktop を再起動します。

ローカルの `claude` CLI の場合:

```bash
claude mcp add xserver \
  --env XSERVER_API_KEY='発行したキー' \
  --env XSERVER_SERVERNAME='xs123456.xsrv.jp' \
  -- node /absolute/path/to/Xserver_MCP/dist/index.js
```

## 環境変数

| 変数 | 必須 | 既定値 | 説明 |
|---|---|---|---|
| `XSERVER_API_KEY` | ✅ | — | サーバーパネルで発行した APIキー |
| `XSERVER_SERVERNAME` | | `/me` から自動解決 | 初期ドメイン。Xserver は `<サーバーID>.xsrv.jp`、Xserver ビジネスは `<サーバーID>.xbiz.jp` |
| `XSERVER_API_BASE` | | `https://api.xserver.ne.jp/v1` | APIのベースURL（https 必須） |
| `XSERVER_TIMEOUT_MS` | | `30000` | 1リクエストあたりのタイムアウト |

`XSERVER_SERVERNAME` を省略した場合、最初のツール呼び出し時に `GET /me` から
サーバー名を取得してキャッシュします。

APIキーをコマンド行に直接書くと PowerShell の履歴ファイルに平文で残ります。
入力を伏せ字にして渡すには:

```powershell
$env:XSERVER_API_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR([Runtime.InteropServices.Marshal]::SecureStringToBSTR((Read-Host "API key" -AsSecureString)))
```

## 提供ツール

| ツール | 用途 |
|---|---|
| `xserver_account_info` | `GET /me`。契約種別・有効期限・サーバー名・権限種別。まずこれで疎通確認 |
| `xserver_server_status` | サーバー状況。ディスク使用量・ファイル数・各種リソース件数のサマリと生JSON |
| `xserver_list` | リソース一覧（`resource` を指定）。domain / mail / cron / subdomain / ssl / php / mysql / ftp / dns など |
| `xserver_get` | 任意パスへの GET。他のツールで届かないエンドポイント用の逃げ道 |
| `xserver_endpoints` | このサーバーが把握しているエンドポイント一覧と確度を返す |

`xserver_list` で 404 が返る場合は、`xserver_endpoints` で確度を確認したうえで、
公式リファレンスの正しいパスを `xserver_get` に渡してください。

## エンドポイントの検証状況

Xserver ビジネス契約・`permission_type: "read"` のキーで `npm run check` を実行した実測結果です。

**`verified`（200 が返る）**

| パス | レスポンス |
|---|---|
| `/me` | `{service_type, expires_at, servername, permission_type}` |
| `/server/{servername}/server-info` | `{server_id, hostname, ip_address, os, cpu, ...}` |
| `/server/{servername}/server-info/usage` | `{disk: {quota_gb, used_gb, file_limit, file_count}, counts: {...}}` |
| `/server/{servername}/domain` | `{domains: [{domain, type, ssl, memo, is_awaiting}]}` |
| `/server/{servername}/mail` | `{accounts: [...]}` |
| `/server/{servername}/cron` | `{crons: [...], notification_email}` |
| `/server/{servername}/subdomain` | `{subdomains: [...]}` |
| `/server/{servername}/ssl` | `{ssl_list: [{id, common_name, type, expires_at, status}]}` |
| `/server/{servername}/ftp` | `{accounts: [...]}` |
| `/server/{servername}/dns` | `{records: [...]}` |
| `/server/{servername}/mail-filter` | `{filters: [...]}` |

`disk.file_limit` が `0` の場合は上限なしを意味します。

**`requires-params`（422 `VALIDATION_ERROR`）**

`access-log` / `error-log`

エンドポイントは存在しますが、**`domain` パラメータが必須**です（省略すると
`{"error":{"code":"VALIDATION_ERROR","message":"ドメインは必須です"}}`）。

```
xserver_list(resource="access-log", query={ "domain": "example.com" })
```

`domain` の値は `xserver_list(resource="domain")` で取得できます。
`npm run check` は最初のドメインを自動で補って検証します。

**`unavailable`（404 `NOT_FOUND`）**

`php` / `mysql` / `mysql-user` / `wordpress` / `mail-forward` / `backup`

これらは `xserver_list` の候補から除外してあり、指定すると「このパスには存在しない」旨を
説明して返します。機能自体は別パスに存在する可能性があるため、公式リファレンスで
正しいパスを確認のうえ `xserver_get` を使ってください。

なお `verified` は上記1アカウント（Xserver ビジネス・読み取り権限）での結果です。
プランや権限が異なれば同じパスでも 403 になり得ます。

### 日本語メッセージが文字化けする場合

APIのエラーメッセージは UTF-8 の日本語です。Windows のコンソールは既定で cp932 のため
化けます。PowerShell で先に実行してください:

```powershell
[Console]::OutputEncoding = [Text.Encoding]::UTF8
```

## セキュリティ

- APIキーは環境変数からのみ読み込み、ログにもツールの応答にも出力しません。
- `xserver_get` に渡されたパスは正規化のうえ検証し、`XSERVER_API_BASE` と
  ホストが一致しない URL は拒否します（`Authorization` ヘッダを別ホストへ
  送出させないため）。`..` を含むパスも拒否します。
- HTTP メソッドは GET に固定されており、書き込み系は実装されていません。
  書き込みを追加する場合は `XserverClient` にメソッドを足すことになりますが、
  誤操作のリスクを踏まえて明示的なオプトイン（環境変数など）で
  ガードすることを推奨します。

## 開発

```bash
npm run build      # dist/ へコンパイル
npm run watch      # 差分ビルド
npm run typecheck  # 型チェックのみ
npm run check      # API 疎通チェック（要 XSERVER_API_KEY）
```

`src/` の構成:

- `config.ts` — 環境変数の読み込みと検証
- `client.ts` — HTTPクライアント。認証・パス正規化・レート制限ヘッダ・エラー整形
- `endpoints.ts` — エンドポイントカタログ（確度付き）
- `tools.ts` — MCP ツールの定義と登録
- `index.ts` — stdio サーバーのエントリポイント
- `check.ts` — 疎通チェックCLI

## 実装メモ

MCP SDK は v1 系（`@modelcontextprotocol/sdk@^1.30.0`）を使用しています。
v2 系（`@modelcontextprotocol/server@2.0.0`）が 2026-07-27 にリリースされていますが、
リリース直後で各 MCP クライアントの対応状況が読めないため、広く動作実績のある
v1 系を選択しました。v1 は少なくとも v2 リリースから6か月はメンテナンスされます。

## ライセンス

MIT