Desktop Extensions (DXT) 详解

已于 2025-07-18 22:55:17 修改
阅读量1.7k 收藏 17
点赞数 49
CC 4.0 BY-SA版权
分类专栏： MCP(Model Context Protocol) 文章标签： dxt ai mcp AIGC agent
于 2025-07-14 22:58:59 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/aiqlcom/article/details/149341257

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/dxt

2. 创建扩展

# 初始化新扩展
dxt init my-extension
cd my-extension

# 开发你的MCP服务器代码
# (根据选择的服务器类型创建相应文件)

# 打包扩展
dxt pack . my-extension.dxt

3. 签名扩展（可选）

# 自签名扩展（开发用途）
dxt sign my-extension.dxt --self-signed

# 使用正式证书签名
dxt sign my-extension.dxt --cert cert.pem --key key.pem

4. 安装使用

生成的.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_versionstring是DXT规范版本
namestring是扩展的唯一标识名称
versionstring是语义化版本号
descriptionstring是简短描述
authorobject是作者信息

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服务器打包和分发格式，具有以下核心优势：

  1. 简化分发：将复杂配置封装为单文件，实现一键安装
  2. 标准化接口：通过manifest.json明确定义服务器能力和配置需求
  3. 跨平台支持：兼容Node.js、Python和二进制等多种服务器类型
  4. 用户友好：内置配置系统提供统一的用户界面
  5. 生态系统集成：支持工具和提示的声明，便于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>

该函数的主要功能包括：

  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 settings
  const mergedConfig: Record<string, unknown> = {};

  // First, add defaults from manifest
  if (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 settings
  if (userConfig) {
    Object.assign(mergedConfig, userConfig);
  }

  // Add merged configuration variables for substitution
  for (const [key, value] of Object.entries(mergedConfig)) {
    // Convert user config to the format expected by variable substitution
    const userConfigKey = `user_config.${key}`;

    if (Array.isArray(value)) {
      // Keep arrays as arrays for proper expansion
      variables[userConfigKey] = value.map(String);
    } else if (typeof value === "boolean") {
      // Convert booleans to "true"/"false" strings as per spec
      variables[userConfigKey] = value ? "true" : "false";
    } else {
      // Convert other types to strings
      variables[userConfigKey] = String(value);
    }
  }

2. 变量替换系统

DXT 系统支持多种变量替换，用于将打包的扩展适配到运行时环境： MANIFEST.md

支持的变量包括：

  • ${__dirname}: 扩展目录的绝对路径
  • ${HOME}, ${DESKTOP}, ${DOCUMENTS}, ${DOWNLOADS}: 系统目录
  • ${user_config.*}: 用户配置值
  • ${pathSeparator} 或 ${/}: 路径分隔符

架构分析

DXT 到 MCP Server 的转换流程

所以对于一个Desktop MCP Client 应用，典型的实现流程应当包括：

  1. 接收 .dxt 文件
  2. 解压缩 ZIP 档案
  3. 验证数字签名
  4. 解析 manifest.json
  5. 使用 getMcpConfigForManifest 生成 MCP 配置
  6. 启动 MCP server 进程

开源实现

由于 Claude Desktop 本身是闭源的，所以无法获知它的实际实现方式，所以我在我自己的开源项目 TUUI 中完整实现了一遍，这里提供一下使用效果：

配置界面需要配置允许访问的目录

file-system-node 默认提供了一系列用于访问本地路径的工具

LLM 自动编排工具调用来完成文件夹的访问和文件的写入

最后保持好习惯，所有代码都开源到了github：

https://www.github.com/AI-QL/tuui

对于 Window 系统的小伙伴，可以安装 nodejs 之后，直接在最新 release 中下载 zip 免安装包和对应的两个 .dxt 文件示例来体验（注意：其中 file-system-node.dxt 这个官方包的 Allowed Directory 实际是个必须配置的参数。所以需要配置之后才能正常启动 MCP Server）

对于 MacOS 的小伙伴，就比较麻烦了，我在 README 中给出了一些 ISSUE 链接，需要魔改一下 node 的安装访问路径。由于对应的问题在开源社区还是 open 状态，所以我暂时也只能保持现状，等有了较为明确的结论再调试这部分。

好了，以上就是今天的内容，睡觉去了，又要秃了。。。。

评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值