DXT Manifest.json 规范

2025-06-29 5 minute read

该文档概述了 DXT Manifest.json 规范，这是一个用于定义扩展元数据和配置的JSON文件标准。它详细说明了 manifest.json 文件的结构，包括 必填字段 如版本、名称、作者和服务器配置，以及 可选字段 如显示名称、描述、存储库信息和屏幕截图。此外，规范还涵盖了 兼容性要求（针对客户端、平台和运行时）、服务器配置（支持Python、Node.js和二进制类型，并允许平台特定覆盖和变量替换），以及 用户可配置选项 的定义和传递方式。最后，文档解释了如何声明扩展提供的 工具和提示，并支持动态生成这些功能。

Manifest 结构

manifest.json 文件包含所有扩展的元数据和配置。大多数字段是可选的。

一个只包含必填字段的基本 manifest.json 如下所示：

{
  "dxt_version": "0.1", // 此 manifest 符合的 DXT 规范版本
  "name": "my-extension", // 机器可读名称（用于 CLI、API）
  "version": "1.0.0", // 您的扩展的语义化版本
  "description": "一个简单的 MCP 扩展", // 扩展功能的简要描述
  "author": {
    // 作者信息（必填）
    "name": "Extension Author" // 作者姓名（必填字段）
  },
  "server": {
    // 服务器配置（必填）
    "type": "node", // 服务器类型："node"、"python" 或 "binary"
    "entry_point": "server/index.js", // 主服务器文件的路径
    "mcp_config": {
      // MCP 服务器配置
      "command": "node", // 运行服务器的命令
      "args": [
        // 传递给命令的参数
        "${__dirname}/server/index.js" // ${__dirname} 会被替换为扩展的目录
      ]
    }
  }
}

{
  "dxt_version": "0.1",
  "name": "my-extension",
  "version": "1.0.0",
  "description": "一个简单的 MCP 扩展",
  "author": {
    "name": "Extension Author"
  },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "API_KEY": "${user_config.api_key}"
      }
    }
  },
  "user_config": {
    "api_key": {
      "type": "string",
      "title": "API 密钥",
      "description": "用于身份验证的 API 密钥",
      "sensitive": true,
      "required": true
    }
  }
}

一个包含大部分可选字段的完整 manifest.json 如下所示：

{
  "dxt_version": "0.1",
  "name": "My MCP Extension",
  "display_name": "我的超棒 MCP 扩展",
  "version": "1.0.0",
  "description": "关于此扩展功能的简要描述",
  "long_description": "详细描述，可以包含多个段落，解释扩展的功能、用例和特性。支持基本的 markdown。",
  "author": {
    "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"
  ],
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["server/index.js"],
      "env": {
        "ALLOWED_DIRECTORIES": "${user_config.allowed_directories}"
      }
    }
  },
  "tools": [
    {
      "name": "search_files",
      "description": "在目录中搜索文件"
    }
  ],
  "prompts": [
    {
      "name": "poetry",
      "description": "让 LLM 写诗",
      "arguments": ["topic"],
      "text": "围绕以下主题写一首有创意的诗：${arguments.topic}"
    }
  ],
  "tools_generated": true,
  "keywords": ["api", "automation", "productivity"],
  "license": "MIT",
  "compatibility": {
    "claude_desktop": ">=1.0.0",
    "platforms": ["darwin", "win32", "linux"],
    "runtimes": {
      "python": ">=3.8",
      "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
    }
  }
}

字段定义

必填字段

dxt_version: 此扩展遵循的规范版本
name: 机器可读名称（用于 CLI、API）
version: 语义化版本 (semver)
description: 简要描述
author: 作者信息对象，包含 name（必填）、email（可选）和 url（可选）
server: 服务器配置对象

可选字段

