Apostrophe Cms Generator

Apostrophe代码生成器

使用Claude AI和MCP（模型上下文协议）架构的Apostrophe CMS模块的AI驱动代码生成器。

______________________________________________________________________

快速入门（TL；DR）

# 1. Ensure prerequisites are installed
node --version    # Must be >= 18
claude --version  # Must have Claude Code CLI

# 2. Install
./install.sh      # Linux/macOS
# OR manually:
npm install && cd mcp-server && npm install

# 3. Run
npm start

# 4. Open browser
# http://localhost:3031

就是这样！ 选择项目，选择模块类型，配置，生成。

______________________________________________________________________

概述

Apostrophe代码生成器是一个基于网络的工具，利用Claude AI生成生产就绪的Apostrophe-CMS模块。它提供了一个直观的向导界面，用于使用项目的设计令牌创建片段、页面、小部件和完整的捆绑包，并使用AI驱动的SCSS生成。

主要特点

• 工件生成器：创建存储在数据库中的内容类型
• 页面生成器：生成具有内容区域和片段关系的页面类型
• 小部件生成器：创建具有关系模式的可重用UI组件
• 线束生成器：一次性生成完整的功能集（片段+页面+小部件）
• 设计令牌提取：自动提取并使用项目的SCSS设计令牌
• BEM方法论：可选的SCSS生成遵循BEM命名约定（实验）
• 自动注册：自动将生成的模块注册到项目的 modules.js
• SCSS集成：自动创建和导入SCSS文件
• 世代历史：浏览和重用以前生成的模块

备注：CSS/SCSS生成是实验性的。结果可能因项目复杂性和设计令牌可用性而异。在部署到生产环境之前，始终检查生成的样式。

______________________________________________________________________

先决条件

安装前，请确保具备以下条件：

必需

安装克劳德代码

克劳德代码是 必需的 用于AI驱动的代码生成。应用程序调用 claude CLI直接生成Apostrophe模块。

# Install Claude Code globally
npm install -g @anthropic-ai/claude-code

# Configure with your Anthropic API key
claude configure

您需要一个Anthropic API密钥。获取一个：https://console.anthropic.com/

要验证Claude Code是否正确安装：

claude --version

ESM（ES模块）要求

重要提示： 此工具使用以下方式生成代码 ES模块语法 (export default)而不是CommonJS(module.exports).您的Apostrophe项目必须配置为ESM。

确保您的项目 package.json 包含：

{
  "type": "module"
}

生成的代码语法：

// ✅ This tool generates (ESM):
export default {
  extend: '@apostrophecms/widget-type',
  fields: { ... }
};

// ❌ NOT CommonJS:
module.exports = {
  extend: '@apostrophecms/widget-type',
  fields: { ... }
};

如果你的项目使用CommonJS，你需要：

1. 转换为ESM （建议用于Apostrophe 3.x/4.x）
2. 手动转换生成 export default 到 module.exports

Apostrophe CMS项目

该工具自动发现Apostrophe CMS项目 父目录。如果文件夹包含以下内容，则将其识别为Apostrophe项目 app.js 文件与a shortName 财产。

目录结构示例：

/projects/                           # Parent directory
├── apostrophe-code-generator/       # This tool
├── my-apostrophe-site/              # ✓ Discovered (has app.js with shortName)
├── another-apostrophe-project/      # ✓ Discovered
└── some-other-folder/               # ✗ Ignored (no app.js with shortName)

______________________________________________________________________

安装

快速安装（推荐）

# Clone or download the repository
cd /path/to/apostrophe-code-generator

# Run the install script
./install.sh

安装脚本将：

1. 检查Node.js和npm
2. 安装主要应用程序依赖项
3. 安装MCP服务器依赖项
4. 可选配置Claude Code集成

手动安装

如果您更喜欢手动安装：

# Navigate to the project directory
cd /path/to/apostrophe-code-generator

# Install main dependencies
npm install

# Install MCP server dependencies
cd mcp-server
npm install
cd ..

______________________________________________________________________

用法

启动应用程序

# From the project root directory
npm start

# Or for development with auto-reload
npm run dev

服务器将于启动 http://localhost:3031

