Apostrophe Cms Generator

🚀 Apostrophe Code Generator

Apostrophe Code Generatorは、Claude AIとMCP（Model Context Protocol）アーキテクチャを利用した、Apostrophe CMSモジュール用のAI駆動型コード生成ツールです。このツールは、生産環境で使用可能なApostrophe CMSモジュールを簡単に生成することができます。

🚀 クイックスタート

# 1. 前提条件がインストールされていることを確認
node --version    # バージョンが18以上である必要があります
claude --version  # Claude Code CLIが必要です

# 2. インストール
./install.sh      # Linux/macOS
# または手動で:
npm install && cd mcp-server && npm install

# 3. 実行
npm start

# 4. ブラウザを開く
# http://localhost:3031

以上です！プロジェクトを選択し、モジュールタイプを選び、設定を行い、コードを生成することができます。

✨ 主な機能

• Piece Generator：データベースに保存されるコンテンツタイプを作成します。
• Page Generator：コンテンツエリアとPieceの関係を持つページタイプを生成します。
• Widget Generator：関係パターンを持つ再利用可能なUIコンポーネントを作成します。
• Bundle Generator：Piece、Page、Widgetをまとめた完全な機能セットを一度に生成します。
• Design Token Extraction：プロジェクトのデザイントークンを自動的に抽出し、SCSS生成に使用します。
• BEM Methodology：オプションで、BEM命名規則に従ったSCSS生成を行います（実験的機能）。
• Auto-Registration：生成されたモジュールを自動的にプロジェクトのmodules.jsに登録します。
• SCSS Integration：SCSSファイルを自動的に作成し、インポートします。
• Generation History：以前に生成したモジュールを閲覧し、再利用することができます。

⚠️ 重要提示

CSS/SCSS生成は実験的機能です。結果はプロジェクトの複雑さやデザイントークンの可用性によって異なります。本番環境にデプロイする前に、必ず生成されたスタイルを確認してください。

📦 インストール

クイックインストール（推奨）

# リポジトリをクローンまたはダウンロード
cd /path/to/apostrophe-code-generator

# インストールスクリプトを実行
./install.sh

インストールスクリプトは以下のことを行います：

1. Node.jsとnpmがインストールされていることを確認します。
2. メインアプリケーションの依存関係をインストールします。
3. MCPサーバーの依存関係をインストールします。
4. オプションでClaude Codeの統合を設定します。

手動インストール

手動でインストールする場合は、以下のコマンドを実行します：

# プロジェクトディレクトリに移動
cd /path/to/apostrophe-code-generator

# メインの依存関係をインストール
npm install

# MCPサーバーの依存関係をインストール
cd mcp-server
npm install
cd ..

💻 使用例

基本的な使用法

# アプリケーションを起動
npm start

# または開発モードで自動リロードを有効にする場合
npm run dev

サーバーは http://localhost:3031 で起動します。

Webインターフェイスの使用方法

1. ブラウザを開き、http://localhost:3031にアクセスします。
2. プロジェクトを選択：ドロップダウンからApostropheプロジェクトを選択します。プロジェクトは親ディレクトリから自動的に検出されます。
3. モジュールタイプを選択：生成するものを選択します：
   • Piece：データベースに保存されるコンテンツタイプ
   • Page：コンテンツエリアを持つページタイプ
   • Widget：再利用可能なUIコンポーネント
   • Bundle：完全な機能セット（Piece + Page + Widget）
4. オプションを設定：モジュールの詳細を入力します：
   • モジュール名
   • 説明
   • フィールドと関係
   • スタイリングオプション（BEM、デザイントークン）
5. コードを生成：「Generate Code」をクリックし、AIがモジュールを作成します。
6. プロジェクトに保存：生成されたコードを確認し、直接プロジェクトに保存します。

生成履歴

生成されたすべてのモジュールは履歴に保存されます。以下のことができます：

• 以前に生成したモジュールを閲覧する
• 変更した設定で再生成する
• コードをクリップボードにコピーする
• 履歴から削除する