icon: 指向 png 图标文件的路径，可以是包内的相对路径或 https:// 网址。
display_name: 用于 UI 显示的用户友好名称
long_description: 用于扩展商店的详细描述，支持 markdown
repository: 源代码仓库信息（类型和 url）
homepage: 扩展主页 URL
documentation: 文档 URL
support: 支持/问题跟踪 URL
screenshots: 屏幕截图路径数组
tools: 扩展提供的工具数组
tools_generated: 布尔值，指示服务器是否在运行时生成额外的工具（默认为 false）
prompts: 扩展提供的提示数组
prompts_generated: 布尔值，指示服务器是否在运行时生成额外的提示（默认为 false）
keywords: 搜索关键词
license: 许可证标识符
compatibility: 兼容性要求（客户端应用版本、平台和运行时版本）
user_config: 扩展的用户可配置选项（参见用户配置部分）

兼容性

compatibility 对象指定了运行扩展的所有要求。所有字段，包括 compatibility 字段本身，都是可选的。如果您什么都不指定，鼓励实现 DXT 的客户端在任何系统上运行该扩展。

{
  "compatibility": {
    "claude_desktop": ">=1.0.0",
    "my_client": ">1.0.0",
    "other_client": ">=2.0.0 <3.0.0",
    "platforms": ["darwin", "win32", "linux"],
    "runtimes": {
      "python": ">=3.8",
      "node": ">=16.0.0"
    }
  }
}

字段

客户端版本约束

兼容性对象支持任何客户端应用程序的版本约束：

claude_desktop: 所需的最低 Claude Desktop 版本（使用 semver）
my_client: 自定义客户端的版本约束（使用 semver）
其他客户端名称: 您可以为任何客户端应用程序添加版本约束

所有客户端版本约束都使用 semver 语法（例如 ">=1.0.0"、">1.0.0 <2.0.0"、"^1.2.3"）。

系统要求

platforms: 支持的平台数组（darwin、win32、linux）。这些值与 Node.js 的 process.platform 和 Python 的 sys.platform 值相匹配。如果省略，则支持所有平台。
runtimes: 运行时版本要求
- 仅指定您的扩展实际使用的运行时
- 对于 Python 扩展：指定 python 版本
- 对于 Node.js 扩展：指定 node 版本
- 二进制扩展不需要运行时规范

注意：macOS 使用 darwin，Windows 使用 win32，Linux 系统使用 linux。

示例

Python 扩展：

{
  "server": {
    "type": "python",
    "entry_point": "server/main.py"
  },
  "compatibility": {
    "claude_desktop": ">=0.10.0",
    "platforms": ["darwin", "win32", "linux"],
    "runtimes": {
      "python": ">=3.8,<4.0"
    }
  }
}

仅支持 macOS 的 Node.js 扩展：

{
  "server": {
    "type": "node",
    "entry_point": "server/index.js"
  },
  "compatibility": {
    "claude_desktop": ">=0.10.0",
    "platforms": ["darwin"],
    "runtimes": {
      "node": ">=16.0.0"
    }
  }
}

二进制扩展（无需运行时）：

{
  "server": {
    "type": "binary",
    "entry_point": "server/my-tool"
  },
  "compatibility": {
    "claude_desktop": ">=0.10.0",
    "platforms": ["darwin", "win32"]
  }
}

服务器配置

server 对象定义了如何运行 MCP 服务器：

服务器类型

Python: server.type = "python"
- 要求 entry_point 指向 Python 文件
- 所有依赖项必须打包在 DXT 中
- 可以使用 server/lib 存放包，或使用 server/venv 存放完整的虚拟环境
- Python 运行时版本在 compatibility.runtimes.python 中指定
Node.js: server.type = "node"
- 要求 entry_point 指向 JavaScript 文件
- 所有依赖项必须打包在 node_modules 中
- Node.js 运行时版本在 compatibility.runtimes.node 中指定
- 通常在扩展根目录包含 package.json 用于依赖管理
Binary: server.type = "binary"
- 包含所有依赖项的预编译可执行文件
- 支持特定于平台（platform-specific）的二进制文件
- 完全自包含（无运行时要求）

MCP 配置