使用Web界面

1. 打开浏览器 并导航到 http://localhost:3031

1. 选择一个项目：从下拉列表中选择一个Apostrophe项目。项目将从父目录中自动发现。

1. 选择模块类型：选择要生成的内容：

- 件：数据库中存储的内容类型 - 页：带内容区域的页面类型 - 小部件：可重用UI组件 - 捆绑：完整的功能集（片+页+小部件）

1. 配置选项：填写模块详细信息：

- 模块名称 - 描述 - 领域和关系 - 造型选项（BEM、设计符号）

1. 生成：点击“生成代码”，观看AI创建您的模块

1. 保存到项目：查看生成的代码并将其直接保存到您的项目中

世代历史

所有生成的模块都保存到历史记录中。你可以：

• 查看以前生成的模块
• 使用修改后的设置重新生成
• 将代码复制到剪贴板
• 从历史记录中删除

______________________________________________________________________

高级：直接克劳德代码MCP集成

此部分是可选的。 web UI位于 localhost:3031 是使用此工具的主要方式。此MCP集成仅适用于希望直接从Claude Code CLI调用生成器而不使用web界面的高级用户。

为什么使用这个？

如果你已经在Apostrophe项目的Claude Code会话中工作，你可以通过让Claude Code使用生成器工具直接生成模块，而不需要切换到浏览器。

例子： 在Claude Code中，你可以说：

“使用撇号生成器为我的项目创建一个名为新闻提要的小部件”

配置

1. 找到您的Claude Code设置文件:

- Linux/macOS： ~/.claude/settings.json - 窗户： %USERPROFILE%\.claude\settings.json

1. 添加MCP服务器配置:

{
  "mcpServers": {
    "apostrophe-generator": {
      "command": "node",
      "args": ["/absolute/path/to/apostrophe-code-generator/mcp-server/index.js"],
      "env": {},
      "description": "Apostrophe CMS code generation tools"
    }
  }
}

替换 /absolute/path/to/ 安装的实际路径。

1. 重新启动Claude代码 加载新的MCP服务器

可用的MCP工具

配置后，以下工具在Claude Code中可用：

______________________________________________________________________

生成的模块结构

本节详细介绍了为每种模块类型生成的文件及其结构。

工件模块

片段是存储在数据库中的内容类型（如文章、产品、团队成员）。

生成的文件：

modules/pieces/{piece-name}/
└── index.js              # Schema definition with fields

无模板 -片段仅为数据；它们通过页面或小部件显示。

index.js结构：

export default {
  extend: '@apostrophecms/piece-type',
  options: {
    label: 'Piece Name',
    pluralLabel: 'Piece Names',
    seoFields: false,
    openGraph: false
  },
  fields: {
    add: {
      // Custom fields defined here
      description: { type: 'string', label: 'Description' },
      featuredImage: {
        type: 'area',
        label: 'Featured Image',
        options: {
          widgets: { '@apostrophecms/image': {} }
        }
      }
    },
    group: {
      basics: {
        label: 'Basics',
        fields: ['title', 'description', 'featuredImage']
      }
    }
  }
};

页面模块

页面是可通过URL路由的内容，可以显示片段（片段页面）或独立内容。

生成的文件：

modules/pages/{page-name}/
├── index.js              # Schema definition
└── views/
    ├── index.html        # List view (for piece-pages)
    └── show.html         # Detail view (for piece-pages)

对于独立页面，仅 page.html 生成而不是索引/显示。

index.js结构：

export default {
  extend: '@apostrophecms/piece-page-type',  // or '@apostrophecms/page-type'
  options: {
    label: 'Page Name',
    pieceModuleName: 'piece-name'  // For piece-pages only
  },
  fields: {
    add: {
      // Page-specific fields
    },
    group: {
      // Field groups
    }
  }
};

小部件模块

小部件是可重用的UI组件，可以放置在内容区域中。

生成的文件：

modules/widgets/{widget-name}-widget/
├── index.js              # Schema definition
└── views/
    └── widget.html       # Widget template

注： 小部件文件夹名称始终以结尾 -widget 后缀。

index.js结构：

