# @atlaskit/ads-mcp 中文文档
规范地址：https://npmcn.com/package/%40atlaskit/ads-mcp/
版本：1\.12\.5
npm 元数据更新时间：2026-11-05T17:41:12.933Z
中文译文更新时间：2026-11-07T02:29:59.100Z
软件包许可：Apache-2\.0
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40atlaskit/ads-mcp
原文对照：https://npmcn.com/package/%40atlaskit/ads-mcp/?lang=original
项目主页：https://atlassian.design/llms.txt
源码仓库：https://bitbucket.org/atlassian/atlassian-frontend-mirror
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：16.6 MB，496 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：16 个
- 首次发布：2025-06-06T05:08:10.824Z
- 最新版本发布：2026-11-05T17:41:12.750Z
- 近 30 天下载量：5700（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：133（近 12 个月 99 个）
## 中文简介
官方的Atlassian Design System MCP服务器,开发与Atlassian风格相匹配的应用程序和用户界面.
## 安装
```sh
npm install @atlaskit/ads-mcp
```
也可以使用：`pnpm add @atlaskit/ads-mcp`、`yarn add @atlaskit/ads-mcp`、`bun add @atlaskit/ads-mcp`
## README
# Atlassian设计系统 MCP 服务器
当前状态: 早期访问
阿特拉斯斯设计系统的官方模型背景协议(MCP)服务器. 这个服务器 提供在程序上访问设计标志、图标和组件/原物的工具.
**新建: 远程 MCP 服务器** ADS MCP服务器的主机版本现在可在 `https://mcp.atlassian.com/v1/ads/public/mcp`。简单地将您的 MCP 客户端指向此 URL 以获取 开始 。 见 [使用量](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-usage) 每个IDE配置示例的章节.
或者,只需点击下面的一个按钮即可轻松地将服务器添加到Cursor或VS代码.
 