服务器配置中的 mcp_config 对象定义了实现此规范的应用应如何执行 MCP 服务器。这取代了用户当前需要手动编写的 JSON 配置。

Python 示例：

"mcp_config": {
  "command": "python",
  "args": ["server/main.py"],
  "env": {
    "PYTHONPATH": "server/lib"
  }
}

Node.js 示例：

"mcp_config": {
  "command": "node",
  "args": ["${__dirname}/server/index.js"],
  "env": {}
}

二进制示例（跨平台）：

"mcp_config": {
  "command": "server/my-server",
  "args": ["--config", "server/config.json"],
  "env": {}
}

注意：对于二进制文件，应用在 Windows 上会自动附加 .exe 后缀

特定于平台的配置： 对于不同平台需要不同配置的情况，请使用特定于平台的覆盖（overrides）：

"mcp_config": {
  "command": "server/my-server",
  "args": ["--config", "server/config.json"],
  "env": {},
  "platform_overrides": {
    "win32": {
      "command": "server/my-server.exe",
      "args": ["--config", "server/config-windows.json"]
    },
    "darwin": {
      "env": {
        "DYLD_LIBRARY_PATH": "server/lib"
      }
    }
  }
}

安装扩展时，应用将自动生成适当的 MCP 服务器配置并将其添加到用户的设置中，从而无需手动编辑 JSON。

变量替换： 实现此规范的桌面应用将在 mcp_config 中替换变量，以使扩展更具可移植性：

${__dirname}: 此变量被替换为扩展目录的绝对路径。这对于引用扩展包内的文件很有用。
${HOME}: 用户的主目录
${DESKTOP}: 用户的桌面目录
${DOCUMENTS}: 用户的文档目录
${DOWNLOADS}: 用户的下载目录
${pathSeparator} 或 ${/}: 当前平台的路径分隔符

示例：

"mcp_config": {
  "command": "python",
  "args": ["${__dirname}/server/main.py"],
  "env": {
    "CONFIG_PATH": "${__dirname}/config/settings.json"
  }
}

这确保了无论扩展安装在用户系统的哪个位置，路径都能正常工作。

${user_config}: 您的扩展可以指定由用户配置的值，实现此规范的应用将从用户那里收集这些值。请继续阅读以了解有关用户配置的更多信息。

用户配置

user_config 字段允许扩展开发者指定配置选项，这些选项可以通过实现此规范的应用的用户界面呈现给最终用户。这些配置从用户处收集，并在运行时传递给 MCP 服务器。

配置结构

每个配置选项都定义为一个键值对，其中键是配置名称，值是具有以下属性的对象：

type: 配置的数据类型
- "string": 文本输入
- "number": 数字输入
- "boolean": 复选框/开关
- "directory": 目录选择器
- "file": 文件选择器
title: 在 UI 中显示的名称
description: 解释配置选项的帮助文本
required: 是否必须提供此字段（默认为 false）
default: 默认值（支持变量替换）
multiple: 对于目录/文件类型，是否允许选择多个（默认为 false）
sensitive: 对于字符串类型，是否屏蔽输入并安全存储（默认为 false）
min/max: 对于数字类型，验证约束

用户配置中的变量替换

用户配置值支持在 mcp_config 中进行变量替换：

${user_config.KEY}: 替换为用户为配置 KEY 提供的值
数组（来自多选）将作为单独的参数展开
环境变量是敏感数据的理想选择
命令参数适用于路径和非敏感选项

可用于默认值的变量：

${HOME}: 用户的主目录
${DESKTOP}: 用户的桌面目录
${DOCUMENTS}: 用户的文档目录

示例

带目录配置的文件系统扩展：

{
  "user_config": {
    "allowed_directories": {
      "type": "directory",
      "title": "允许的目录",
      "description": "选择文件系统服务器可以访问的目录",
      "multiple": true,
      "required": true,
      "default": ["${HOME}/Desktop", "${HOME}/Documents"]
    }
  },
  "server": {
    "mcp_config": {
      "command": "node",
      "args": [
        "${__dirname}/server/index.js",
        "${user_config.allowed_directories}"
      ]
    }
  }
}

