pilates_mcp

pilates_mCP は、ピラティスセンターのプロモーションポスター向けのローカルファーストMCPサーバーです。編集可能なHTML/CSSポスターソースを作成し、ローカルアーカイブに保存し、過去のポスターを検索・再利用し、デザインフィードバックを記録し、ヘッドレスChromiumでPNG/PDFアーティファクトをレンダリングできます。

フェーズ1では、会員名、電話番号、スケジュール、健康データ、支払いデータ、その他の会員個人情報を意図的に保存しません。

プロジェクト構造

実装時点でこのリポジトリは空だったため、サーバーはTypeScript + Node.jsのMCPサーバーとして実装されています。

src/
  server.ts        MCP stdio JSON-RPC transport and tool dispatch
  service.ts       poster workflow orchestration
  repository.ts    local poster archive search/read/write
  renderer.ts      Playwright PNG/PDF renderer
  templates.ts     HTML/CSS template layer
  feedback.ts      design feedback storage
  profile.ts       center profile storage
  themes.ts        design token presets
  types.ts         domain types
data/
  posters/YYYY/<poster-id>/
    poster.html
    poster.css
    metadata.json
    content.json
    preview.png    optional
    poster.pdf     optional
    revisions/     update backups
  feedback/
    global.json
    table.json
    standard.json
    poster-<poster-id>.json
  config/
    center-profile.json
  schedules/
    settings.json
    center-closures.json
    group/
      template.json
      group_schedule.xlsx
      revisions/
    private/
      template.json
      private_schedule.xlsx
      revisions/

Related MCP server: Networking MCP

インストール

npm install
npx playwright install chromium

開発

npm run build
npm test
npm run dev

PILATES_MCP_DATA_DIR は、アーカイブを別のローカルデータディレクトリに指定できます。未設定の場合、サーバーは ./data を使用します。

Railwayデプロイ

Railwayデプロイは railway.json と Dockerfile で設定されています。

本番コンテナは公式のPlaywrightイメージを使用するため、PNG/PDFレンダリング用のChromiumランタイム依存関係が利用可能です。Railwayは npm run start:railway を起動し、以下を公開します:

• GET /health: デプロイのヘルスチェック

• GET /tools: デプロイ検査用のMCPツール概要

• GET /schedule: 軽量なExcelスタイルのスケジュールワークスペース

stdio MCPサーバーは、コマンドで接続するMCPクライアント向けに npm run start を通じて引き続き利用可能です。Railwayのヘルスプロセスは、stdio MCPがHTTPポートを公開しないため、意図的に分離されています。

Railwayでの永続的なローカルファーストアーカイブストレージには、Railwayボリュームを /data にマウントするか、PILATES_MCP_DATA_DIR を別の永続パスに設定します。

MCPクライアント接続

ビルド済みサーバーをstdio MCPコマンドとして使用します:

{
  "mcpServers": {
    "pilates_mcp": {
      "command": "node",
      "args": ["G:/pilates_mcp/dist/src/server.js"],
      "env": {
        "PILATES_MCP_DATA_DIR": "G:/pilates_mcp/data"
      }
    }
  }
}

ツール

ポスターツール:

• get_center_profile

• update_center_profile

• search_posters

• get_poster

• create_poster

• update_poster

• reuse_poster_template

• import_poster

• render_poster

• add_design_feedback

• get_design_feedback

• recommend_poster_style

スケジュールツール:

• get_schedule_settings

• update_schedule_settings

• inspect_schedule_file

• import_schedule_file

• create_schedule_template

• get_schedule

• generate_weekly_schedule

• set_schedule_slot

• clear_schedule_slot

• find_available_slots

• validate_schedule

• add_center_closure

• remove_center_closure

• get_center_closures

• save_schedule

• export_schedule

• create_schedule_poster

ポスター作成フロー

create_poster はセンターのプロフィールを読み取り、センターのデフォルトを適用し、PosterBrief を検証し、関連するフィードバックを収集し、レイアウトとテーマを解決し、静的HTML/CSSをレンダリングし、メタデータ/コンテンツ/ソースファイルを書き込み、オプションでPNG/PDFをレンダリングします。