🔧 技術詳細

生成されたモジュールの構造

Piece Module

Piecesはデータベースに保存されるコンテンツタイプです（記事、製品、チームメンバーなど）。

modules/pieces/{piece-name}/
└── index.js              # フィールドを持つスキーマ定義

テンプレートは生成されません - Piecesはデータのみであり、piece-pagesまたはwidgetsを通じて表示されます。

export default {
  extend: '@apostrophecms/piece-type',
  options: {
    label: 'Piece Name',
    pluralLabel: 'Piece Names',
    seoFields: false,
    openGraph: false
  },
  fields: {
    add: {
      // ここで定義されたカスタムフィールド
      description: { type: 'string', label: 'Description' },
      featuredImage: {
        type: 'area',
        label: 'Featured Image',
        options: {
          widgets: { '@apostrophecms/image': {} }
        }
      }
    },
    group: {
      basics: {
        label: 'Basics',
        fields: ['title', 'description', 'featuredImage']
      }
    }
  }
};

Page Module

PagesはURLルーティング可能なコンテンツで、Piecesを表示することができます（piece-pages）またはスタンドアロンのコンテンツです。

modules/pages/{page-name}/
├── index.js              # スキーマ定義
└── views/
    ├── index.html        # 一覧表示（piece-pagesの場合）
    └── show.html         # 詳細表示（piece-pagesの場合）

スタンドアロンページの場合、index/showの代わりにpage.htmlのみが生成されます。

export default {
  extend: '@apostrophecms/piece-page-type',  // または '@apostrophecms/page-type'
  options: {
    label: 'Page Name',
    pieceModuleName: 'piece-name'  // piece-pagesの場合のみ
  },
  fields: {
    add: {
      // ページ固有のフィールド
    },
    group: {
      // フィールドグループ
    }
  }
};

Widget Module

Widgetsはコンテンツエリアに配置できる再利用可能なUIコンポーネントです。

modules/widgets/{widget-name}-widget/
├── index.js              # スキーマ定義
└── views/
    └── widget.html       # Widgetテンプレート

注意：Widgetフォルダ名は常に-widgetサフィックスで終わります。

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']
      }
    }
  }
};

<div class="widget-name-widget" data-widget-name-widget>
  <h2>{{ data.widget.heading }}</h2>
  {% area data.widget, 'content' %}
</div>

Bundle Module

Bundlesは一度に3つのモジュールを生成します：Piece、Page、Widget。

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

Bundleの関係：

• Widgetは自動的に_pieces関係フィールドを含み、Pieceを参照します。
• PageはPieceタイプのpiece-pageとして構成されます。

SCSS生成（オプション）

BEM Stylesが有効になっている場合、追加のSCSSファイルが生成されます。

modules/asset/ui/src/scss/
├── components/
│   └── _{widget-name}.scss    # Widget用
└── pages/
    └── _{page-name}.scss      # ページ用

SCSSの機能

• BEM Methodology：Block-Element-Modifier命名規則
• Design Token Integration：プロジェクトの既存のデザイントークン（色、スペーシング、タイポグラフィ）を使用する
• Auto-Import：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 = {
  // ... 既存のモジュール ...

  // コードジェネレーターによって自動追加される:
  'news': {},                    // Piece
  'news-page': {},               // Page
  'news-widget': {},             // Widget
};

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": "<div class=\"news-widget\">...</div>"
    }
  ],
  "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の代わりに → category, kind, itemTypeを使用する
• statusの代わりに → currentStatus, statusLabelを使用する

プロジェクト構造

