開発者必見！Desktop Extensions（DXT）公式ドキュメント完全解説〜知られざる便利機能と実践的設定〜

YaroTech｜生成AIの傾奇者

2025年7月19日 22:43

こんにちは！YaroTechです。

昨日のDXTファイル配布の記事に、引き続き公式ドキュメントを再度振り返りたいと思います！

「manifest.jsonの詳しい設定を知りたい！」
「環境変数の動的設定ってどうやるの？」
「プラットフォーム別の設定分岐は？」

そんなリクエストにお応えして、今日はDesktop Extensions（DXT）公式ドキュメントの完全解説をお届けします！

Anthropicが公開した公式仕様書と、実際に15種類以上のDXTを作成して発見した実践的なテクニックを組み合わせて、開発者に本当に役立つ情報をお届けします。

🖥️ 動作確認環境

PC: Windows 11
Claude Desktop: v0.7.2以降
開発環境: VS Code + Node.js 18+

※解説の中にはmacOSについても一部触れています。

🎯 この記事で得られること

manifest.jsonの全フィールド完全解説
テンプレート変数の活用方法
プラットフォーム別オーバーライド設定
ユーザー設定（user_config）の実装
エンタープライズ向けポリシー設定
公式ツールチェーンの使い方

📋 manifest.json完全リファレンス

基本構造と必須フィールド

{
  // 必須フィールド
  "dxt_version": "0.1",              // DXT仕様バージョン（現在は0.1）
  "name": "excel-mcp-pro",           // マシン可読名（CLI/API用）
  "version": "2.0.0",                // セマンティックバージョニング
  "description": "Excelを完全制御",  // 簡潔な説明文
  "author": {
    "name": "YaroTech"               // 作者名（必須）
  },
  
  // サーバー設定（必須）
  "server": {
    "type": "node",                 // node、python、binaryから選択
    "entry_point": "server/index.js", // エントリーポイント
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"]
    }
  }

🔥 テンプレート変数の展開機能

DXTは以下のテンプレート変数を自動展開します：

{
  "server": {
    "mcp_config": {
      "args": [
        "${__dirname}/server/index.js"      // 拡張機能のディレクトリ
      ],
      "env": {
        "HOME_DIR": "${HOME}",              // ホームディレクトリ
        "TEMP_DIR": "${TEMP}",              // 一時ディレクトリ（Windows）
        "TEMP_DIR_MAC": "${TMPDIR}",        // 一時ディレクトリ（macOS）
        "API_KEY": "${user_config.api_key}" // ユーザー設定値
      }
    }
  }
}

🎯 ユーザー設定（user_config）の活用

{
  "server": {
    "mcp_config": {
      "env": {
        "API_KEY": "${user_config.api_key}",
        "ALLOWED_DIRS": "${user_config.allowed_directories}"
      }
    }
  },
  
  // ユーザー設定の定義
  "user_config": {
    "api_key": {
      "type": "string",
      "title": "APIキー",
      "description": "サービスのAPIキーを入力してください",
      "sensitive": true,      // OSのセキュアストレージに保存
      "required": true
    },
    "allowed_directories": {
      "type": "directory",
      "title": "許可ディレクトリ",
      "description": "サーバーがアクセス可能なディレクトリ",
      "multiple": true,       // 複数選択可能
      "required": true,
      "default": ["${HOME}/Documents"]
    },
    "max_file_size": {
      "type": "number",
      "title": "最大ファイルサイズ（MB）",
      "default": 10,
      "min": 1,
      "max": 100
    }
  }
}

🖥️ プラットフォーム別オーバーライド設定

プラットフォーム固有の設定

{
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "platforms": {
        "win32": {
          "command": "node.exe",
          "env": {
            "TEMP_DIR": "${TEMP}",
            "EXCEL_PATH": "C:\\Program Files\\Microsoft Office\\root\\Office16\\EXCEL.EXE"
          }
        },
        "darwin": {
          "env": {
            "TEMP_DIR": "${TMPDIR}",
            "EXCEL_PATH": "/Applications/Microsoft Excel.app/Contents/MacOS/Microsoft Excel"
          }
        }
      }
    }
  }
}

互換性の設定

{
  "compatibility": {
    "claude_desktop": ">=1.0.0",       // 最小Claude Desktopバージョン
    "platforms": ["darwin", "win32", "linux"],  // 対応OS
    "runtimes": {
      "node": ">=16.0.0"               // Node.jsバージョン要件
    }
  }
}

🔧 実践的な完全manifest.json例