export default {
  extend: '@apostrophecms/widget-type',
  fields: {
    add: {
      heading: { type: 'string', label: 'Heading' },
      content: {
        type: 'area',
        label: 'Content',
        options: {
          widgets: {
            '@apostrophecms/rich-text': {},
            '@apostrophecms/image': {}
          }
        }
      }
    },
    group: {
      basics: {
        label: 'Basics',
        fields: ['heading', 'content']
      }
    }
  }
};

widget.html模板：

  
{{ data.widget.heading }}

  {% area data.widget, 'content' %}

捆绑模块

Bundles在一次操作中生成一个完整的功能集：片段+片段页面+小部件。

生成的文件：

modules/
├── pieces/{name}/
│   └── index.js
├── pages/{name}-page/
│   ├── index.js
│   └── views/
│       ├── index.html
│       └── show.html
└── widgets/{name}-widget/
    ├── index.js
    └── views/
        └── widget.html

捆绑关系：

• 小部件自动包含 _pieces 关系字段引用工件
• 该页面被配置为工件类型的工件页面

______________________________________________________________________

SCSS生成（可选）

当 BEM风格 启用后，将生成其他SCSS文件。

生成的SCSS文件

modules/asset/ui/src/scss/
├── components/
│   └── _{widget-name}.scss    # For widgets
└── pages/
    └── _{page-name}.scss      # For pages

SCSS功能

• BEM方法论：块元素修改器命名约定
• 设计令牌集成：使用项目现有的设计标记（颜色、间距、排版）
• 自动导入：SCSS文件会自动导入到主样式表中

生成的SCSS示例：

// _news-widget.scss
.news-widget {
  padding: $spacing-lg;
  background-color: $color-background;

  &__heading {
    font-size: $font-size-xl;
    color: $color-text-primary;
    margin-bottom: $spacing-md;
  }

  &__content {
    line-height: $line-height-relaxed;
  }

  &__item {
    border-bottom: 1px solid $color-border;
    padding: $spacing-md 0;

    &:last-child {
      border-bottom: none;
    }
  }
}

设计令牌提取

生成器会自动扫描您的项目中的设计标记：

• modules/asset/ui/src/scss/_settings.scss
• modules/asset/ui/src/scss/_variables.scss
• 任何匹配的文件 *variables* 或 *tokens* 模式

提取的令牌类型：

• 颜色($color-*)
• 间距($spacing-*)
• 排版($font-*, $line-height-*)
• 断点($breakpoint-*)

______________________________________________________________________

自动注册

生成的模块会自动注册到项目的 modules.js 文件。

添加什么

// modules.js
module.exports = {
  // ... existing modules ...

  // Auto-added by Code Generator:
  'news': {},                    // Piece
  'news-page': {},               // Page
  'news-widget': {},             // Widget
};

SCSS导入

如果生成了SCSS，则会将导入语句添加到您的主SCSS文件中：

// In _components.scss or main.scss
@import 'components/_news-widget';

______________________________________________________________________

历史存储

所有生成的模块都保存到 history/ 文件夹以供参考和重复使用。

历史文件夹结构

history/
└── 2025-11-18_14-30-45_news-widget/
    ├── metadata.json
    └── modules/
        └── widgets/
            └── news-widget/
                ├── index.js
                └── views/
                    └── widget.html

元数据格式

{
  "moduleName": "news-widget",
  "moduleType": "widget",
  "projectName": "my-apostrophe-project",
  "fileCount": 2,
  "fullDesign": false,
  "description": "A widget to display latest news items",
  "timestamp": "2025-11-18T14:30:45.123Z"
}

历史特征

• 视图：浏览以前生成的模块
• 重新生成：使用以前的设置作为起点
• 复制：将代码直接复制到剪贴板
• 删除：从历史记录中删除条目（不影响已保存的项目文件）

______________________________________________________________________

API终点

Express服务器公开了这些端点：

生成请求格式

{
  "projectId": "my-project",
  "type": "widget",
  "name": "news",
  "label": "News Widget",
  "description": "Display latest news with images and summaries",
  "includeBemStyles": true,
  "fullDesign": false
}

生成响应格式

