# @buildpad/mcp 中文文档

规范地址：https://npmcn.com/package/%40buildpad/mcp/

版本：3\.7\.0
npm 元数据更新时间：2026-11-06T09:06:01.549Z
中文译文更新时间：2026-11-08T20:47:29.919Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40buildpad/mcp
原文对照：https://npmcn.com/package/%40buildpad/mcp/?lang=original
项目主页：https://github.com/buildpad-ai/ui#readme
源码仓库：https://github.com/buildpad-ai/ui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.8 MB，500 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-02-27T08:45:28.363Z
- 最新版本发布：2026-11-06T09:06:01.247Z
- 近 30 天下载量：2122（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

Buildpad 组件的模型上下文协议服务器 - 允许 AI 代理 发现和使用 Buildpad 包

## 安装

```sh
npm install @buildpad/mcp
```

也可以使用：`pnpm add @buildpad/mcp`、`yarn add @buildpad/mcp`、`bun add @buildpad/mcp`

## README

# @ buildingpad/ mcp (帮助)

Buildpad组件的模型上下文协议(MCP)服务器. 启用像 VS 代码等 AI 代理程序,以便使用 **复制( O)** 发行模式.

[![npm version](https://img.shields.io/npm/v/@buildpad/mcp)](https://www.npmjs.com/package/@buildpad/mcp)

## 什么是MCP吗?

这个 [示范背景协议](https://modelcontextprotocol.io/) 是一个开放标准,使AI助手能够安全地访问外部数据源和工具. 这个MCP服务器将Buildpad组件库暴露给AI代理.

## 复制自有模式( O)

构建纸板使用 **复制( O)** 分配模式(类似于shadcn/ui):

-   QQ 组件作为源代码复制到您的工程
-   QQ 完全定制 - 组件成为您的应用程序代码
-   组件代码没有外部软件包依赖性
-   QQ 上游更新中未出现分解变化
-   工程安装后下线

## 特征

-   📦 **组件发现** - 列出所有可用的 Buildpad 组件
-   📖 **源代码访问** - 读取组件和lib模块源代码。 货包里面的源头船,所以这个工作离线
-   🛠️ **代码生成** - 生成组件、窗体和接口
-   🔧 **CLI 一体化** - 让CLI命令安装组件
-   ⬆️ **升级** - 在一个项目中找到过时的组件和 lib 模块,规划升级,并与匹配的 CLI 运行
-   📚 **用法实例** - 获得当地进口的实际使用实例

## 从何而来

每次发布 `@buildpad/mcp` 包含两件事 从同一承诺:

-   组成部分登记册`registry.json`,嵌入于 `dist/index.js`
-   登记册所列出的每个源文件,单位: `dist/sources/<source path>`

构建检查每个捆绑的文件与注册处的 `sourceSha256` 并因错配而失败。 这么说吧 `get_component`, (中文(简体) ), `copy_component` 财务报告和审定财务报表 `resources/read` 返回该释放的确切字节, 没有网络访问 .

如果您运行服务器从一个单列波检出( I)`packages/mcp-server/dist`),读作: `packages/` 直接换成。 它从不读其他软件包 `node_modules/@buildpad`。 。 。 .

如果无法读取文件, 工具返回 `isError: true` 带有 `missingSources` 列表中选择一个选项. `resources/read` 返回 MCP 错误 `missingSources` 联合国 `data`。一个工具永远不会返回空文件列表或占位符文本取而代之.

来源如已公布。 他们进口 `@buildpad/*` 软件包,不在npm上. `npx @buildpad/cli add <name>` 把这些进口重新写入您的项目路径。 如果您手抄文件, 您必须自己重写导入 .

## 安装

### 对于 VS 代码副驾驶( 建议通过 npx)

MCP服务器发布于npm. 不需要当地建筑.

添加到您的 VS 代码 `settings.json` 或者说 `.vscode/mcp.json`数字 :

```json
{
  "mcp": {
    "servers": {
      "buildpad": {
        "command": "npx",
        "args": ["@buildpad/mcp@latest"]
      }
    }
  }
}
```

重新装入 VS 代码窗口.

### VS 代码副驾驶( 本地建筑)

对于单列范围内的发展:

1.  构建 MCP 服务器 :

```bash
pnpm build:mcp
```

2.  添加到您的 VS 代码 `settings.json` 或者说 `.vscode/mcp.json`数字 :

```json
{
  "mcp": {
    "servers": {
      "buildpad": {
        "command": "node",
        "args": [
          "/absolute/path/to/buildpad-ui/packages/mcp-server/dist/index.js"
        ]
      }
    }
  }
}
```

3.  重新装入 VS 代码窗口

### 其他大赦国际代理人

使用任何 MCP 兼容客户端 :

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["/path/to/buildpad-ui/packages/mcp-server/dist/index.js"],
});