apostrophe-code-generator/
├── server/                     # Expressサーバー
│   ├── index.js               # メインサーバーエントリポイント
│   ├── mcp-client.js          # AI生成用のMCPクライアント
│   └── apostrophe-docs/       # Apostropheドキュメントとパターン
├── mcp-server/                 # Claude Code用のMCPサーバー
│   ├── index.js               # MCPサーバーエントリポイント
│   ├── generator.js           # コード生成ロジック
│   ├── design-token-parser.js # デザイントークン抽出
│   ├── package.json           # MCPサーバーの依存関係
│   └── mcp-config.json        # 例のMCP設定
├── public/                     # Web UI
│   ├── index.html             # メインウィザードインターフェイス
│   ├── css/                   # スタイルシート
│   └── js/                    # クライアントサイドJavaScript
├── docs/                       # ドキュメント
├── history/                    # 生成されたモジュールの履歴
├── install.sh                  # インストールスクリプト
├── package.json               # メインの依存関係
└── README.md                  # このファイル

設定

サーバーポート

デフォルトのポートは3031です。ポートを変更するには、PORT環境変数を設定します：

PORT=8080 npm start

プロジェクトの検出

デフォルトでは、このツールは親ディレクトリのApostropheプロジェクトを自動的に検出します。この動作は自動で、設定は必要ありません。

トラブルシューティング

一般的な問題

• "Cannot find module '@modelcontextprotocol/sdk'"：MCPサーバーの依存関係がインストールされていません。以下のコマンドを実行してください：

cd mcp-server
npm install

• "No projects found"：Apostropheプロジェクトが親ディレクトリにあり、app.jsファイルにshortNameプロパティが含まれていることを確認してください：

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

• "Claude API timeout" または生成が失敗する：
  1. Claude Codeがインストールされていることを確認してください：claude --version
  2. Claude Codeが設定されていることを確認してください：claude configure
  3. Anthropic APIキーが有効であることを確認してください
  4. よりシンプルなモジュールの説明を試してください
  5. インターネット接続を確認してください
• "MCP server failed"：
  1. Claude設定のMCPサーバーのパスが正しいことを確認してください
  2. すべての依存関係がインストールされていることを確認してください
  3. Node.jsのバージョンが18以上であることを確認してください
• ポートが既に使用されている：別のアプリケーションがポート3031を使用しています。以下のいずれかを行ってください：
  • 他のアプリケーションを停止する
  • 別のポートを使用する：PORT=3032 npm start

ヘルプの取得

問題が発生した場合は、以下のことを行ってください：

1. ブラウザのコンソールでエラーを確認する
2. ターミナルでサーバー側のエラーを確認する
3. すべての前提条件が満たされていることを確認する
4. プロジェクトの構造が期待される形式と一致することを確認する

アーキテクチャ

コンポーネント

1. Express Server (server/index.js)
   • Web UIを提供します。
   • APIリクエストを処理します。
   • プロジェクトの検出を管理します。
   • MCPサーバーと通信します。
2. MCP Server (mcp-server/index.js)
   • AI駆動のコード生成を提供します。
   • Claude AIと統合します。
   • Claude Code統合用のツールを公開します。
3. Web UI (public/)
   • ウィザードスタイルのインターフェイスです。
   • リアルタイムの生成進捗を表示します。
   • 履歴管理を行います。

データフロー

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

開発

開発モードで実行

npm run dev

これにより、ファイルの変更時に自動リロードされるサーバーが起動します。

Tailwind 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

:: メインの依存関係をインストール
npm install

:: MCPサーバーの依存関係をインストール
cd mcp-server
npm install
cd ..

:: サーバーを起動
npm start

PowerShellを使用する場合

cd path\to\apostrophe-code-generator

# メインの依存関係をインストール
npm install

# MCPサーバーの依存関係をインストール
cd mcp-server
npm install
cd ..

# サーバーを起動
npm start

Windowsの前提条件

1. Node.js：https://nodejs.org/ からダウンロードしてください（v18以上）
2. Claude Code：npm install -g @anthropic-ai/claude-code
3. Claudeを設定する：claude configure

互換性

Apostrophe CMSのバージョン

Node.jsのバージョン

オペレーティングシステム

既知の制限事項

SCSS生成（実験的）