{
  "success": true,
  "files": [
    {
      "path": "modules/widgets/news-widget/index.js",
      "content": "export default { ... }"
    },
    {
      "path": "modules/widgets/news-widget/views/widget.html",
      "content": "
...
"
    }
  ],
  "registrationNote": "Module registered in modules.js",
  "historyId": "2025-11-18_14-30-45_news-widget"
}

______________________________________________________________________

字段类型参考

模块架构的可用字段类型：

保留字段名称

永远不要使用这些名字 -它们由Apostrophe保留：

• type, _id, slug, published, archived
• trash, visibility, createdAt, updatedAt
• metaType, aposMode, aposLocale

选择：

• 而非 type → use category, kind, itemType
• 而非 status → use currentStatus, statusLabel

______________________________________________________________________

项目结构

apostrophe-code-generator/
├── server/                     # Express server
│   ├── index.js               # Main server entry point
│   ├── mcp-client.js          # MCP client for AI generation
│   └── apostrophe-docs/       # Apostrophe documentation & patterns
├── mcp-server/                 # MCP server for Claude Code
│   ├── index.js               # MCP server entry point
│   ├── generator.js           # Code generation logic
│   ├── design-token-parser.js # Design token extraction
│   ├── package.json           # MCP server dependencies
│   └── mcp-config.json        # Example MCP configuration
├── public/                     # Web UI
│   ├── index.html             # Main wizard interface
│   ├── css/                   # Stylesheets
│   └── js/                    # Client-side JavaScript
├── docs/                       # Documentation
├── history/                    # Generated module history
├── install.sh                  # Installation script
├── package.json               # Main dependencies
└── README.md                  # This file

______________________________________________________________________

配置

服务器端口

默认端口为 3031。要更改它，请设置 PORT 环境变量：

PORT=8080 npm start

项目发现

默认情况下，该工具在父目录中查找Apostrophe项目。此行为是自动的，不需要配置。

______________________________________________________________________

故障排除

常见问题

“找不到模块'@modelcontextprotocol/sdk'”

未安装MCP服务器依赖项。运行：

cd mcp-server
npm install

“未找到项目”

确保您的Apostrophe项目位于父目录中，并包含 app.js 文件与a shortName 财产：

// app.js
module.exports = require('apostrophe')({
  shortName: 'my-project',
  // ...
});

“Claude API超时”或生成失败

1. 确保已安装Claude Code： claude --version
2. 确保配置了Claude代码： claude configure
3. 检查您的Anthropic API密钥是否有效
4. 尝试更简单的模块描述
5. 检查您的互联网连接

“MCP服务器失败”

1. 检查Claude设置中的MCP服务器路径是否正确
2. 确保安装了所有依赖项
3. 检查Node.js版本（需要>=18）

端口已在使用中

另一个应用程序正在使用端口3031。要么：

• 停止其他应用程序
• 使用其他端口： PORT=3032 npm start

获取帮助

如果您遇到问题：

1. 检查浏览器控制台是否有错误
2. 检查终端是否存在服务器端错误
3. 确保满足所有先决条件
4. 验证项目结构是否与预期格式匹配

______________________________________________________________________

建筑

组件

1. 快递服务器 (server/index.js)

- 提供web UI - 处理API请求 - 管理项目发现 - 与MCP服务器通信

1. MCP服务器 (mcp-server/index.js)

- 提供AI驱动的代码生成 - 与Claude AI集成 - 公开用于Claude代码集成的工具

1. Web用户界面 (public/)

- 向导风格界面 - 实时发电进度 - 历史管理

数据流

User Input → Express Server → MCP Server → Claude AI
                                    ↓
User ← Web UI ← Express Server ← Generated Code

______________________________________________________________________

发展

以开发模式运行

npm run dev

这将启动服务器，并在文件更改时自动重新加载。

建筑顺风CSS

如果修改样式：

./tailwindcss-linux-x64 -i public/css/input.css -o public/css/styles.css --watch

______________________________________________________________________

贡献

欢迎投稿！请确保：

1. 代码遵循现有模式
2. 记录新功能
3. 测试通过（如适用）

______________________________________________________________________

Windows安装