const client = new Client({
  name: "my-app",
  version: "1.0.0",
}, {
  capabilities: {},
});

await client.connect(transport);
```

## 可用资源

### 软件包

-   `buildpad://packages/@buildpad/types` - 类型脚本类型定义
-   `buildpad://packages/@buildpad/services` - CRUD服务类
-   `buildpad://packages/@buildpad/hooks` - 关系反应钩
-   `buildpad://packages/@buildpad/ui-interfaces` - 外地接口组件
-   `buildpad://packages/@buildpad/ui-collections` - 动态收集组件

### 构成部分

每个资源返回一个组件的主要(第一个)源文件。 一个 lib- 模块名称( 例如) `buildpad://components/utils`)亦能通达.

-   `buildpad://components/input` - 文本输入部分
-   `buildpad://components/select-dropdown` - 选择下拉
-   `buildpad://components/datetime` - 日期/时间采集器
-   `buildpad://components/file-image` - 图像上传
-   `buildpad://components/collection-form` - 动态形式
-   以及许多其他(例如: `Input` 还匹配)

## 可用工具

### `list_components`

列出所有可用的组件,包括描述和类别.

### `get_component`

获取特定组件或lib模块的详细信息和源代码. `source` 是主文件,并且 `allSources` 绘制每个目标路径的内容.

```json
{
  "name": "Input"
}
```

### `list_packages`

列出所有 Buildpad 套件及其出口 .

### `get_install_command`

让 CLI 命令安装组件 。 对AI代理帮助用户添加组件至关重要.

```json
{
  "components": ["input", "select-dropdown", "datetime"]
}
```

或按类别安装 :

```json
{
  "category": "selection"
}
```

### `get_copy_own_info`

获取关于 Copy & Own 分发模式的详细信息 .

### `copy_component`

获取完整的源代码和文件结构,以便手动将一个组件复制到您的工程(Shadcn-tyle)中. 返回全部执行代码、目标路径和所需的依赖性.

```json
{
  "name": "datetime",
  "includeLib": true
}
```

回返情况:

-   完整组件源代码
-   目标文件路径
-   必需的 lib 模块( 类型、 服务、 钩子、 utils, ...), 包括依赖的 lib 模块
-   安装的对等依赖性及其使用的其他组件(`registryDependencies`(中文(简体) )
-   复制指令

CLI(`npx @buildpad/cli add datetime`)是建议安装的方法:它也重写 `@buildpad/*` 导入并记录以后升级的文件.

### `generate_form`

生成带有指定配置的 CollectionForm 组件 .

```json
{
  "collection": "products",
  "fields": ["title", "description", "price"],
  "mode": "create"
}
```

### `generate_interface`

生成一个字段接口组件 .

```json
{
  "type": "input",
  "field": "title",
  "props": {
    "placeholder": "Enter title",
    "required": true
  }
}
```

### `get_usage_example`

获取一个组件( 包括本地导入) 的真实世界使用示例 .

```json
{
  "component": "SelectDropdown"
}
```

### `get_rbac_pattern`

Get RBAC(基于Role的存取控制)为DaaS应用程序设置模式. 返回分步 MCP 工具调用序列来设置角色,政策,访问和权限.

```json
{
  "pattern": "own_items",
  "collections": ["articles", "categories"],
  "roleName": "Editor"
}
```

**可用模式 :**

| 图案 | 说明 |
| --- | --- |
| `own_items` | 用户管理自己的记录, 读取他人公布的项目 |
| `role_hierarchy` | 管理员 > 编辑器 > 查看器串联权限 |
| `public_read` | 公开读取 + 认证写入 |
| `multi_tenant` | 组织一级的数据隔离 |
| `full_crud` | 不受限制的 CRUD 访问 |
| `read_only` | 仅读访问 |

**支持的动态变量 :** `$CURRENT_USER`, (中文(简体) ), `$CURRENT_USER.<field>`, (中文(简体) ), `$CURRENT_ROLE`, (中文(简体) ), `$CURRENT_ROLES`, (中文(简体) ), `$CURRENT_POLICIES`, (中文(简体) ), `$NOW`

仅封面收藏 CRUD. 每一个反应都包含 `moduleAccess` 提醒指向下面的工具.

### `get_module_access_pattern`

拿着 **模块级访问** 设置序列——属于 _没有_ 绑在一个收藏.

DaaS有两个独立的许可尺寸:

| 尺寸 | 存储于 | 控件 |
| --- | --- | --- |
| 记录级访问 | `daas_permissions` 行数 | 用户可以 CRUD 的收藏, 其中的字段和过滤器 |
| 模块级访问 | `daas_policies.module_access` (JSONB) (英语) | 用户是否拥有命名的应用程序能力 |

用于任何门采集权限都无法表达:向一些用户显示按钮,页面,区域,或导航项,或限制工作流程过渡. **角色名称从不设闸门** (单位:千美元)`user.role === 'manager'`这是受制裁的机制.

```json
{
  "keys": [{ "key": "reports:export", "display_name": "Export Reports" }],
  "folder": "Reporting",
  "policyName": "Manager Policy"
}
```

返回 `module_access_keys` + 键 `policies` 用于注册和授予密钥的工具呼叫, 加上三种守护模式:

| 警卫 | 何处 | 什麽 |
| --- | --- | --- |
| 客户端 | 反应组件 | `usePermissions().hasModuleAccess('reports:export')` - 仅UX; **未关闭** 装入时 |
| 服务器 | API 路径 | `enforceModuleAccess('reports:export')` → `ModuleAccessError(403)` - 安全边界 |
| 工作流程 | JSON指挥系统 | `module_access_keys: ["reports:export"]`,或已经与 `policies` |

**关键规则 :** 格式 `^[a-z][a-z0-9_:./-]*$`全球独特的公约 `<domain>:<capability>`编辑 `system:` 财务报告和审定财务报表 `workflow:` 名称空间由平台保留。 用户持有的每条政策都有钥匙;管理员持有每把钥匙。 决议尊重活动范围(Resource URI).

登记册管理 `users-management` 构成部分`ModuleAccessKeysManager`,挂载在 `/module-access-keys`); 每项政策授权是“模块级访问”标签 `PolicyDetail`。 。 。 .