• SCSS生成は、プロジェクトに明確に定義されたデザイントークンがある場合に最適に機能します。
• 生成されたSCSSには、プロジェクトにトークンが存在しない場合、未定義の変数が含まれる可能性があります。
• コンパイルする前に、必ず生成されたSCSSを確認してください。
• 複雑なレイアウトは手動で調整する必要がある場合があります。

AI生成

• 結果は説明の質に依存します。
• 非常に複雑なモジュールは、複数回の生成または手動編集が必要な場合があります。
• 生成時間は変動します（通常、複雑さに応じて10-60秒）。
• 時折、JSON解析エラーが発生する場合があり、再試行が必要です。

プロジェクトの検出

• 親ディレクトリのプロジェクトのみが検出されます。
• プロジェクトにはapp.jsファイルとshortNameプロパティが必要です。
• シンボリックリンクされたプロジェクトは検出されない場合があります。

バンドル生成

• バンドルは一度に3つのモジュールを生成するため、時間がかかる場合があります。
• 3つのモジュールはすべて同じ基本名を共有します。
• バンドル内の個々のモジュール名をカスタマイズすることはできません。

FAQ

一般的な質問

Q: Anthropic APIキーは必要ですか？ A: はい。Claude Codeにはhttps://console.anthropic.com/ からのAPIキーが必要です。

Q: 使用にはどれくらいの費用がかかりますか？ A: ツール自体は無料です。Claude APIの使用料は、あなたのAnthropicアカウントで支払います。各生成には通常1,000-5,000トークンが使用されます。

Q: これをオフラインで使用できますか？ A: いいえ。このツールはClaude AIと通信するためにインターネットアクセスが必要です。

プロジェクトに関する質問

Q: なぜ私のプロジェクトがドロップダウンに表示されないのですか？ A: あなたのプロジェクトが以下の条件を満たしていることを確認してください：

• このツールの親ディレクトリにある
• app.jsファイルを持っている
• app.jsにshortName: 'your-project'が含まれている

Q: プロジェクトの検出場所を変更できますか？ A: 現在はできません。プロジェクトは親ディレクトリになければなりません。将来的なバージョンで設定可能になるかもしれません。

生成に関する質問

Q: 生成されたコードにエラーがあります。どうすればいいですか？ A: 以下を試してみてください：

1. 説明を簡略化する
2. 再度生成する（AIの応答は変動する）
3. 生成されたコードを手動で編集する
4. 予約済みのフィールド名を確認する

Q: 保存する前に生成されたコードを編集できますか？ A: 現在、UIではできません。生成し、保存してから、IDEで編集してください。

Q: モジュールを再生成するにはどうすればいいですか？ A: 履歴機能を使用して、以前の生成を表示し、変更した設定で再生成します。

スタイリングに関する質問

Q: SCSSに未定義の変数があります。なぜですか？ A: ジェネレーターはプロジェクトのデザイントークンを使用します。トークンが存在しない場合、変数は未定義になります。実際の値に置き換えるか、トークンをプロジェクトに追加してください。

Q: SCSS生成を無効にできますか？ A: はい。モジュールを設定するときに「Include BEM Styles」のチェックを外してください。

アンインストール

コードジェネレーターを削除するには、以下のコマンドを実行します：

# フォルダを削除するだけです
rm -rf /path/to/apostrophe-code-generator

# オプション: もはや必要ない場合は、グローバルなClaude Codeを削除する
npm uninstall -g @anthropic-ai/claude-code

Apostropheプロジェクトに生成されたモジュールは、このツールをアンインストールしても影響を受けません。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

クレジット

作成者: Andrei Mateas 対象: GLOOBUS A-Team Claude AIとMCP（Model Context Protocol）を使用して構築されています。

変更履歴

v1.0.0

• 初期リリース
• Piece、Page、Widget、およびBundleジェネレーター
• デザイントークンの抽出
• BEM SCSS生成（実験的）
• 生成履歴
• Claude Code MCP統合