**新建:无障碍分析和指导** 服务器现在包括全面的无障碍工具 来帮助确保您的界面向所有用户开放.
## 目录
- [可用工具](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-available-tools)
- [设计系统工具](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-design-system-tools)
- [阿特拉斯基特倒计时研究工具](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-atlaskit-fallback-research-tools)
- [无障碍工具](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-accessibility-tools)
- [无障碍特性](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-accessibility-features)
- [示例使用](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-example-usage)
- [使用量](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-usage)
- [AFM 用户(仅限内部地图集)](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-for-afm-users-internal-atlassians-only)
- [非AFM 用户](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-for-non-afm-users)
- [光标 IDE](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-cursor-ide)
- [当地( stdio)](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-local-stdio)
- [远程](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-remote)
- [视觉工作室代码](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-visual-studio-code)
- [Github 副驾驶](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-github-copilot)
- [当地( stdio)](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-local-stdio-1)
- [远程](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-remote-1)
- [法典](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-codelassian)
- [当地( stdio)](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-local-stdio-2)
- [远程](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-remote-2)
- [罗沃德夫](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-rovodev)
- [当地( stdio)](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-local-stdio-3)
- [远程](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-remote-3)
- [Atlas CLI 的 MCP 插件](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-mcp-plugin-for-atlas-cli)
- [环境变量](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-environment-variables)
- [分析](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-analytics)
- [我们追踪的是什么](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-what-we-track)
- [隐私处理出错( E)](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-privacy--error-handling)
- [发展](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-development)
- [问题](https://npmcn.com/package/%40atlaskit/ads-mcp/#readme-faqs)
## 可用工具
### 设计系统工具
- `ads_get_all_tokens` - 获得所有可用的颜色、间距、打字等设计标志.
- `ads_search_tokens` - 按名称、说明或示例值搜索具体设计符号
- `ads_get_all_components` - 获得所有具有基本信息(完整目录)的犬类ADS组件
- `ads_search_components` - 按名称、说明、类别、或 软件包名称
- `ads_get_all_icons` - 从设计系统中获取所有可用的图标
- `ads_search_icons` - 按名称、关键词或分类搜索特定图标
- `ads_plan` - 单独搜索多个设计系统资源(托盘、图标、组件) 高效运行
使用 `ads_*` 工具首先用于标准的 UI 工作。 它们是ADS组件的犬类来源, 符号,图标,地基,无障碍,线条规则,i18n,和迁移.
### 阿特拉斯基特倒计时研究工具
- `atlaskit_get_components` - 获得一份简明的公众清单 `@atlaskit/*` 组件包 aDS 目录之外
- `atlaskit_search_components` - 公开搜索非ADS `@atlaskit/*` 包含实例和 道具
- `atlaskit_get_hooks` - 获得一份简明的公众清单 `@atlaskit/*` aDS 系统外的钩子 目录
- `atlaskit_search_hooks` - 公开搜索非ADS `@atlaskit/*` 带有使用细节的钩子
- `atlaskit_get_utilities` - 获得一份简明的公众清单 `@atlaskit/*` 水电费 ADS 目录
- `atlaskit_search_utilities` - 公开搜索非ADS `@atlaskit/*` 水电费及使用详情
使用 `atlaskit_*` 当ADS搜索没有有用的匹配时, 或者当您是时, 用于倒置研究的工具 寻找公众 `@atlaskit/*` 软件包不属于ADS。 不将Atlaskit结果视为 标准UI决定中ADS组件的等优先置换.
#### 设计系统工具使用
```typescript
// Search for canonical ADS components (recommended approach)
const buttonComponents = await ads_search_components({
terms: ['button', 'click'],
limit: 3,
});
// Search for specific tokens
const colorTokens = await ads_search_tokens({
terms: ['color.text', 'primary'],
limit: 5,
});
// Search for icons
const addIcons = await ads_search_icons({
terms: ['add', 'plus', 'create'],
limit: 2,
});
// Search for multiple resources at once (most efficient for complex UI patterns)
const designResources = await ads_plan({
tokens: ['color.text', 'space.100', 'radius.small'],
icons: ['add', 'edit', 'delete'],
components: ['Button', 'TextField', 'Modal'],
atlaskitComponents: [],
limit: 2,
});
// Search public @atlaskit/* packages only when ADS has no useful match
const atlaskitComponents = await atlaskit_search_components({
terms: ['editor-core', 'onboarding'],
limit: 2,
});
// Get all available items (fallback when search doesn't find what you need)
const allComponents = await ads_get_all_components();
const allTokens = await ads_get_all_tokens();
const allIcons = await ads_get_all_icons();
```
### 无障碍工具
- `ads_analyze_a11y` - 利用轴心和 提供特定ADS建议
- `ads_analyze_localhost_a11y` - 分析整个网页或具体要素(当地主机或已部署) URL)针对侵犯无障碍环境的行为
- `ads_get_a11y_guidelines` - 为不同部门获得具体的无障碍准则和最佳做法 专题
- `ads_suggest_a11y_fixes` - 获得关于违反无障碍规定的具体固定建议 实例
## 无障碍特性
ADS MCP服务器包括全面无障碍分析和指导:
- **轴心分析**使用轴心的工业标准无障碍测试
- **JSX 到 HTML 转换**: 通过将 React JSX 转换为 HTML 进行精确分析
- **ADS 特定修复**: 获取使用Atlassian设计系统组件和模式的建议
- **WCAG 2.1 AA 遵守情况**: 对照WCAG 2.1 AA标准进行试验
- **准则**: 获取按钮、窗体、图像、颜色、焦点的详细无障碍准则 管理,以及
- **最佳做法**:学习与ADS相关的无障碍最佳做法和模式
- **后退分析**: 如果轴- 核心分析失败, 则基于模式的分析
### 示例使用
```typescript
// Analyze a component for accessibility issues using axe-core
const analysis = await ads_analyze_a11y({
code: ``,
componentName: 'CloseButton',
includePatternAnalysis: true, // Also include pattern-based analysis
});
// Get specific accessibility guidelines
const guidelines = await ads_get_a11y_guidelines({
topic: 'buttons',
});
// Get fix suggestions for a violation
const fixes = await ads_suggest_a11y_fixes({
violation: 'Button missing accessible label',
code: ``,
});
```
## 使用量
### AFM 用户(仅限内部地图集)
如果您在 AFM 根文件夹或任何主产品文件夹中工作(`platform/`, (中文(简体) ), `jira/`, (中文(简体) ), `confluence/`, (中文(简体) ), `post-office/`, (中文(简体) ), `confluence/`,或 `townsquare/`),ads-mcp已预配置并准备就绪 用于使用Cursor、VSCode(Copilot/Codelassian)和Rovodev等辅助工具.
对于大多数用户来说,ads-mcp在AFM中预配置,但您可能需要手动在光标中启用它 或副驾驶。 Rovodev 用户在 AFM 内任何地方自动获得 ads- mcp 启用 。 对于其他工具, 请确定您正在从 AFM 根或主要产品文件夹之一运行它们以访问 广告mcp.
### 非AFM 用户
#### 光标 IDE
##### 当地( stdio)
在您的 `mcp.json` 文件(位于 `~/.cursor/mcp.json` 用于用户级或 `.cursor/mcp.json` 工作空间:
```json
{
"mcpServers": {
"ads-mcp": {
"command": "npx",
"args": ["-y", "@atlaskit/ads-mcp"],
"env": {
"ADSMCP_AGENT": "cursor"
}
}
}
}
```
##### 远程
点击  添加或添加以下内容: `mcp.json` 文件 :
```json
{
"mcpServers": {
"ads-mcp": {
"url": "https://mcp.atlassian.com/v1/ads/public/mcp"
}
}
}
```
#### 视觉工作室代码
##### Github 副驾驶
###### 当地( stdio)
在您的 `mcp.json` 文件(位于 `~/Library/Application Support/Code/User/mcp.json` 用于用户级或 `.vscode/mcp.json` 在你身边 工作空间 :
```json
{
"servers": {
"ads-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@atlaskit/ads-mcp"]
},
"env": {
"ADSMCMP_AGENT": "vscode"
}
}
}
```
###### 远程
点击  或将以下内容添加到同一处 `mcp.json` 文件 :
```json
{
"servers": {
"ads-mcp": {
"type": "http",
"url": "https://mcp.atlassian.com/v1/ads/public/mcp"
}
}
}
```
##### 法典
###### 当地( stdio)
在您的 `mcp.json` 文件(位于 `~/.codelassian/mcp.json` 用户级别 或者说 `.codelassian/mcp.json` 工作空间:
```json
{
"mcpServers": {
"ads-mcp": {
"command": "npx",
"args": ["-y", "@atlaskit/ads-mcp"],
"env": {
"ADSMCP_AGENT": "codelassian"
}
}
}
}
```
###### 远程
无需安装本地设备。 将以下内容添加到同一处 `mcp.json` 文件 :
```json
{
"mcpServers": {
"ads-mcp": {
"type": "streamableHttp",
"url": "https://mcp.atlassian.com/v1/ads/public/mcp",
"disabled": false
}
}
}
```
#### 罗沃德夫
##### 当地( stdio)
在您的 `mcp.json` 文件(位于 `~/.rovodev/mcp.json` 用于用户级或 `mcp.json` 工作空间:
```json
{
"mcpServers": {
"ads-mcp": {
"command": "npx",
"args": ["-y", "@atlaskit/ads-mcp"],
"env": {
"ADSMCP_AGENT": "rovodev"
}
}
}
}
```
> **说明:**
> 这个 `timeout` 字段在Rovodev配置中得到支持。 例如,设置 `"timeout": 300` 将指定在 **秒数** mCP 服务器将在 如果进程失去响应,则终止进程。 根据需要调整此值 环境或工作流程.
##### 远程
无需安装本地设备。 将以下内容添加到同一处 `mcp.json` 文件 :
```json
{
"mcpServers": {
"ads-mcp": {
"url": "https://mcp.atlassian.com/v1/ads/public/mcp"
}
}
}
```
#### Atlas CLI 的 MCP 插件
Atlas CLI 提供了管理 MCP 服务器的插件,包括从 a 列出可用的服务器 登记和安装新的系统.
要安装 MCP 插件, 请运行 :
```
atlas plugin install -n mcp
```
插件安装后,可以在Rovodev(用户级)上添加MCP服务器:
```
atlas mcp install --name=ads-mcp --agent=rovodev
```
> **说明:**
> 查看现有人员名单,访问: [引入 Atlas CLI 的 MCP 插件](https://hello.atlassian.net/wiki/spaces/~dnorton/blog/2025/10/07/5931517464/Introducing+the+MCP+plugin+for+Atlas+CLI)
### 环境变量
ADS MCP 服务器支持多个环境变量,主要用于分析帮助 改善服务。 这些变量可以实现平台识别,配置的规格 路径,必要时选择退出分析收藏.
> **说明:** 所有环境变量都是可选的. MCP 服务器将不设任何功能 设置.
- `ADSMCP_AGENT` - 使用MCP服务器确定AI代理/平台。 支持的数值 :
- `cursor` - 光标编辑器
- `vscode` - 视觉工作室代码
- `rovodev` - 罗沃发展环境
- `codelassian` - 代码平台
- `unknown` - 未指定的默认值
这个 `ADSMCP_AGENT` 变量帮助跟踪使用 MCP 服务器进行分析的平台 目标.
- `ADSMCP_CONFIG_PATH` - 指定用于运行服务器的 MCP 配置文件的路径. 用于分析以了解服务器的配置来自何处(例如, `mcp.json`, (中文(简体) ), `jira/.cursor/mcp.json`, (中文(简体) ), `platform/.vscode/mcp.json`) (中文(简体) ). 默认为 `unknown` 如果不是的话 页:1.
- `ADSMCP_ANALYTICS_OPT_OUT` - 解析器收集出来的 设定为 `true` 禁用 :
```json
{
"mcpServers": {
"ads": {
"command": "npx",
"args": ["-y", "@atlaskit/ads-mcp"],
"env": {
"ADSMCP_AGENT": "codelassian",
"ADSMCP_CONFIG_PATH": "platform/.codelassian/mcp.json",
"ADSMCP_ANALYTICS_OPT_OUT": true
}
}
}
}
```
## 分析
MCP服务器包括内置分析器来帮助改进服务. 分析发给 Atlassian的内部分析系统和轨迹:
### 我们追踪的是什么
- **工具使用**: 哪些工具被称作(例如, `ads_plan`, (中文(简体) ), `ads_analyze_a11y`(中文(简体) )
- **工具参数**: 传递给工具的参数(搜索名词,组件名称等)
- **成功/失败**: 工具呼叫是否成功,包括错误消息
- **环境背景**数字 :
- `agent`: 使用 MCP 服务器的平台(来自 `ADSMCP_AGENT` (原始内容存档于2019-09-21) (英语). env var
- `os`: 操作系统名(darwin, win32, linux)
- `osVersion`:操作系统版本(如:macOS的24. 6.0)
- `version`页:1 `@atlaskit/ads-mcp` 正在使用
- `staffId`: 用户标识符(来自 `STAFF_ID`, (中文(简体) ), `USER`, (中文(简体) ), `ATLAS_USER`,或用户名)
- `timestamp`: 事件发生时
### 隐私处理出错( E)
- 收集分析,仅供Atlassian内部使用,以改善MCP服务器
- **你可以选择退出** 设置 `ADSMCP_ANALYTICS_OPT_OUT=true` 在环境变量中
- 如果分析客户端无法初始化或发送事件, MCP 服务器将继续工作 一般情况
- 所有分析错误都被记录下来 保证不会打断你的工作流程
- 为了提高效率,每5秒对事件进行批量并冲出一次
## 发展
您可自动获得本地版本的 `@atlaskit/ads-mcp` 取决于你在哪里 运行它从, 但你应该强迫它这样:
```json
{
"mcpServers": {
"ads": {
"command": "npx",
"args": [
"-y",
"~/git/atlassian/atlassian-frontend-monorepo/platform/packages/design-system/ads-mcp"
],
"env": {
"ADSMCP_AGENT": "cursor"
}
}
}
}
```
## 维护者发布工作流程(AFM)
当 ADS 结构化内容更改时 :
1. 从 `platform/`,运行合并代码源一次:
```bash
afm workspace @af/ads-ai-tooling codegen
```
2. 在此包中提交更新生成的 MCP 输出 .
3. 添加一个 `platform/.changeset/*.md` 条目 `@atlaskit/ads-mcp` 在同一公关。 使用 `patch` 页:1 目录或文档刷新; 使用 `minor` 或者说 `major` 当软件包 API 更改时.
4. 创建并运送 `@atlaskit/ads-mcp` 照常释放.
5. 等待软件包的发布.
6. 翻新应该把它塞进去 [地图集-mcp-micros](https://bitbucket.org/atlassian/atlassian-mcp-micros/)。 。 。 .
7. 调动 `atlassian-mcp-micros` 在倾覆后.
对于生成的技能和DESIGN.md输出,使用交叉存储同步工作流程 `packages/design-system/ai-tooling/README.md`,然后跟随目的地 README 在 `atlassian/skills`。代码运行器不创建指令文件 `platform/tmp/`。 。 。 .
## 问题
1. 我看到一个错误,如"错误:找不到模块" `/Users/[username]/.npm/_npx/[hash]/node_modules/[module]/...`" (中文(简体) )
这通常意味着被缓存的软件包被腐蚀或过时. 决心:
1. 禁用 `ads-mcp` 在已安装的 MCP 服务器列表中.
2. 删除受影响的 `/Users/[username]/.npm/_npx/[hash]` 目录.
3. 重新启用 `ads-mcp` 在您的 MCP 服务器中.
2. 在VSCode(副驾驶), `ads-mcp` 继续自动启动聊天面板,即使已禁用.
防止自动启动 :
1. 打开 VSCode 设置 .
2. 搜索 `@feature:chat mcp`。 。 。 .
3. 设定 `Chat › Mcp: Autostart` 改为 `never`。 。 。 .
3. 我该联系谁寻求支持或提问?
对于内部阿特拉斯人,请联系 [#帮助 -ads -ai #](https://atlassian.enterprise.slack.com/archives/C091C8JCUTV) 频道为黑 任何问题或查询.
## 常见问题
### @atlaskit/ads-mcp 是什么？
官方的Atlassian Design System MCP服务器,开发与Atlassian风格相匹配的应用程序和用户界面\.
### 如何安装 @atlaskit/ads-mcp？
在项目目录运行 npm install @atlaskit/ads-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ads-mcp，可以用 npx ads-mcp 直接运行。
### @atlaskit/ads-mcp 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @atlaskit/ads-mcp 支持 ESM 还是 CommonJS？
以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。
### @atlaskit/ads-mcp 可以商用吗？
@atlaskit/ads-mcp 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。
### @atlaskit/ads-mcp 的下载量有多少？
根据 npm 官方下载统计，@atlaskit/ads-mcp 在 2026/10/07 – 2026/11/05 这 30 天内被下载 5,700 次，日均约 190 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @atlaskit/ads-mcp 还在维护吗？
最新版本 1\.12\.5 发布于 2026/11/06（2 天前）；至今共发布 133 个版本，其中过去 12 个月发布了 99 个；首次发布于 2025/06/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。