带身份验证的 API 集成：

{
  "user_config": {
    "api_key": {
      "type": "string",
      "title": "API 密钥",
      "description": "用于身份验证的 API 密钥",
      "sensitive": true,
      "required": true
    },
    "base_url": {
      "type": "string",
      "title": "API 基础 URL",
      "description": "API 请求的基础 URL",
      "default": "https://api.example.com",
      "required": false
    }
  },
  "server": {
    "mcp_config": {
      "command": "node",
      "args": ["server/index.js"],
      "env": {
        "API_KEY": "${user_config.api_key}",
        "BASE_URL": "${user_config.base_url}"
      }
    }
  }
}

数据库连接配置：

{
  "user_config": {
    "database_path": {
      "type": "file",
      "title": "数据库文件",
      "description": "您的 SQLite 数据库文件的路径",
      "required": true
    },
    "read_only": {
      "type": "boolean",
      "title": "只读模式",
      "description": "以只读模式打开数据库",
      "default": true
    },
    "timeout": {
      "type": "number",
      "title": "查询超时（秒）",
      "description": "查询执行的最长时间",
      "default": 30,
      "min": 1,
      "max": 300
    }
  },
  "server": {
    "mcp_config": {
      "command": "python",
      "args": [
        "server/main.py",
        "--database",
        "${user_config.database_path}",
        "--timeout",
        "${user_config.timeout}"
      ],
      "env": {
        "READ_ONLY": "${user_config.read_only}"
      }
    }
  }
}

实现说明

数组展开: 当 multiple: true 的配置在 args 中使用时，每个值都会被展开为单独的参数。例如，如果用户选择了目录 /home/user/docs 和 /home/user/projects，那么 args ["${user_config.allowed_directories}"] 会变成 ["/home/user/docs", "/home/user/projects"]。

工具和提示

这些字段描述了您的 MCP 服务器提供的工具和提示。对于在运行时动态生成功能的服务器，您可以使用 _generated 标志来表明这一点。

注意：资源不包含在 manifest 中，因为 MCP 资源本质上是动态的——它们代表了服务器在运行时根据配置、文件系统状态、数据库连接等发现的数据的 URI。

静态声明

对于具有固定功能集的服务器，请将它们列在数组中。

提示结构

prompts 数组中的每个提示必须包含：

name: 提示的标识符
description (可选): 解释提示的作用
arguments (可选): 可在提示文本中使用的参数名称数组
text: 实际的提示文本，使用像 ${arguments.topic} 或 ${arguments.aspect} 这样的模板变量作为 MCP 客户端提供参数的占位符。如果您的参数名为 language，您应在希望它出现的位置添加 ${arguments.language}。

示例：

{
  "tools": [
    { "name": "search_files", "description": "搜索文件" },
    { "name": "read_file", "description": "读取文件内容" }
  ],
  "prompts": [
    {
      "name": "explain_code",
      "description": "解释代码如何工作",
      "arguments": ["code", "language"],
      "text": "请详细解释以下 ${arguments.language} 代码：\n\n${arguments.code}"
    }
  ]
}

实现此规范的应用可以选择在运行时根据您在 manifest 中的提示声明来验证提示。

动态生成

对于根据上下文、配置或运行时发现来生成功能的服务器，请使用 _generated 标志：

{
  "tools": [{ "name": "search", "description": "搜索功能" }],
  "tools_generated": true,
  "prompts_generated": true
}

这表明：

服务器至少提供 search 工具（可能还有更多）
额外的工具在运行时生成
提示在运行时生成

_generated 字段：

tools_generated: 服务器生成除所列工具之外的额外工具（默认为 false）
prompts_generated: 服务器生成除所列提示之外的额外提示（默认为 false）

这有助于实现此规范的应用理解，在运行时查询服务器将揭示比 manifest 中声明的更多的功能。