Skip to main content
Glama

pilates_mcp

pilates_mcp is a local-first MCP server for Pilates center promotional posters. It creates editable HTML/CSS poster sources, stores them in a local archive, searches and reuses past posters, records design feedback, and can render PNG/PDF artifacts with headless Chromium.

Phase 1 deliberately does not store member names, phone numbers, schedules, health data, payment data, or other member personal information.

Project Structure

This repository was empty at implementation time, so the server is implemented as a TypeScript + Node.js MCP server.

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: Jusratio Case File

Install

npm install
npx playwright install chromium

Development

npm run build
npm test
npm run dev

PILATES_MCP_DATA_DIR can point the archive to another local data directory. If unset, the server uses ./data.

Railway Deployment

Railway deployment is configured with railway.json and Dockerfile.

The production container uses the official Playwright image so Chromium runtime dependencies are available for PNG/PDF rendering. Railway starts npm run start:railway, which exposes:

  • GET /health: deployment healthcheck

  • GET /tools: MCP tool summary for deployment inspection

  • GET /schedule: lightweight Excel-style Schedule Workspace

  • GET /mcp: MCP HTTP endpoint info

  • POST /mcp: JSON-RPC MCP endpoint for initialize, tools/list, and tools/call

The stdio MCP server remains available through npm run start:stdio for MCP clients that connect by command. Railway uses npm start and POST /mcp for HTTP JSON-RPC MCP calls.

For persistent local-first archive storage on Railway, mount a Railway volume at /data or set PILATES_MCP_DATA_DIR to another persistent path.

Set these Railway variables for ChatGPT remote MCP OAuth:

  • PILATES_MCP_OAUTH_PASSWORD: owner password shown during /authorize approval

  • PILATES_MCP_PUBLIC_URL: canonical public origin, for example https://your-service.up.railway.app

  • PILATES_MCP_AUTH_DISABLED: optional local-only escape hatch; set to true only for local development

PILATES_MCP_PUBLIC_URL must use the same origin as the MCP URL configured in ChatGPT. For example, if ChatGPT uses https://pilates-mcp.com/mcp, set PILATES_MCP_PUBLIC_URL=https://pilates-mcp.com. Do not mix it with https://mcp.pilates-mcp.com unless that subdomain is the actual MCP URL and all well-known OAuth endpoints are served from that same subdomain.

OAuth endpoints:

  • /.well-known/oauth-protected-resource

  • /.well-known/oauth-protected-resource/mcp

  • /.well-known/oauth-authorization-server

  • /.well-known/openid-configuration

  • /register

  • /authorize

  • /token

If authorization finishes and the browser shows a 502 for a URL like http://127.0.0.1:<port>, that URL is the MCP client's local OAuth callback, not the Railway service. Check that the ChatGPT/Codex client connection flow is still active and that local callback URLs are not blocked by browser, firewall, proxy, or VPN settings.

MCP Client Connection

Use the built server as a stdio MCP command:

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

For HTTP-capable MCP clients, point the client at:

https://<railway-domain>/mcp

Example JSON-RPC call:

curl -X POST https://<railway-domain>/mcp \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

MCP Output Schemas

Every MCP tool publishes an outputSchema through tools/list. This tells ChatGPT and other MCP clients what structured JSON shape to expect before they call a tool.

Tool calls also return structuredContent alongside the human-readable JSON text response. The text response is kept for compatibility, while structuredContent is the preferred machine-readable result for agents. For example, create_poster can return valid: false with missing fields and questions, search_posters returns an items array, and schedule mutation tools return success, conflicts, and saveState.

This matters for this server because many tools are workflow tools, not one-shot generators. The schema helps the agent understand when it must ask for missing poster settings, when explicit schedule save is still required, and how to safely inspect conflicts or render artifact paths.

Tools

Poster tools:

  • 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

Schedule tools:

  • 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

Poster Creation Flow

create_poster reads the center profile, applies center defaults, validates the PosterBrief, gathers relevant feedback, resolves the layout and theme, renders static HTML/CSS, writes metadata/content/source files, and optionally renders PNG/PDF.

The required order is:

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

Required poster brief decisions are validated before generation:

  • eventName

  • programSeparation

  • tablePreference

  • tableStyle when a table is required or provided

  • vatPolicy when price content exists

The server returns valid: false, missing, and Korean questions instead of guessing missing event names, VAT policy, or program separation.

programSeparation and tableStyle are separate decisions. For example, group/private products can use programSeparation: "table" with tableStyle: "split" to render separate GROUP/PRIVATE table blocks. tablePreference represents user intent; layout is the final renderer choice.

Center defaults can reduce repeated questions:

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

Priority is: current request and PosterBrief, then center profile defaults, then a validation response asking the user for only missing values. VAT is never inferred.

Examples

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
}

Feedback