### `list_outdated`

列出已安装的组件 **模块** (使用,服务,钩子,. )其上游来源有变化. 工具读取了项目的 `buildpad.json` 比较每个记录 `sourceSha256` 与此服务器的注册 。 每个条目包括 `kind` (单位:千美元)`component` 或者说 `lib`, (中文(简体) ), `staleFiles`, (中文(简体) ), `installedRelease`,以及 `latestRelease` (释放这艘服务器船) 从较新版本安装的条目被标记为 `aheadOfRegistry`。 。 。 .

```json
{
  "projectPath": "/absolute/path/to/your-project"
}
```

### `get_upgrade_plan`

仅读干跑. 对于每个已安装的组件和 lib 模块, 它显示磁盘上每个文件的 stale 文件和状态 :

-   `pristine`: 文件匹配安装时记录的散列 .
-   `modified`:文件有本地编辑.
-   `missing`: 文件不在磁盘上 .
-   `untracked`: 文件在磁盘上, 但是 `buildpad.json` 没有安装散列。 无论策略如何,CLI都会覆盖这类文件.
-   `invalid-target`:所记录的目标位于项目根外,或者路径不是一个正则文件(例如目录). 工具没有读取它.

由 CLI 撰写的文档中查找: `src/` 何时 `srcDir` 已设定,组件 `.ts` 文件为 `.tsx`。计划还提供了 `recommendedAction`数字 : `up-to-date`, (中文(简体) ), `safe-overwrite`, (中文(简体) ), `prompt-or-three-way`, (中文(简体) ), `overwrite-untracked` (首先恢复本地编辑), `review-invalid-targets` (对) `buildpad.json` 或文件第一个)或 `update-mcp`。如果指定一个条目,则计划还包括其依赖的过时组件和lib模块。 每个条目都列出它们(`staleLibDependencies`, (中文(简体) ), `staleComponentDependencies`项目没有依赖性(`missingDependencies`页:1 `apply_upgrade` 安装.

### `apply_upgrade`

写给项目。 此工具运行 `npx --yes @buildpad/cli@<this server's version> upgrade --cwd <projectPath> --strategy <strategy> -- <names>`。CLI被固定在服务器自己的版本上,因此它应用了相同的注册号,即 `get_upgrade_plan` 报告.

```json
{
  "projectPath": "/absolute/path/to/your-project",
  "components": ["input"],
  "strategy": "three-way"
}
```

-   奥米 `components` 将安装的所有设备升级(`--all`) (中文(简体) ). 这是最安全的选择.
-   如果命名条目,那么它们所依赖的会随之而来:过时的组件和lib模块被升级并安装了缺失的组件和模块,因为升级后的代码会导入它们. 工具在命令行上标出每个名称并经过 `--no-deps`,因此 CLI 正好触及了工具检查的条目。 结果将它们列为 `libDependencies`, (中文(简体) ), `componentDependencies` 财务报告和审定财务报表 `missingDependencies`。只更新命名条目,设置 `includeDependencies: false` (项目随后可能无法编译). `includeLibDependencies` 是此选项的早期名称, 但仍被接受.
-   `projectPath` 必须是一个绝对的道路。 相对路径被拒绝.
-   `strategy` 必须是 `overwrite`, (中文(简体) ), `new-file` (默认)或 `three-way`。CLI的互动 `prompt` 策略无法通过MCP解答.
-   名称必须是注册名称:小写字母,数字和破折号,而不是从破折号开始. 后传来 `--`没有壳.
-   如果工程、 命名的条目或它会添加的 lib 模块是从比此服务器更新的版本安装的, 工具会拒绝运行, 因为这样会降级 。 替换更新服务器( U)`npx -y @buildpad/mcp@latest`) (中文(简体) ). 如果新增的依赖关系是更新的,您也可以设置 `includeDependencies: false`。 。 。 .
-   如果CLI无法启动,则以非零代码或出站时间(120 s)退出,结果为 `isError: true`JSON的身体仍然给 `success: false`, (中文(简体) ), `exitCode`, (中文(简体) ), `stdout` 财务报告和审定财务报表 `stderr`。 。 。 .

## 使用副驾驶

配置后, 您可以询问副驾驶 :

-   "我如何安装 Buildpad 组件?" (使用) `get_copy_own_info`(中文(简体) )
-   “在我的项目中添加输入和选择Dropdown组件”(使用) `get_install_command`(中文(简体) )
-   “教我如何使用输入组件”(使用) `get_usage_example`(中文(简体) )
-   “为产品收集提供一种形式”(使用) `generate_form`(中文(简体) )
-   “列出所有可用的选择组件”(使用) `list_components`(中文(简体) )
-   "给我看收藏格式的源代码"(使用) `get_component`(中文(简体) )
-   “将RBAC设置为文章的自有项目模式”(使用 `get_rbac_pattern`(中文(简体) )
-   "Generate 角色等级系统用于管理员,编辑,查看器"(使用 `get_rbac_pattern`(中文(简体) )

AI代理将提供CLI命令,您可以运行以安装组件.

## 发展

```bash
# Build
pnpm build

# Watch mode
pnpm dev

# Type check
pnpm typecheck

# Tests
pnpm test

# After a build: pack the package, install it in a temp project and check
# that the source tools return the registry's bytes over stdio
pnpm smoke:pack
```

## 建筑

```
┌─────────────────────────────────────────┐
│      AI Agent (VS Code Copilot, etc.)   │
└────────────────┬────────────────────────┘
                 │ MCP Protocol
┌────────────────▼────────────────────────┐
│       @buildpad/mcp                   │
│  ┌──────────────────────────────────┐   │
│  │  Resource Handlers               │   │
│  │  - List components               │   │
│  │  - Read component source         │   │
│  │  - Get documentation             │   │
│  └──────────────────────────────────┘   │
│  ┌──────────────────────────────────┐   │
│  │  Tool Handlers                   │   │
│  │  - get_install_command           │   │
│  │  - get_copy_own_info             │   │
│  │  - generate_form                 │   │
│  │  - generate_interface            │   │
│  │  - get_usage_example             │   │
│  │  - get_rbac_pattern              │   │
│  └──────────────────────────────────┘   │
│  ┌──────────────────────────────────┐   │
│  │  Component Registry (embedded)   │   │
│  │  - Metadata & Categories         │   │
│  │  - Dependencies                  │   │
│  │  - File mappings                 │   │
│  └──────────────────────────────────┘   │
│  ┌──────────────────────────────────┐   │
│  │  dist/sources (bundled)          │   │
│  │  - Every registry source file    │   │
│  │  - sha256-checked at build time  │   │
│  └──────────────────────────────────┘   │
└─────────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│         @buildpad/cli (npm)           │
│  npx @buildpad/cli@latest add <comp>  │
│  - Fetches source from GitHub CDN       │
│  - Transforms imports                   │
│  - Resolves dependencies                │
│  - Copies to user project               │
└─────────────────────────────────────────┘
```

## 许可证

麻省理工学院

## 常见问题

### @buildpad/mcp 是什么？

Buildpad 组件的模型上下文协议服务器 - 允许 AI 代理 发现和使用 Buildpad 包

### 如何安装 @buildpad/mcp？

在项目目录运行 npm install @buildpad/mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 buildpad-mcp，可以用 npx buildpad-mcp 直接运行。

### @buildpad/mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @buildpad/mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @buildpad/mcp 可以商用吗？

@buildpad/mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @buildpad/mcp 的下载量有多少？

根据 npm 官方下载统计，@buildpad/mcp 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,122 次，日均约 71 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @buildpad/mcp 还在维护吗？

最新版本 3\.7\.0 发布于 2026/11/06（2 天前）；至今共发布 52 个版本，其中过去 12 个月发布了 52 个；首次发布于 2026/02/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。