内容
# MCP 设计器
[](https://www.npmjs.com/package/@kiubi/mcp-designer)
[](https://github.com/Kiubi/mcp-designer/blob/main/LICENSE)
[](https://github.com/Kiubi/mcp-designer/blob/main/package.json)
MCP 设计器是一个本地 MCP 服务器，专门用于集成 **[Kiubi](https://www.kiubi.com)** 的图形主题。它为 AI 代理（Claude、Codex、Gemini 等）提供了一组专用工具：操作文档、当前主题的内省、配置文件创建和静态文件验证。
集成 Kiubi 主题需要处理自定义模板语法（标签、过滤器、块）、技术文档和现有主题的约定。MCP 服务器在您编码时直接为 AI 代理提供此上下文，而不是让您搜索、猜测或在生产环境中测试。
具体来说：
- **不再需要记住标签或过滤器的确切语法** - 模板引擎的规则和集成文档由代理按需查询，而不是在帮助网站上查找。
- **修改现有模板而不破坏项目的一致性** - 在修改文件之前，代理可以列出已有的类型、部件和小部件，并与它们对齐，而不是重新发明命名约定或复制现有字段。
- **创建内容类型而不手动重写 XML** - 文件结构直接生成，而不是复制现有类型并希望不会遗漏任何内容。
- **在部署前检测错误，而不是之后** - 不正确的 `theme.xml` 或文件之间的不一致通常在预览或上线后才被发现。本地验证在部署前进行。
代理应用针对 Kiubi 优化的程序，但仍由您控制：在创建或转换模板任务中，它会公开其操作计划（转换模式、预期字段、预期区域）并在生成任何内容之前等待明确的验证。
---
## 目录
- [前提条件](#前提条件)
- [安装](#安装)
- [Claude Code 配置](#claude-code-配置)
- [Codex 配置](#codex-配置)
- [Gemini 配置](#gemini-配置)
- [更新](#更新)
- [用法](#用法)
- [集成到 Kiubi 项目中](#集成到-kiubi-项目中)
- [项目结构](#项目结构)
- [使用 kiubi-sync 部署主题](#使用-kiubi-sync-部署主题)
- [部署 CLAUDE.md](#部署-claudemd)
- [保密性](#保密性)
- [可用工具](#可用工具)
---
## 前提条件
| 工具 | 最低版本 | 注意事項 |
|:---------|:-----------------|:------------------------------------------|
| Node.js | 22.18 | TypeScript 本机执行所需 |
| npm | 10+ | 随 Node.js 包含 |
---
## 安装
服务器通过 npm 包 **`@kiubi/mcp-designer`** 分发。无需手动安装，使用命令：`npx -y @kiubi/mcp-designer@latest` 即可下载并自动执行最新版本的 MCP 服务器。然后只需将此 MCP 添加到您的 AI 代理中。
### Claude Code 配置
要添加 MCP 服务器，请打开终端，**导航到项目目录**，然后：
```bash
claude mcp add kiubi-mcp --scope project -- npx -y @kiubi/mcp-designer@latest
```
下载文件 https://github.com/Kiubi/mcp-designer/blob/main/storage/documents/CLAUDE.exemple.md 并将其保存在项目根目录下，命名为 `CLAUDE.md`。
### Codex 配置
要添加 MCP 服务器，请打开终端，**导航到项目目录**，然后：
```bash
mkdir .codex
cat >> .codex/config.toml <<'EOF'
[mcp_servers.kiubi-mcp-designer]
command = "npx"
args = ["-y", "@kiubi/mcp-designer@latest"]
enabled = true
required = true
default_tools_approval_mode = "auto"
EOF
```
下载文件 https://github.com/Kiubi/mcp-designer/blob/main/storage/documents/CLAUDE.exemple.md 并将其保存在项目根目录下，命名为 `AGENTS.md`。
### Gemini 配置
要添加 MCP 服务器，请打开终端，**导航到项目目录**，然后：
```bash
gemini mcp add --scope project kiubi-mcp-designer npx -y @kiubi/mcp-designer@latest
```
下载文件 https://github.com/Kiubi/mcp-designer/blob/main/storage/documents/CLAUDE.exemple.md 并将其保存在项目根目录下，命名为 `GEMINI.md`。
### 更新
命令 `npx -y @kiubi/mcp-designer@latest` 在每次启动服务器时解析 `latest` 标签：因此无需手动更新。实际上，此解析仅在 MCP 服务器启动时发生，即会话启动或代理重启时 - 已经运行的会话将继续使用启动时加载的版本。要强制考虑新版本，请重启代理（或 MCP 连接）。
如果 `npx` 仍然提供过时的版本（本地缓存的软件包，联网时解析环境），请清除 npm 缓存以强制下载新版本：
```bash
npm cache clean --force
```
> **重要** - 在安装过程中下载的文件 `CLAUDE.exemple.md`（或 `AGENTS.md`/`GEMINI.md`）不会自动更新：这是本地副本。如果其内容在服务器版本之间发生变化，请下载并将其与项目的版本文件进行比较。
---
## 用法
MCP 服务器连接后，代理根据您的请求自行决定何时调用工具 - 无需输入特定命令。只需在集成项目根目录（包含 `theme/` 目录）打开编辑器即可。以下是一些请求示例:
- *“在部署前验证主题”* → 代理调用 `validate_theme` 并报告发现的错误。
- *“`product` 类型有哪些字段？”* → 代理调用 `detail_type` 并根据结果回答。
- *“使用字段 title、text 和 note 创建一个 `temoignage` 类型”* → 代理公开其计划（字段、预期区域）并在生成任何内容之前等待您的验证，然后调用 `create_type`。
- *“Kiubi 模板引擎的 `date` 过滤器如何工作？”* → 代理查询 `ruleset` 和/或 `search_doc` 而不是猜测语法。
---
## 集成到 Kiubi 项目中
### 项目结构
Kiubi 主题集成项目结构如下：
```
mon-projet-kiubi/
├── theme/ ← Kiubi 图形主题（与 kiubi-sync 同步）
│ ├── theme.xml
│ └── fr/
│ ├── templates/
│ ├── widgets/
│ ├── billets/
│ └── ...
├── gulpfile.js
├── config.json ← FTP 凭证（排除在 git 仓库之外）
├── package.json
└── CLAUDE.md ← 参见下文
```
### 使用 kiubi-sync 部署主题
[kiubi-sync](https://aide.kiubi.com/environnement-de-travail.html) 是 Kiubi 官方的 npm 模块，用于在本地环境和服务器之间同步主题文件。它取代了 FTP 客户端，并通过 Gulp 集成。
它提供了三个主要命令：
| 命令 | 角色 |
|:------------------|:----------------------------------------------------------|
| `npm run pull` | 从服务器下载所有主题文件 |
| `npm run deploy` | 将本地文件发送到服务器 |
| `npm run watch` | 监视更改并实时同步 |
**推荐过程**：首先执行 `pull` 以检索现有主题，然后在开发过程中启动 `watch`。MCP 服务器将在这些本地文件上工作。
请参阅完整的 [kiubi-sync 文档](https://aide.kiubi.com/environnement-de-travail.html) 以完成安装和 `gulpfile.js` 配置。
### 部署 CLAUDE.md
文件 [CLAUDE.exemple.md](https://github.com/Kiubi/mcp-designer/blob/main/storage/documents/CLAUDE.exemple.md) 包含 AI 代理理解 Kiubi 上下文并正确使用 MCP 服务器工具所需的说明。它必须复制到集成项目根目录下，并使用每个代理特有的名称（`CLAUDE.md`、`AGENTS.md`、`GEMINI.md` 等）。
此文件由 Claude 在每次会话开始时自动读取。它特别定义了：
- 代理对主题的行为（在任何修改之前强制验证）
- 集成工作流（微调、标准干预）
- 要遵循的 CSS 规则和 git 约定
- 完整任务集的流水线
> **重要** - `CLAUDE.md` 特定于每个项目。它可以在项目的 git 仓库中版本化。
---
## 保密性
MCP 服务器完全在本地运行。它读取和写入集成项目 (`theme/`) 的文件，并通过 stdio 与 AI 代理通信。它不会进行任何网络调用，也不会将您的文件、代码或数据发送到任何服务器，包括 Kiubi。
项目中唯一的网络流是由您的常用工具处理的：`npx` 用于下载 npm 软件包，以及 `kiubi-sync` 用于与 Kiubi 网站同步主题。
---
## 可用工具
| 工具 | 描述 |
|:------------------|:----------------------------------------------------------------------------|
| `validate_theme` | 验证主题文件的语法和一致性 |
| `ruleset` | 返回 Kiubi 模板引擎的规则（标签、过滤器、语法） |
| `get_doc_section` | 访问文档：集成指南、示例、前端 API |
| `list_types` | 按类型列出主题元素（条目、组件、产品等） |
| `detail_type` | 返回元素的详细信息（字段、区域、集合） |
| `list_widgets` | 列出所有小部件及其替代模板 |
| `create_type` | 创建或更新元素类型（生成 XML 和 HTML 文件） |
| `search_doc` | 文档的跨领域搜索 |