Feedback is stored in JSON files, not hard-coded. create_poster retrieves active global and layout-scoped feedback and includes it in the result as appliedFeedback.

Example:

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

Rendering

render_poster uses Playwright Chromium with JavaScript disabled. Supported sizes:

  • instagram-portrait: 1080 x 1350

  • instagram-square: 1080 x 1080

  • story: 1080 x 1920

  • a4-portrait: A4 portrait

HTML/CSS are the source of truth. PNG/PDF are optional rendered artifacts.

Schedule Workspace

Phase 2 adds a local-first Schedule Workspace for Pilates group/private timetables. It is not a CRM. Private schedules may contain displayName only for grid display and operational placement.

Core model:

  • ScheduleSettings: week display, opening/closing time, default slot minutes, holiday option, locale, country code

  • ScheduleTemplate: explicit-save weekly group/private template

  • ScheduleSlot: neutral domain slot separate from Excel cells

  • ScheduleTemplateMapping: XLSX worksheet/header/time/day-column mapping

  • CenterClosure: center-specific closed dates, separate from national holidays

set_schedule_slot changes an in-memory dirty workspace. It is not persisted until save_schedule is called. export_schedule writes XLSX and backs up an existing XLSX before replacing it.

Existing XLSX files are handled by inspect_schedule_file and import_schedule_file. The importer captures worksheet name, used range, day columns, time column, column widths, row heights, and merges where available. Formulas are not executed.

Holiday handling is provider-based. Phase 2 includes a local provider with basic KR holiday fixtures and can be replaced later by an external provider without changing the domain model. Center closures have priority over public holidays, but occupied slots are not silently deleted; warnings are returned.

Railway serves a lightweight Excel-style workspace at /schedule with sticky headers, direct cell editing, delete/backspace, and visible save state. MCP remains the source of actual schedule operations.

Schedule Examples

Scenario A, create a new group timetable when no file exists:

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

Scenario B, import an existing Excel file and generate next week:

{ "filePath": "fixtures/group_schedule.xlsx", "scheduleType": "group" }
{
  "scheduleType": "group",
  "weekStart": "2026-10-05",
  "applyHolidays": true,
  "applyCenterClosures": true
}

Scenario C, private schedule operation:

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

Scenario D, group schedule poster:

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

Security And Privacy

The archive uses generated poster IDs and validates poster IDs before file access. Archive-relative imports are checked to block ../ traversal and root escape. Generated poster HTML is static, user text is HTML-escaped, and remote scripts are not part of the template. Rendering disables JavaScript.

Phase 1 excludes member management, reservations, payments, SMS, Instagram posting, StudioMate integration, external design scraping, image generation AI, cloud DB requirements, and SaaS authentication.

Phase 2 permits only displayName as person-related schedule display data. It does not create fields for phone, email, address, birth date, gender, health condition, medical history, payment, membership, consultation, attendance profile, or marketing consent. Names are not used for profiling, analytics, poster feedback, marketing, or recommendations.

Phase 2 still excludes StudioMate integration, StudioMate scraping, Chrome extension automation, member CRM, contact management, payment management, attendance analysis, member preference profiling, automatic booking confirmation, SMS, KakaoTalk, Instagram posting, payroll, settlement, and complex ERP features.

Extension Points

The service/repository split keeps room for future semantic search or another index. External design references can be added later behind a provider interface such as:

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

Phase 1 does not implement scraping or copying external templates.

Available Tools

29 tools
add_center_closureA

Add a center-specific closure date. If existing schedule entries are present, returns warnings and requires confirmation semantics without deleting data.

Inputs: date (required), label.

add_design_feedbackB

Store reusable design feedback locally. Scope can be global, table, standard, or a specific poster.

Inputs: text (required), scope (required), active, posterId.

clear_schedule_slotA

Clear a schedule slot in the dirty workspace without saving until save_schedule is called.

Inputs: startTime (required), scheduleType (required), date, dayOfWeek.

create_posterA

Create and archive a new HTML/CSS poster only after required operating and price-display rules are known. Validates PosterBrief first and returns missing questions instead of guessing eventName, VAT policy, table preference, table style, or program separation.

Inputs: title (required), content (required), purpose (required), mood, +11 more.

create_schedule_posterA

Create a Phase 1 poster from public-safe schedule data. Private displayName values are excluded by default.

Inputs: title (required), scheduleType (required), render, weekStart.

create_schedule_templateA

Create a new unsaved weekly group/private schedule template after required settings are known. Does not save until save_schedule is called.

Inputs: scheduleType (required), settings.

export_scheduleA

Export the current schedule to XLSX, preserving mapping metadata where possible and backing up an existing XLSX before writing.

Inputs: scheduleType (required), filename.

find_available_slotsA

Find available schedule slots by schedule type, date/day, time range, and duration.

Inputs: scheduleType (required), date, toTime, duration, +2 more.