{
  "dxt_version": "0.1",
  "name": "my-mcp-extension",
  "display_name": "My Awesome MCP Extension",
  "version": "1.0.0",
  "description": "拡張機能の簡潔な説明",
  "long_description": "詳細な説明。複数段落で機能、使用例、特徴を説明できます。基本的なMarkdownをサポート。",
  
  "author": {
    "name": "Your Name",
    "email": "yourname@example.com",
    "url": "https://your-website.com"
  },
  
  "repository": {
    "type": "git",
    "url": "https://github.com/your-username/my-mcp-extension"
  },
  
  "homepage": "https://example.com/my-extension",
  "documentation": "https://docs.example.com/my-extension",
  "support": "https://github.com/your-username/my-extension/issues",
  "icon": "icon.png",
  "screenshots": [
    "assets/screenshots/screenshot1.png",
    "assets/screenshots/screenshot2.png"
  ],
  
  "keywords": ["api", "automation", "productivity"],
  "license": "MIT",
  
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "ALLOWED_DIRECTORIES": "${user_config.allowed_directories}"
      }
    }
  },
  
  "tools": [
    {
      "name": "search_files",
      "description": "ディレクトリ内のファイルを検索"
    }
  ],
  
  "prompts": [
    {
      "name": "poetry",
      "description": "詩を書くプロンプト",
      "arguments": ["topic"],
      "text": "次のトピックについて創造的な詩を書いてください: ${arguments.topic}"
    }
  ],
  
  "tools_generated": true,
  
  "compatibility": {
    "claude_desktop": ">=1.0.0",
    "platforms": ["darwin", "win32", "linux"],
    "runtimes": {
      "node": ">=16.0.0"
    }
  },
  
  "user_config": {
    "allowed_directories": {
      "type": "directory",
      "title": "許可ディレクトリ",
      "description": "サーバーがアクセス可能なディレクトリ",
      "multiple": true,
      "required": true,
      "default": ["${HOME}/Desktop"]
    },
    "api_key": {
      "type": "string",
      "title": "APIキー",
      "description": "認証用のAPIキー",
      "sensitive": true,
      "required": false
    },
    "max_file_size": {
      "type": "number",
      "title": "最大ファイルサイズ（MB）",
      "description": "処理する最大ファイルサイズ",
      "default": 10,
      "min": 1,
      "max": 100
    }
  }
}

🏢 エンタープライズ向けポリシー設定

macOSエンタープライズ設定

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>isDxtEnabled</key>
    <true/>
    <key>isDxtDirectoryEnabled</key>
    <false/>
    <key>isDxtSignatureRequired</key>
    <true/>
    <key>dxtRegistry</key>
    <string>https://registry.example.com</string>
</dict>
</plist>

Windowsレジストリ設定

# 管理者権限で実行
New-Item -Path "HKLM:\SOFTWARE\Policies\Claude" -Force
Set-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Claude" -Name "isDxtEnabled" -Value 1 -Type DWord
Set-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Claude" -Name "isDxtDirectoryEnabled" -Value 0 -Type DWord
Set-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Claude" -Name "isDxtSignatureRequired" -Value 1 -Type DWord
Set-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Claude" -Name "dxtRegistry" -Value "https://registry.example.com" -Type String

🛠️ 公式ツールチェーンの使い方

DXTパッケージの作成

# グローバルインストール
npm install -g @anthropic-ai/dxt

# manifest.jsonの初期化（対話式）
dxt init

# 高速初期化（デフォルト値で作成）
dxt init --yes

# パッケージング
dxt pack

# バリデーション
dxt validate manifest.json

プロジェクト構造

extension.dxt/
├── manifest.json        # 必須：拡張機能のメタデータ
├── server/             # サーバー実装
│   └── index.js        # エントリーポイント
├── node_modules/       # 依存関係（Node.js）
├── lib/               # 依存関係（Python）
└── icon.png           # オプション：アイコン

🚀 実践的な設定例

Node.js拡張機能の例

{
  "dxt_version": "0.1",
  "name": "excel-automation-pro",
  "display_name": "Excel Automation Pro",
  "version": "2.0.0",
  "description": "プロフェッショナル向けExcel自動化ツール",
  "author": {
    "name": "YaroTech",
    "email": "contact@yarotech.com"
  },
  
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info",
        "EXCEL_PATH": "${user_config.excel_path}"
      },
      "platforms": {
        "win32": {
          "env": {
            "DEFAULT_EXCEL": "C:\\Program Files\\Microsoft Office\\root\\Office16\\EXCEL.EXE"
          }
        },
        "darwin": {
          "env": {
            "DEFAULT_EXCEL": "/Applications/Microsoft Excel.app/Contents/MacOS/Microsoft Excel"
          }
        }
      }
    }
  },
  
  "user_config": {
    "excel_path": {
      "type": "string",
      "title": "Excelのパス",
      "description": "Microsoft Excelの実行ファイルパス",
      "required": false
    },
    "auto_save": {
      "type": "boolean",
      "title": "自動保存",
      "description": "変更を自動的に保存する",
      "default": true
    }
  }
}