必要な順序は次のとおりです:

user request
-> center profile defaults
-> PosterBrief
-> validation
-> ask only missing questions
-> past posters and feedback
-> HTML/CSS
-> optional render
-> archive save

必須のポスター概要の決定事項は、生成前に検証されます:

• eventName

• programSeparation

• tablePreference

• テーブルが必要または提供される場合の tableStyle

• 価格コンテンツが存在する場合の vatPolicy

サーバーは、欠落しているイベント名、VATポリシー、プログラム分離を推測する代わりに、valid: false、missing、韓国語の questions を返します。

programSeparation と tableStyle は別々の決定事項です。たとえば、グループ/プライベート商品は programSeparation: "table" と tableStyle: "split" を使用して、別々のGROUP/PRIVATEテーブルブロックをレンダリングできます。tablePreference はユーザーの意図を表し、layout は最終的なレンダラー選択です。

センターのデフォルトにより、繰り返しの質問を減らせます:

{
  "posterDefaults": {
    "programSeparation": "table",
    "tablePreference": "required",
    "tableStyle": "split",
    "vatPolicy": "excluded"
  }
}

優先順位は、現在のリクエストと PosterBrief、次にセンターのプロフィールデフォルト、その次に欠落している値のみをユーザーに尋ねる検証レスポンスです。VATは決して推測されません。

例

8月会員権価格表ポスター作成

{
  "title": "8월 회원권 이벤트",
  "purpose": "event",
  "brief": {
    "eventName": "8월 회원권 이벤트",
    "programCategories": ["private", "duet"],
    "programSeparation": "table",
    "tablePreference": "required",
    "tableStyle": "comparison",
    "vatPolicy": "excluded"
  },
  "content": {
    "subtitle": "이번 달 특별 혜택",
    "badge": "8월 EVENT",
    "table": {
      "columns": ["상품", "정상가", "이벤트가"],
      "rows": [
        ["1:1 개인레슨 10회", "800,000원", "650,000원"],
        ["듀엣레슨 10회", "500,000원", "390,000원"]
      ],
      "highlightColumn": 2
    },
    "footer": "선착순 마감"
  },
  "style": "premium",
  "render": { "png": true, "pdf": true, "size": "instagram-portrait" }
}

昨年9月のポスターテンプレート再利用

{
  "sourcePosterId": "poster_20250901_ab12cd34",
  "title": "2026년 9월 신규회원 이벤트",
  "brief": {
    "eventName": "9월 신규회원 이벤트",
    "vatPolicy": "excluded"
  },
  "content": {
    "subtitle": "올해 가격으로 업데이트",
    "table": {
      "columns": ["상품", "정상가", "이벤트가"],
      "rows": [["1:1 개인레슨 10회", "820,000원", "670,000원"]],
      "highlightColumn": 2
    }
  }
}

直近1年の記録に基づくスタイル推薦

{
  "purpose": "event",
  "month": 9,
  "recentMonths": 12
}

フィードバック

フィードバックはハードコードではなくJSONファイルに保存されます。create_poster はアクティブなグローバルおよびレイアウトスコープのフィードバックを取得し、結果に appliedFeedback として含めます。

例:

{
  "scope": "table",
  "text": "이벤트가는 정상가보다 확실히 강조."
}

レンダリング

render_poster はJavaScriptを無効にしたPlaywright Chromiumを使用します。対応サイズ:

• instagram-portrait: 1080 x 1350

• instagram-square: 1080 x 1080

• story: 1080 x 1920

• a4-portrait: A4縦向き

HTML/CSSが真実のソースです。PNG/PDFはオプションのレンダリングアーティファクトです。

スケジュールワークスペース

フェーズ2では、ピラティスのグループ/プライベートタイムテーブル用のローカルファーストのスケジュールワークスペースを追加します。これはCRMではありません。プライベートスケジュールには、グリッド表示と運用上の配置のための displayName のみを含めることができます。

コアモデル:

• ScheduleSettings: 週表示、開講/閉講時間、デフォルトのスロット分数、休日オプション、ロケール、国コード

• ScheduleTemplate: 明示保存型の週次グループ/プライベートテンプレート