这 install.sh 该脚本适用于Linux/macOS。Windows用户应手动安装：

使用命令提示符

cd path\to\apostrophe-code-generator

:: Install main dependencies
npm install

:: Install MCP server dependencies
cd mcp-server
npm install
cd ..

:: Start the server
npm start

使用PowerShell

cd path\to\apostrophe-code-generator

# Install main dependencies
npm install

# Install MCP server dependencies
cd mcp-server
npm install
cd ..

# Start the server
npm start

Windows先决条件

1. Node.js：从下载https://nodejs.org/（v18+）
2. 克劳德代码: npm install -g @anthropic-ai/claude-code
3. 配置Claude： claude configure

______________________________________________________________________

兼容性

Apostrophe CMS版本

此工具生成以下代码 撇号3.x和4.x模块结构、字段类型和模板语法与A3和A4兼容。

Node.js版本

操作系统

______________________________________________________________________

已知限制

SCSS生成（实验）

• 当您的项目具有定义良好的设计令牌时，SCSS生成效果最佳
• 如果项目中不存在令牌，则生成的SCSS可能包含未定义的变量
• 编译前始终检查生成的SCSS
• 复杂的布局可能需要手动调整

人工智能一代

• 结果取决于描述的质量
• 非常复杂的模块可能需要多代或手动编辑
• 生成时间各不相同（通常为10-60秒，具体取决于复杂性）
• 偶尔出现的JSON解析错误可能需要重试

项目发现

• 仅在中发现项目 父目录
• 项目必须具备 app.js 随着 shortName 财产
• 可能找不到Symlinked项目

捆绑包生成

• 捆绑包一次生成3个模块-这可能需要更长的时间
• 所有3个模块共享相同的基本名称
• 无法自定义捆绑包中的单个模块名称

______________________________________________________________________

常见问题解答

将军

Q： 我需要Anthropic API钥匙吗？ A： 是的。Claude Code需要来自的API密钥https://console.anthropic.com/

Q： 使用它要花多少钱？ A： 工具本身是免费的。您通过Anthropic帐户支付Claude API的使用费用。每一代通常使用1000-5000个代币。

Q： 我可以离线使用这个吗？ A： 不需要。该工具需要互联网接入才能与Claude AI通信。

项目

Q： 为什么我的项目没有出现在下拉列表中？ A： 确保您的项目：

• 位于此工具的父目录中
• 有一个 app.js 文件
• 包含 shortName: 'your-project' 在app.js中

Q： 我可以更改项目发现位置吗？ A： 目前没有。项目必须在父目录中。这可以在未来的版本中配置。

生成

Q： 生成的代码有错误。我该怎么办？ A： 尝试：

1. 简化你的描述
2. 再次生成（AI响应各不相同）
3. 手动编辑生成的代码
4. 检查保留的字段名

Q： 我可以在保存之前编辑生成的代码吗？ A： 目前不在UI中。在IDE中生成、保存和编辑。

Q： 如何重新生成模块？ A： 使用历史记录功能查看前几代，并使用修改后的设置重新生成。

样式

Q： SCSS具有未定义的变量。为什么？ A： 生成器使用项目的设计令牌。如果令牌不存在，则变量将未定义。替换为实际值或将标记添加到项目中。

Q： 我可以禁用SCSS生成吗？ A： 是的。配置模块时取消选中“包含边界元样式”。

______________________________________________________________________

卸载

要删除代码生成器，请执行以下操作：

# Simply delete the folder
rm -rf /path/to/apostrophe-code-generator

# Optional: Remove global Claude Code if no longer needed
npm uninstall -g @anthropic-ai/claude-code

Apostrophe项目中生成的模块是 不影响 通过卸载此工具。

______________________________________________________________________

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

______________________________________________________________________

鸣谢

由...创建安德烈·马泰亚斯 对于：GLOOBUS A队

基于Claude AI和MCP（模型上下文协议）构建

______________________________________________________________________

更新日志

v1.0.0

• 初始版本
• 工件、页面、小部件和捆绑包生成器
• 设计令牌提取
• BEM SCSS生成（实验）
• 发电历史
• Claude Code MCP集成