内容
# MD3-Docs MCP
[](https://www.npmjs.com/package/md3-docs-mcp)
`MD3-Docs` 是一个 stdio 模型上下文协议（MCP）服务器，为 AI 助手提供对 [Material Design 3 文档](https://m3.material.io/) 的访问。该服务器涵盖了基础知识、样式和组件，并以 Markdown 格式返回官方英文内容。
服务器不包含文档快照，也不要求浏览器。它会发现当前的 Material 网站数据版本，获取网站的结构化 JSON 数据，并将文本、表格、实现资源、链接、代码和媒体元数据转换为 AI 友好的格式。
## 架构
代码库使用功能驱动的结构：
```text
src/
├── app/ # 应用组合
├── features/
│ ├── catalog/ # list_md3_docs
│ ├── document/ # read_md3_doc 和 Markdown 渲染
│ ├── resources/ # MCP 文档资源
│ └── search/ # search_md3_docs
├── infrastructure/
│ └── material/ # Material 网站客户端、解析器和上游类型
├── shared/
│ ├── cache/ # 通用 TTL/LRU 缓存
│ ├── errors/ # 领域错误表示
│ ├── http/ # 重试获取适配器
│ ├── mcp/ # 共享 MCP 结果帮助器
│ └── pagination/ # 不透明的光标
└── index.ts # stdio 进程入口点
```
功能拥有自己的 MCP 模式和处理程序。`app` 组合功能，`infrastructure` 适应外部 Material 服务，`shared` 仅包含与功能无关的实用程序。测试在 `test/` 下镜像相同的边界。
## 要求
- Node.js 24 或更高版本
- npm，包含在 Node.js 中
[Bun](https://bun.sh/) 仅在从源代码开发时需要。应用程序使用标准的 Node.js 和 Web API，不依赖于 `Bun.*` 运行时功能。
## 安装和配置
### 使用 npx 运行（推荐）
不需要全局安装。添加以下内容到您的 MCP 客户端配置中：
```json
{
"mcpServers": {
"MD3-Docs": {
"command": "npx",
"args": ["-y", "md3-docs-mcp@latest"]
}
}
}
```
`-y` 标志允许 `npx` 在不提示的情况下安装或更新包。
### 全局安装
一次性安装命令：
```sh
npm install --global md3-docs-mcp
```
然后配置您的 MCP 客户端直接运行它：
```json
{
"mcpServers": {
"MD3-Docs": {
"command": "md3-docs-mcp"
}
}
}
```
### 从源代码运行
```sh
git clone https://github.com/ChouChiu/MD3-Docs-MCP.git
cd MD3-Docs-MCP
bun install --frozen-lockfile
```
使用绝对路径作为 `cwd`：
```json
{
"mcpServers": {
"MD3-Docs": {
"command": "bun",
"args": ["run", "start"],
"cwd": "/absolute/path/to/MD3-Docs-MCP"
}
}
}
```
## 开发
开发和验证命令：
```sh
bun run dev
bun run check
bun run fix
bun run typecheck
bun run test
bun run test:live
```
`check` 运行 Biome 格式化和 lint 验证，接着是 TypeScript 类型检查。`fix` 应用 Biome 的安全格式化、lint 和导入组织修复。
默认测试是离线的。`test:live` 显式联系 `m3.material.io`。
## 持续集成和发布
代码质量工作流恢复了特定于平台的 `node_modules` 缓存，执行冻结依赖安装，并运行 Biome、TypeScript 和离线测试套件，运行在 Node.js 24 上。它适用于分支推送、拉取请求和手动调度。实时测试仍然是可选的，不会使 CI 依赖于 Material 网站。
发布是从诸如 `v1.0.1` 之类的语义版本标签创建的。标签必须与 `package.json` 中的版本完全匹配；在验证后，工作流将源代码包发布到 npm，并使用生成的注释创建 GitHub 发布。它不会生成或附加构建工件。GitHub 的标准源代码存档仍然可用。
在发布第一个版本之前，请添加名为 `NPM_TOKEN` 的存储库机密。它必须是具有发布 `md3-docs-mcp` 权限的 npm 粒度访问令牌。重新运行部分完成的发布是安全的：如果已经存在 npm 版本或 GitHub 发布，则会跳过。
服务器只向 stdout 写入 MCP 协议消息。诊断信息会输出到 stderr。
## 工具
### `list_md3_docs`
列出官方文档目录。
```json
{
"category": "components",
"prefix": "components/button",
"limit": 20
}
```
输入：
- `category`：可选 `foundations`、`styles` 或 `components`
- `prefix`：可选规范路径前缀
- `limit`：1-100，默认 50
- `cursor`：上一次调用返回的不透明光标
### `search_md3_docs`
搜索官方网站并丢弃支持文档范围之外的结果。
```json
{
"query": "large screens 上的导航",
"category": "components",
"limit": 10
}
```
### `read_md3_doc`
读取规范路径或干净的 `https://m3.material.io/` URL。
```json
{
"path": "components/buttons/guidelines",
"maxCharacters": 12000
}
```
您可以显式提供 `section`。基本组件路径默认为存在 `Overview` 选项卡时的 `Overview`。长结果返回不透明的 `nextCursor`；请将其与相同的路径和部分一起传递以继续。如果实时文档版本更改，则拒绝光标。
所有工具都提供结构化的 MCP 输出和 JSON 文本回退。
## 资源
文档也作为 `text/markdown` 资源公开：
```text
md3-docs://docs/components/buttons/guidelines
```
资源列表从实时站点地图生成。资源读取返回完整的所选文档选项卡；当分页更可取时，请使用 `read_md3_doc`。
## 获取、缓存和安全
- 站点地图、路由索引、搜索、文档和辅助资源表使用五分钟的进程内 LRU 缓存，最多 256 个条目。
- 相同的并发请求共享一个上游操作。
- 请求在十秒后超时。网络故障、HTTP 429 和选定的 5xx 响应将重试一次。
- 过期内容在刷新失败时不会被提供。
- 仅接受 `https://m3.material.io` 下的干净 URL，位于 `foundations`、`styles` 和 `components` 下。查询字符串、片段、凭证、遍历和外部主机将被拒绝。
如果 Material 网站更改了其未发布的 структури化数据布局，工具将返回 `UPSTREAM_SCHEMA` 错误。运行 `bun run test:live` 以诊断站点兼容性。
## 故障排除
- 如果启动报告 `tsx` 无法找到，请在项目目录中运行 `bun install`。
- `UPSTREAM_TIMEOUT` 或 `UPSTREAM_HTTP` 结果指示实时网站或网络故障；服务器不会回退到过期的文档快照。
- `UPSTREAM_SCHEMA` 结果通常意味着 Material 网站更改了其内部数据形状。运行 `bun run test:live` 以识别受影响的端点。
- `CURSOR_STALE` 表示实时文档或结果集已更改。请在没有光标的情况下重复原始调用。
-_stdio 服务器通常不会打印人类可读的启动消息。请检查 MCP 客户端捕获的 stderr 以获取诊断信息。
## 许可证和归属
MCP 服务器源代码在 [MIT License](LICENSE) 下可用。
Material Design 文档、图像、视频、商标和其他远程获取的内容仍然是其各自所有者的财产，不受此存储库许可证的约束。每个文档响应都保留其官方源 URL。