• ScheduleSlot: Excelセルとは別の中立的なドメインスロット

• ScheduleTemplateMapping: XLSXワークシート/ヘッダー/時刻/曜日列のマッピング

• CenterClosure: センター固有の休館日。国民の祝日とは別

set_schedule_slot はメモリ内のダーティワークスペースを変更します。save_schedule が呼び出されるまで永続化されません。export_schedule はXLSXを書き込み、置き換える前に既存のXLSXをバックアップします。

既存のXLSXファイルは inspect_schedule_file と import_schedule_file で処理されます。インポーターは、ワークシート名、使用範囲、曜日列、時刻列、列幅、行の高さ、および利用可能な場合は結合を取得します。数式は実行されません。

休日処理はプロバイダーベースです。フェーズ2には基本的な韓国休日フィクスチャを備えたローカルプロバイダーが含まれ、ドメインモデルを変更せずに後で外部プロバイダーに置き換えることができます。センターの休館日は祝日より優先されますが、占有スロットは黙って削除されず、警告が返されます。

Railwayは /schedule で、固定ヘッダー、直接セル編集、削除/バックスペース、表示可能な保存状態を備えた軽量なExcelスタイルのワークスペースを提供します。MCPは実際のスケジュール操作のソースであり続けます。

スケジュール例

シナリオA、ファイルが存在しない場合に新しいグループタイムテーブルを作成:

{
  "scheduleType": "group",
  "settings": {
    "weekDisplay": "mon-sat",
    "openingTime": "09:00",
    "closingTime": "21:00",
    "defaultSlotMinutes": 60,
    "autoHolidayMarking": true,
    "locale": "ko-KR",
    "countryCode": "KR"
  }
}

シナリオB、既存のExcelファイルをインポートして翌週を生成:

{ "filePath": "fixtures/group_schedule.xlsx", "scheduleType": "group" }

{
  "scheduleType": "group",
  "weekStart": "2026-10-05",
  "applyHolidays": true,
  "applyCenterClosures": true
}

シナリオC、プライベートスケジュール操作:

{
  "scheduleType": "private",
  "dayOfWeek": "monday",
  "startTime": "19:00",
  "displayName": "김OO"
}

シナリオD、グループスケジュールポスター:

{
  "scheduleType": "group",
  "weekStart": "2026-10-05",
  "title": "9월 그룹레슨 시간표",
  "render": { "png": true, "pdf": true, "size": "instagram-portrait" }
}

セキュリティとプライバシー

アーカイブは生成されたポスターIDを使用し、ファイルアクセス前にポスターIDを検証します。アーカイブ相対インポートは、../ トラバーサルとルートエスケープをブロックするためにチェックされます。生成されたポスターページHTMLは静的で、ユーザーテキストはHTMLエスケープされ、リモートスクリプトはテンプレートの一部ではありません。レンダリングではJavaScriptが無効になります。

フェーズ1では、会員管理、予約、支払い、SMS、Instagram投稿、StudioMate統合、外部デザインスクレイピング、画像生成AI、クラウドDB要件、SaaS認証を除外します。

フェーズ2では、人物関連のスケジュール表示データとして displayName のみを許可します。電話、メール、住所、生年月日、性別、健康状態、病歴、支払い、会員資格、相談、出席プロフィール、マーケティング同意のフィールドは作成しません。名前はプロファイリング、分析、ポスターフィードバック、マーケティング、推薦には使用されません。

フェーズ2でも、StudioMate統合、StudioMateスクレイピング、Chrome拡張機能の自動化、会員CRM、連絡先管理、支払い管理、出席分析、会員嗜好プロファイリング、自動予約確認、SMS、KakaoTalk、Instagram投稿、給与計算、決済、複雑なERP機能を除外します。

拡張ポイント

サービス/リポジトリの分割により、将来のセマンティック検索や別のインデックスの余地が確保されています。外部デザイン参照は、次のようなプロバイダーインターフェースの背後に後で追加できます:

interface DesignReferenceProvider {
  search(query: string): Promise<DesignReference[]>;
}

フェーズ1では、外部テンプレートのスクレイピングやコピーは実装しません。