generate_weekly_scheduleB

Generate an unsaved weekly schedule from the weekly template plus holidays, center closures, and overrides.

Inputs: weekStart (required), scheduleType (required), applyHolidays, applyCenterClosures.

get_center_closuresB

Return locally stored center-specific closure dates.

Inputs: no named parameters.

get_center_profileA

Return the local Pilates center profile and poster defaults. Use before poster generation.

Inputs: no named parameters.

get_design_feedbackC

Return active local design feedback by scope, poster, or layout so generation can reference it.

Inputs: scope, layout, posterId, activeOnly.

get_posterA

Return one archived poster's metadata, structured content, theme, HTML, CSS, and local archive paths.

Inputs: posterId (required).

get_scheduleB

Return the current dirty draft or saved schedule template.

Inputs: scheduleType (required).

get_schedule_settingsA

Return local non-CRM schedule settings such as week display, opening hours, slot minutes, locale, and holiday marking.

Inputs: no named parameters.

import_posterB

Import existing HTML/CSS into the local archive with metadata. Image-only poster reconstruction is intentionally out of Phase 1 scope.

Inputs: metadata (required), css, html, theme, +3 more.

import_schedule_fileA

Import an existing group/private XLSX schedule into a dirty Schedule Workspace draft while preserving mapping metadata where possible.

Inputs: filePath (required), scheduleType.

inspect_schedule_fileA

Inspect an existing XLSX schedule file inside the workspace and infer worksheet, used range, day columns, time column, merges, widths, and heights without executing formulas.

Inputs: filePath (required).

recommend_poster_styleB

Recommend poster layout/style/table structure from local archive history and saved feedback only. Does not search the internet.

Inputs: month, purpose, recentMonths, programCategories.

remove_center_closureB

Remove a center-specific closure date.

Inputs: date (required).

render_posterB

Render an archived HTML/CSS poster to PNG and/or PDF with headless Chromium. JavaScript is disabled during rendering.

Inputs: posterId (required), pdf, png, size.

reuse_poster_templateB

Copy an existing poster's layout/style/theme into a new poster and replace only the content. Never overwrites the source poster.

Inputs: title (required), content (required), sourcePosterId (required), mood, +11 more.

save_scheduleA

Explicitly save the dirty schedule template and create a revision backup when replacing an existing saved template.

Inputs: scheduleType (required).

search_postersC

Search local archived poster metadata by date, layout, purpose, style, feedback-related tags, free text, VAT policy, and table structure.

Inputs: tag, mood, year, limit, +11 more.

set_schedule_slotB

Set one group/private schedule slot in the dirty workspace. Conflicts are returned unless overwrite is explicitly true. Only displayName is allowed for private names; no CRM fields.

Inputs: startTime (required), scheduleType (required), date, note, +6 more.

update_center_profileA

Update non-member Pilates center profile fields and default poster expression rules such as VAT and table style.

Inputs: name, brand, logoPath, footerText, +3 more.

update_posterA

Update an existing poster source HTML/CSS through structured content/theme fields. Creates a simple revision backup first.

Inputs: posterId (required), mood, notes, style, +4 more.

update_schedule_settingsC

Update center schedule defaults. These are operational settings and must not include member CRM data.

Inputs: locale, closingTime, countryCode, openingTime, +3 more.

validate_scheduleA

Validate duplicate slots, operating hours, holiday conflicts, time ranges, and Excel mapping warnings.

Inputs: scheduleType (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 29 tools

    Disambiguation4/5

    Most tools map to distinct resource-action pairs, and the descriptions generally make boundaries clear. The closest potential confusions are create_schedule_poster vs. create_poster and inspect_schedule_file vs. import_schedule_file, but each has enough distinction to guide selection.

    Naming Consistency5/5

    All tool names consistently follow a snake_case verb_noun pattern, such as get_schedule, update_center_profile, render_poster, and validate_schedule. There are no mixed naming conventions or vague one-word tool names.

    Tool Count2/5

    29 tools is above the comfortable range for a single MCP server and crosses the 'too many' threshold. While the tools are organized into settings, schedule, and poster workflows, the large surface increases selection burden and makes the server feel heavy.

    Completeness4/5

    The tool surface covers center profile settings, schedule import/template/validation/save/export, and poster creation/archive/render/feedback/search comprehensively. Minor lifecycle gaps exist, such as no explicit delete operation for a poster or an entire saved schedule template, but these are workaroundable.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      A local-first open-source MCP server that acts as a personal secretary, memory manager, and automation hub—it syncs Calendar, Gmail, Canvas, GitHub, and Health into a typed temporal memory graph, and enables approval-gated write actions like creating events, drafting/sending mail, and filing issues, all with telegram/slack/CLI interfaces and a SQLite-backed audit trail.
      33
      Apache 2.0