Desktop Extensions (DXT) 详解
Desktop Extensions (DXT) 详解
什么是Desktop Extensions (DXT)？
Desktop Extensions (DXT，桌面扩展) 是一种用于打包和分发本地MCP (Model Context Protocol) 服务器的标准化格式。它类似于Chrome扩展(.crx)或VS Code扩展(.vsix)，允许用户通过单次点击安装本地MCP服务器。
Desktop Extensions
https://www.anthropic.com/engineering/desktop-extensions
DXT的核心是一个包含以下内容的ZIP压缩包： - 完整的本地MCP服务器代码/二进制文件 - 描述扩展功能和配置的manifest.json文件 - 其他资源文件（如图标、配置文件等）
DXT的主要特点
| 特点 (Feature) | 描述 (Description) | 优势 (Advantage) |
|---|---|---|
| 单文件分发 (Single-file distribution) | 所有内容打包在一个.dxt文件中 | 简化安装和分发过程 |
| 标准化配置 (Standardized configuration) | 通过manifest.json定义服务器配置 | 消除手动配置错误 |
| 跨平台支持 (Cross-platform support) | 支持Node.js、Python和二进制服务器 | 开发者可自由选择技术栈 |
| 用户配置集成 (User configuration integration) | 内置用户配置系统 | 提供统一的配置界面 |
| 自动更新 (Automatic updates) | 支持扩展版本管理和更新 | 确保用户使用最新版本 |
DXT使用方法
1. 安装CLI工具
npm install -g @anthropic-ai/dxt2. 创建扩展
# 初始化新扩展
dxt init my-extension
cd my-extension# 开发你的MCP服务器代码
# (根据选择的服务器类型创建相应文件)# 打包扩展
dxt pack . my-extension.dxt3. 签名扩展（可选）
# 自签名扩展（开发用途）
dxt sign my-extension.dxt --self-signed# 使用正式证书签名
dxt sign my-extension.dxt --cert cert.pem --key key.pem4. 安装使用
生成的.dxt文件可直接在支持DXT格式的应用程序中安装使用。由于所有文件已预先打包，安装过程仅需解压即可。
Manifest定义详解
基本结构
{"dxt_version": "0.1","name": "my-extension","version": "1.0.0","description": "A simple MCP extension","author": {"name": "Extension Author"},"server": {"type": "node","entry_point": "server/index.js","mcp_config": {"command": "node","args": ["${__dirname}/server/index.js"]}}
}关键字段说明
1. 元数据部分 (Metadata)
| 字段 (Field) | 类型 (Type) | 必填 (Required) | 描述 (Description) |
|---|---|---|---|
| dxt_version | string | 是 | DXT规范版本 |
| name | string | 是 | 扩展的唯一标识名称 |
| version | string | 是 | 语义化版本号 |
| description | string | 是 | 简短描述 |
| author | object | 是 | 作者信息 |
2. 服务器配置 (Server Configuration)
"server": {"type": "python","entry_point": "server/main.py","mcp_config": {"command": "python","args": ["server/main.py"],"env": {"PYTHONPATH": "server/lib","API_KEY": "${user_config.api_key}"},"platform_overrides": {"win32": {"command": "python.exe"}}}
}这里定义了服务端的核心配置，其中mcp_config部分是与 MCP 兼容的实际运行时配置，而外层的type和entry_point字段提供了更抽象的接口定义，为未来可能的扩展保留了灵活性。两者内容本质上是相关的，但外层配置提供了更高层次的抽象。
服务器类型支持：
node: Node.js服务器python: Python服务器binary: 预编译二进制
3. 用户配置 (User Configuration)
"user_config": {"api_key": {"type": "string","title": "API Key","description": "Your API key for authentication","sensitive": true,"required": true},"max_file_size": {"type": "number","title": "Maximum File Size (MB)","description": "Maximum file size to process","default": 10,"min": 1,"max": 100}
}配置类型支持：
string: 文本输入number: 数字输入boolean: 复选框/开关directory: 目录选择器file: 文件选择器
directory 和 file 在实际类型定义里，其实是 string | string[ ] 。所以可以通过 multiple 参数来控制配置一个或者多个可访问的路径或者文件。
4. 工具和提示定义 (Tools and Prompts)
"tools": [{"name": "search_files","description": "Search for files in a directory"}
],
"prompts": [{"name": "explain_code","description": "Explain how code works","arguments": ["code", "language"],"text": "Explain this ${arguments.language} code:\n${arguments.code}"}
],
"tools_generated": true,
"prompts_generated": false实际应用示例
文件搜索扩展示例
{"dxt_version": "0.1","name": "file-search","display_name": "File Search Extension","version": "1.0.0","description": "Allows searching files in specified directories","author": {"name": "Search Tools Inc.","email": "support@searchtools.com"},"server": {"type": "node","entry_point": "server/index.js","mcp_config": {"command": "node","args": ["${__dirname}/server/index.js"],"env": {"SEARCH_PATHS": "${user_config.search_dirs}"}}},"user_config": {"search_dirs": {"type": "directory","title": "Search Directories","description": "Directories to include in searches","multiple": true,"required": true,"default": ["${HOME}/Documents"]},"max_depth": {"type": "number","title": "Maximum Search Depth","description": "How many subdirectory levels to search","default": 3,"min": 1,"max": 10}},"tools": [{"name": "search_files","description": "Search for files by name or content"},{"name": "get_file_info","description": "Get information about a file"}],"compatibility": {"claude_desktop": ">=1.2.0","platforms": ["darwin", "win32", "linux"],"runtimes": {"node": ">=16.0.0"}}
}以上是一个 manifest.json 文件的完整配置示例，供大家参考。
总结
Desktop Extensions (DXT，桌面扩展) 是一种创新的本地MCP服务器打包和分发格式，具有以下核心优势：
- 简化分发：将复杂配置封装为单文件，实现一键安装
- 标准化接口：通过manifest.json明确定义服务器能力和配置需求
- 跨平台支持：兼容Node.js、Python和二进制等多种服务器类型
- 用户友好：内置配置系统提供统一的用户界面
- 生态系统集成：支持工具和提示的声明，便于AI应用集成
DXT特别适合需要与桌面AI应用集成的本地服务场景，如：
- 文件系统访问工具
- 本地数据库查询接口
- 专业软件集成插件
- 自定义自动化工具
通过标准化和简化本地MCP服务器的分发流程，DXT有望成为AI桌面应用生态系统中重要的组成部分。
上手开发 DXT
关于 DXT 的使用操作，网上已有大量演示。今天我们将重点讲解如何利用官方 GitHub 库进行开发。
Anthropics DXThttps://github.com/anthropics/dxt
DXT 库主要提供了用于创建和打包 DXT 文件的接口，并且提供解压缩已打包的 DXT 文件并转换为 MCP server 的功能。
现有的解压缩和转换接口
1. 核心配置转换接口
库中提供了 getMcpConfigForManifest 函数，这是将 DXT 扩展转换为 MCP server 配置的核心接口： config.ts:
export async function getMcpConfigForManifest(options: GetMcpConfigForManifestOptions,
): Promise<McpServerConfig | undefined>
该函数的主要功能包括：
- 解析 DXT manifest 中的
mcp_config配置:
const baseConfig = manifest.server?.mcp_config;if (!baseConfig) {return undefined;}
- 处理平台特定的配置覆盖:
if (baseConfig.platform_overrides) {if (process.platform in baseConfig.platform_overrides) {const platformConfig = baseConfig.platform_overrides[process.platform];result.command = platformConfig.command || result.command;result.args = platformConfig.args || result.args;result.env = platformConfig.env || result.env;}}
- 执行变量替换，包括
${__dirname}、${user_config.*}等:
const variables: Record<string, string | string[]> = {__dirname: extensionPath,pathSeparator,"/": pathSeparator,...systemDirs,};// Build merged configuration from defaults and user settingsconst mergedConfig: Record<string, unknown> = {};// First, add defaults from manifestif (manifest.user_config) {for (const [key, configOption] of Object.entries(manifest.user_config)) {if (configOption.default !== undefined) {mergedConfig[key] = configOption.default;}}}// Then, override with user settingsif (userConfig) {Object.assign(mergedConfig, userConfig);}// Add merged configuration variables for substitutionfor (const [key, value] of Object.entries(mergedConfig)) {// Convert user config to the format expected by variable substitutionconst userConfigKey = `user_config.${key}`;if (Array.isArray(value)) {// Keep arrays as arrays for proper expansionvariables[userConfigKey] = value.map(String);} else if (typeof value === "boolean") {// Convert booleans to "true"/"false" strings as per specvariables[userConfigKey] = value ? "true" : "false";} else {// Convert other types to stringsvariables[userConfigKey] = String(value);}}
2. 变量替换系统
DXT 系统支持多种变量替换，用于将打包的扩展适配到运行时环境： MANIFEST.md
支持的变量包括：
${__dirname}: 扩展目录的绝对路径${HOME},${DESKTOP},${DOCUMENTS},${DOWNLOADS}: 系统目录${user_config.*}: 用户配置值${pathSeparator}或${/}: 路径分隔符
架构分析
DXT 到 MCP Server 的转换流程
所以对于一个Desktop MCP Client 应用，典型的实现流程应当包括：
- 接收 .dxt 文件
- 解压缩 ZIP 档案
- 验证数字签名
- 解析 manifest.json
- 使用
getMcpConfigForManifest生成 MCP 配置 - 启动 MCP server 进程
开源实现
由于 Claude Desktop 本身是闭源的，所以无法获知它的实际实现方式，所以我在我自己的开源项目 TUUI 中完整实现了一遍，这里提供一下使用效果：
配置界面需要配置允许访问的目录
file-system-node 默认提供了一系列用于访问本地路径的工具
LLM 自动编排工具调用来完成文件夹的访问和文件的写入
最后保持好习惯，所有代码都开源到了github：
https://github.com/AI-QL/tuuigithub.com/AI-QL/tuui
对于 Window 系统的小伙伴，可以安装 nodejs 之后，直接在最新 release 中下载 Portable 包和对应的两个 .dxt 文件示例来体验（注意：其中 file-system-node.dxt 这个官方包的 Allowed Directory 实际是个必须配置的参数。所以需要配置之后才能正常启动 MCP Server）
对于 MacOS 的小伙伴，就比较麻烦了，我在 README 中给出了一些 ISSUE 链接，需要魔改一下 node 的安装访问路径。由于对应的问题在开源社区还是 open 状态，所以我暂时也只能保持现状，等有了较为明确的结论再调试这部分。
好了，以上就是今天的内容，睡觉去了，又要秃了。。。。