Python拡張機能の例

{
  "dxt_version": "0.1",
  "name": "data-analysis-mcp",
  "version": "1.0.0",
  "description": "Pythonベースのデータ分析MCP",
  "author": {
    "name": "YaroTech"
  },
  
  "server": {
    "type": "python",
    "entry_point": "server/main.py",
    "mcp_config": {
      "command": "python",
      "args": ["${__dirname}/server/main.py"],
      "env": {
        "PYTHONPATH": "${__dirname}/lib",
        "DATA_DIR": "${user_config.data_directory}"
      }
    }
  },
  
  "user_config": {
    "data_directory": {
      "type": "directory",
      "title": "データディレクトリ",
      "description": "分析対象のデータが格納されているディレクトリ",
      "required": true,
      "default": ["${HOME}/Documents/Data"]
    }
  }
}

💡 実装のベストプラクティス

1. ツールとプロンプトの宣言

{
  "tools": [
    {
      "name": "read_file",
      "description": "ファイルの内容を読み取る"
    },
    {
      "name": "write_file",
      "description": "ファイルに内容を書き込む"
    }
  ],
  
  "prompts": [
    {
      "name": "code_review",
      "description": "コードレビューを実行",
      "arguments": ["file_path"],
      "text": "次のファイルのコードレビューを実施してください: ${arguments.file_path}"
    }
  ],
  
  "tools_generated": true  // ツールが動的に生成される場合
}

2. エラーハンドリング

// server/index.js
process.on('uncaughtException', (error) => {
  console.error('Uncaught Exception:', error);
  // グレースフルシャットダウン
  process.exit(1);
});

// タイムアウト管理
const TIMEOUT = 30000; // 30秒
setTimeout(() => {
  console.error('Operation timed out');
  process.exit(1);
}, TIMEOUT);

3. 開発とデバッグ

# ローカルでのテスト
claude-desktop --dev-extension ./my-extension

# ログの確認
# macOS: ~/Library/Logs/Claude/extensions.log
# Windows: %APPDATA%\Claude\logs\extensions.log

# バリデーション
dxt validate manifest.json

🔍 よくあるトラブルと解決策

1. 拡張機能がインストールできない

# manifest.jsonの検証
dxt validate manifest.json

# よくあるエラー
- "dxt_version"フィールドが不足
- author.nameが未設定
- server設定の不備

2. ツールが表示されない

// MCPサーバーの実装確認
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// 正しいツール登録
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'my_tool',
        description: 'ツールの説明',
        inputSchema: {
          type: 'object',
          properties: {
            // パラメータ定義
          }
        }
      }
    ]
  };
});

📚 公式リソースとコミュニティ

公式ドキュメント

拡張機能の提出

# 1. ガイドラインの確認
# 2. Windows/macOSでのテスト
# 3. セキュリティレビュー
# 4. 提出フォームから申請

拡張機能を提出する

コミュニティ

GitHub Discussions
Discord サーバー
開発者フォーラム

💬 まとめ

DXTファイルの公式ドキュメントには、想像以上に多くの機能が隠されていました。自作MCPのDXTファイルがうまく作れて読み込ませるこんな感じになりました！

インストールから先の結果は別途、投稿したいと思います！

今回紹介した設定を活用すれば、エンタープライズレベルのMCP配布も、開発者向けのデバッグ環境も、すべて実現できます。

特に環境変数の動的展開とプラットフォーム別設定は、クロスプラットフォーム対応の鍵となる機能です。

Desktop Extensionsは、MCPサーバーの配布を革命的に簡単にしました。公式ツールチェーンとこれらの設定を活用すれば、プロフェッショナルで使いやすい拡張機能を作成できます。

特に重要なのは：

`dxt_version: "0.1"`の指定（必須）
`${__dirname}`と`${user_config.*}`の活用
プラットフォーム別オーバーライド
セキュアな設定管理（sensitive: true）

シェアの際は #DXT完全解説 #MCP開発 #公式ドキュメント #YaroTech をつけていただけると嬉しいです。

💬 質問・リクエスト

「この設定の意味がわからない」
「もっと詳しく知りたい機能がある」
「実装で困っていることがある」

コメント欄でお気軽にどうぞ！土曜日なので、ゆっくりお答えします😊

🔗 関連記事

Day12: 君のMCPを世界へ配布！DXTファイル化の魔法

Day5: Excel自動化MCPを自作してみた

Day11: さよなら黒い画面！新機能でポチポチ設定

📚 参考リソース

🏷️ タグ
#DXT完全解説 #DesktopExtensions #MCP開発 #ClaudeDesktop #YaroTech #manifest設定 #開発者向け #土曜日の技術記事 #生成AI #Anthropic