🚀 페이로드 CMS 3.0 MCP 서버
📋 개요
Payload CMS 3.0 MCP 서버는 Payload CMS 개발 경험을 향상시키도록 설계된 특수 모델 컨텍스트 프로토콜(MCP) 서버입니다. 모범 사례를 따르는 코드 검증, 템플릿 생성 및 프로젝트 스캐폴딩 기능을 제공하여 개발자가 더 나은 Payload CMS 애플리케이션을 구축할 수 있도록 지원합니다.
✨ 특징
🔧 페이로드 CMS 3.0 기능
검증 도구
validate - 컬렉션, 필드, 전역 및 구성에 대한 코드 검증query - 쿼리 검증 규칙 및 모범 사례mcp_query - 페이로드 CMS 구조에 대한 SQL 유사 쿼리 실행
코드 생성
generate_template - 다양한 구성 요소에 대한 코드 템플릿 생성generate_collection - 완전한 컬렉션 정의 생성generate_field - 적절한 입력으로 필드 정의 생성
프로젝트 설정
scaffold_project - 전체 Payload CMS 프로젝트 구조 생성validate_scaffold_options - 스캐폴드 옵션이 모범 사례를 따르는지 확인합니다(scaffold_project에서 내부적으로 사용).
📝 자세한 도구 참조
검증 도구
validate
구문과 모범 사례에 대해 Payload CMS 코드를 검증합니다.
매개변수:
code (문자열): 검증할 코드fileType (enum): 파일 유형 - "collection", "field", "global" 또는 "config"
예시 프롬프트:
지엑스피1
query
Payload CMS에 대한 쿼리 검증 규칙과 모범 사례입니다.
매개변수:
query (문자열): 쿼리 문자열fileType (선택적 열거형): 파일 유형 - "collection", "field", "global" 또는 "config"
예시 프롬프트:
What are the best practices for implementing access control in Payload CMS collections?
mcp_query
Payload CMS 구조에 대해 SQL과 유사한 쿼리를 실행합니다.
매개변수:
sql (문자열): SQL과 유사한 쿼리 문자열
예시 프롬프트:
Can you execute this query to find all valid field types in Payload CMS?
SELECT field_types FROM payload_schema WHERE version = '3.0'
코드 생성
generate_template
다양한 Payload CMS 구성 요소에 대한 코드 템플릿을 생성합니다.
매개변수:
templateType (enum): 템플릿 유형 - "collection", "field", "global", "config", "access-control", "hook", "endpoint", "plugin", "block", "migration"options (레코드): 템플릿에 대한 구성 옵션
예시 프롬프트:
Generate a template for a Payload CMS hook that logs when a document is created.
generate_collection
완전한 페이로드 CMS 컬렉션 정의를 생성합니다.
매개변수:
slug (문자열): 컬렉션 슬러그fields (선택적 배열): 필드 객체의 배열auth (선택적 부울): 이것이 인증 컬렉션인지 여부timestamps (선택적 boolean): 타임스탬프를 포함할지 여부admin (선택적 객체): 관리자 패널 구성hooks (선택적 부울): 후크를 포함할지 여부access (선택적 부울): 액세스 제어를 포함할지 여부versions (선택적 부울): 버전 관리를 활성화할지 여부
예시 프롬프트:
Generate a Payload CMS collection for a blog with title, content, author, and published date fields. Include timestamps and versioning.
generate_field
페이로드 CMS 필드 정의를 생성합니다.
매개변수:
name (문자열): 필드 이름type (문자열): 필드 유형required (선택적 부울): 필드가 필수인지 여부unique (선택적 부울): 필드가 고유해야 하는지 여부localized (선택적 부울): 필드를 지역화해야 하는지 여부access (선택적 부울): 액세스 제어를 포함할지 여부admin (선택적 객체): 관리자 패널 구성validation (선택적 부울): 유효성 검사를 포함할지 여부defaultValue (선택 사항): 필드의 기본값
예시 프롬프트:
Generate a Payload CMS image field with validation that requires alt text and has a description in the admin panel.
프로젝트 설정
scaffold_project
완전한 페이로드 CMS 프로젝트 구조를 구축합니다.
매개변수:
projectName (문자열): 프로젝트 이름description (선택 문자열): 프로젝트 설명serverUrl (선택 문자열): 서버 URLdatabase (선택적 열거형): 데이터베이스 유형 - "mongodb" 또는 "postgres"auth (선택적 부울): 인증을 포함할지 여부admin (선택적 객체): 관리자 패널 구성collections (선택적 배열): 컬렉션 객체의 배열globals (선택적 배열): 전역 객체의 배열blocks (선택적 배열): 블록 객체의 배열plugins (선택적 배열): 플러그인 문자열 배열typescript (선택적 부울): TypeScript를 사용할지 여부
예시 프롬프트:
Scaffold a Payload CMS project called "blog-platform" with MongoDB, authentication, and collections for posts, categories, and users. Include a global for site settings.
🚀 시작하기
1. 필수 조건
시작하기 전에 다음 사항이 있는지 확인하세요.
2. 커서 구성
커서 IDE와 함께 사용하려면:
- 커서 설정 열기
- MCP 서버 섹션으로 이동
- 새로운 MCP 서버 추가
- "Payload CMS 3.0 MCP"라고 이름을 지정하세요.
- 전송 유형을 "명령"으로 설정하세요
- 명령을 다음으로 설정하세요:
railway run --service=YOUR_SERVICE_ID - 구성을 저장합니다
3. MCP 서버 사용
구성이 완료되면 AI 프롬프트에서 다음 도구를 사용할 수 있습니다.
- 코드 검증: "이 페이로드 CMS 수집 코드를 검증하세요"
- 템플릿 생성: "미디어 컬렉션에 대한 템플릿 생성"
- 쿼리 규칙: "액세스 제어를 위한 쿼리 검증 규칙"
- SQL 유사 쿼리: "컬렉션의 필드 유형을 찾기 위한 쿼리 실행"
4. 워크플로 예시
Payload CMS MCP 서버를 사용한 일반적인 워크플로:
- 특정 필드가 있는 컬렉션 템플릿 생성
- 생성된 코드를 모범 사례에 맞게 검증합니다.
- 코드 개선을 위한 특정 검증 규칙에 대한 쿼리
- 후크나 엔드포인트와 같은 추가 구성 요소를 생성합니다.
- 준비가 되면 완전한 프로젝트 구조를 구축하세요
5. 전체 워크플로우 예시
대화에서 MCP 서버를 사용하는 방법에 대한 전체적인 예는 다음과 같습니다.
User: I need to create a Payload CMS collection for a product catalog.
AI: I'll help you create a product catalog collection. Let me generate a template for you.
[Uses generate_collection tool]
Here's a collection template for your product catalog:
```typescript
import { CollectionConfig } from 'payload/types';
export const Products: CollectionConfig = {
slug: 'products',
admin: {
useAsTitle: 'name',
defaultColumns: ['name', 'price', 'category', 'inStock'],
group: 'Shop',
},
access: {
read: () => true,
},
fields: [
{
name: 'name',
type: 'text',
required: true,
},
{
name: 'description',
type: 'richText',
},
{
name: 'price',
type: 'number',
required: true,
},
{
name: 'category',
type: 'relationship',
relationTo: 'categories',
required: true,
},
{
name: 'images',
type: 'array',
fields: [
{
name: 'image',
type: 'upload',
relationTo: 'media',
required: true,
},
{
name: 'altText',
type: 'text',
required: true,
}
]
},
{
name: 'inStock',
type: 'checkbox',
defaultValue: true,
},
],
timestamps: true,
}
사용자: 이 코드가 모범 사례를 따르는지 검증해 주실 수 있나요?
AI: 제가 코드를 검증해 드릴게요.
[검증 도구 사용]
유효성 검사 결과 코드가 유효하며 모범 사례를 준수하는 것으로 나타났습니다. 다음은 몇 가지 제안 사항입니다.
- 심층적인 쿼리를 방지하려면 카테고리 관계 필드에 maxDepth를 추가하는 것을 고려하세요.
- 생성, 업데이트 및 삭제 작업에 대한 액세스 제어를 추가할 수 있습니다.
- 제품이 업데이트되면 재고 관리를 위한 후크를 추가하는 것을 고려하세요.
사용자: Payload CMS에서 액세스 제어를 위한 모범 사례는 무엇입니까?
AI: 액세스 제어에 대한 검증 규칙을 쿼리해보겠습니다.
[쿼리 도구 사용]
Payload CMS에서 액세스 제어를 위한 모범 사례는 다음과 같습니다.
- 생성, 읽기, 업데이트 및 삭제 작업에 대해 항상 명시적 액세스 제어 기능을 정의합니다.
- 관리자 사용자에 대한 역할 기반 액세스 제어 사용
- 민감한 데이터에 대한 필드 수준 액세스 제어 구현
- 광범위한 권한에 대해 컬렉션 수준 액세스 제어를 사용하세요.
- 복잡한 논리에 대해 액세스 제어와 함께 후크 사용을 고려하세요.
사용자: 이제 이 제품 컬렉션과 카테고리 컬렉션을 사용하여 완전한 프로젝트를 구축해야 합니다.
AI: 당신을 위해 완전한 프로젝트를 설계해 드리겠습니다.
[scaffold_project 도구 사용]
다음을 사용하여 완전한 Payload CMS 프로젝트 구조를 생성했습니다.
- 귀하가 지정한 대로 제품 컬렉션
- 이름 및 설명 필드가 있는 카테고리 컬렉션
- 제품 이미지용 미디어 컬렉션
- 관리자 사용자에 대한 인증
- TypeScript 구성
- MongoDB 데이터베이스 설정
- 필요한 모든 파일 및 구성
npm install 과 npm run dev 로 프로젝트를 초기화할 준비가 되었습니다.
📋 스캐폴딩 예시 및 자세한 프롬프트
프로젝트 스캐폴딩 예시
MCP 서버를 사용하여 프로젝트를 스캐폴딩하면 완전한 프로젝트 구조를 얻게 됩니다. 스캐폴딩된 전자상거래 프로젝트는 다음과 같습니다.
e-commerce-platform/
├── .env
├── .eslintrc.js
├── .gitignore
├── README.md
├── package.json
├── tsconfig.json
├── src/
│ ├── payload.config.ts
│ ├── server.ts
│ ├── collections/
│ │ ├── Products.ts
│ │ ├── Categories.ts
│ │ ├── Orders.ts
│ │ ├── Customers.ts
│ │ ├── Media.ts
│ │ └── Users.ts
│ ├── globals/
│ │ ├── Settings.ts
│ │ └── Footer.ts
│ ├── blocks/
│ │ ├── Hero.ts
│ │ ├── ProductGrid.ts
│ │ └── CallToAction.ts
│ ├── fields/
│ │ ├── richText/
│ │ ├── metaImage.ts
│ │ └── slug.ts
│ ├── hooks/
│ │ ├── beforeChange.ts
│ │ └── afterChange.ts
│ ├── access/
│ │ ├── isAdmin.ts
│ │ └── isAdminOrSelf.ts
│ └── utilities/
│ ├── formatSlug.ts
│ └── sendEmail.ts
예시 스캐폴드 프로젝트 프롬프트(기본)
Scaffold a Payload CMS project for a blog platform with the following:
- Project name: blog-platform
- Database: MongoDB
- Authentication: Yes
- Collections: Posts, Categories, Authors, Media
- Globals: SiteSettings
- TypeScript: Yes
예시 스캐폴드 프로젝트 프롬프트(상세)
Scaffold a comprehensive Payload CMS project for an e-commerce platform with the following specifications:
Project details:
- Name: luxury-watches-store
- Description: "An e-commerce platform for luxury watches"
- Database: PostgreSQL
- TypeScript: Yes
Collections needed:
1. Products collection with:
- Name (text, required)
- Description (rich text)
- Price (number, required)
- SKU (text, unique)
- Brand (relationship to Brands collection)
- Categories (relationship to Categories, multiple)
- Features (array of text fields)
- Specifications (array of key-value pairs)
- Images (array of media uploads with alt text)
- Stock quantity (number)
- Status (select: available, out of stock, discontinued)
2. Categories collection with:
- Name (text, required)
- Description (rich text)
- Parent category (self-relationship)
- Image (media upload)
3. Brands collection with:
- Name (text, required)
- Logo (media upload)
- Description (rich text)
- Founded year (number)
- Country of origin (text)
4. Orders collection with:
- Order number (text, generated)
- Customer (relationship to Users)
- Products (array of relationships to Products with quantity)
- Status (select: pending, processing, shipped, delivered, cancelled)
- Shipping address (group of fields)
- Billing address (group of fields)
- Payment method (select)
- Total amount (number, calculated)
- Notes (text)
5. Users collection (auth enabled) with:
- Email (email, required)
- Name (text, required)
- Shipping addresses (array of address groups)
- Order history (relationship to Orders)
- Wishlist (relationship to Products)
- Role (select: customer, admin)
Globals:
1. SiteSettings with:
- Site name
- Logo
- Contact information
- Social media links
- SEO defaults
2. ShippingMethods with:
- Array of shipping options with prices
Include access control for:
- Admin-only access to manage products, categories, brands
- Customer access to their own orders and profile
- Public read access to products and categories
Add hooks for:
- Updating stock when orders are placed
- Generating order numbers
- Sending email notifications on order status changes
예제 컬렉션 생성 프롬프트(기본)
Generate a Payload CMS collection for blog posts with title, content, author, and published date fields.
컬렉션 생성 프롬프트 예시(상세)
Generate a Payload CMS collection for a real estate property listing with the following specifications:
Collection name: Properties
Admin configuration:
- Use "title" as the display field
- Group under "Listings" in the admin panel
- Default columns: title, price, location, status, createdAt
Fields:
1. Title (text, required)
2. Slug (text, unique, generated from title)
3. Description (rich text with basic formatting options)
4. Price (number, required)
5. Location (group) with:
- Address (text)
- City (text, required)
- State/Province (text, required)
- Postal code (text)
- Country (select from predefined list)
- Coordinates (point) for map display
6. Property details (group) with:
- Property type (select: house, apartment, condo, land, commercial)
- Bedrooms (number)
- Bathrooms (number)
- Square footage (number)
- Lot size (number)
- Year built (number)
- Parking spaces (number)
7. Features (array of checkboxes) including:
- Air conditioning
- Swimming pool
- Garden
- Garage
- Fireplace
- Security system
- Elevator
- Furnished
8. Images (array of media uploads with alt text and caption)
9. Documents (array of file uploads for floor plans, certificates, etc.)
10. Status (select: available, under contract, sold, off market)
11. Featured (checkbox to highlight on homepage)
12. Agent (relationship to Users collection, required)
13. Related properties (relationship to self, multiple)
Access control:
- Public read access
- Agent can create and edit their own listings
- Admin can manage all listings
Hooks:
- Before change: Format slug from title
- After change: Notify agent of status changes
Versioning: Enabled
Timestamps: Enabled
프롬프트의 세부 수준
MCP 서버는 다양한 수준의 세부 정보를 포함하는 프롬프트를 처리할 수 있습니다.
최소한의 세부 정보(AI가 빈틈을 메웁니다)
Generate a collection for blog posts.
중간 세부 사항(특정 요구 사항)
Generate a collection for blog posts with title, content, featured image, categories, and author fields. Make title and content required.
하이 디테일(완전한 사양)
Generate a collection for blog posts with:
- Slug: posts
- Fields:
- Title (text, required)
- Content (rich text with custom formatting options)
- Featured image (upload with alt text)
- Categories (relationship to categories collection, multiple)
- Author (relationship to users collection)
- Status (select: draft, published, archived)
- Published date (date)
- SEO (group with title, description, and keywords)
- Admin configuration:
- Use title as display field
- Group under "Content"
- Default columns: title, author, status, publishedDate
- Access control for different user roles
- Hooks for slug generation and notification
- Enable versioning and timestamps
효과적인 프롬프트를 위한 팁
- 요구사항을 구체적으로 명시하세요 . 자세한 내용을 제공할수록 더욱 맞춤화된 결과물이 나옵니다.
- 관계 지정 : 컬렉션이 서로 어떻게 관련되어 있는지 명확하게 나타냅니다.
- 검증 요구 사항 포함 : 필드에 대한 검증 규칙이나 제약 조건을 언급합니다.
- 관리자 UI 기본 설정 설명 : 관리자 패널에 컬렉션이 표시되는 방식을 지정합니다.
- 후크와 액세스 제어 언급 : 특정 비즈니스 로직이나 보안 규칙이 필요한 경우 프롬프트에 포함하세요.
- 도메인별 용어 사용 : 업계나 사용 사례와 관련된 용어를 사용하여 프로젝트를 설명하세요.
📄 라이센스
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.
🌍 MATMAX WORLDWIDE 소개
우리는 기술이 선한 목적을 이룬다고 믿습니다. 인간성을 존중하면서 우리 삶을 향상시키는 도구입니다.
기술이 웰빙, 연결, 그리고 삶의 목적을 실현하는 미래를 함께 만들어 갑시다. 함께라면 우리 모두의 잠재력을 최대한 발휘할 수 있는 디지털 경험을 만들어낼 수 있습니다.
matmax.world를 방문하여 인간 중심 기술에 대한 당사의 비전에 대해 자세히 알아보세요.
🖥️ 지역적으로 운영
npm을 사용하여 Payload CMS MCP 서버를 로컬로 실행할 수 있습니다.
옵션 1: npm에서 설치
# Install globally
npm install -g payload-cms-mcp
# Run the server
payload-cms-mcp
옵션 2: 저장소 복제
- 저장소를 복제합니다.
git clone https://github.com/Matmax-Worldwide/payloadcmsmcp.git
cd payloadcmsmcp
- 종속성 설치:
- 서버를 로컬로 실행합니다.
또는 대안적으로:
이제 MCP 서버는 로컬에서 실행되며 Railway API 토큰이 없어도 개발 및 테스트를 위해 액세스할 수 있습니다.
🚀 배포 옵션
철도에 배치(권장)
MCP 서버를 배포하는 가장 쉬운 방법은 Railway의 원클릭 배포를 사용하는 것입니다.
버튼을 클릭한 후:
- "GitHub 저장소에서 배포"를 선택하세요
- "Matmax-Worldwide/payloadcmsmcp"를 검색하세요
- "지금 배포"를 클릭하세요
빠른 커서 IDE 설정
배치 후:
- 철도 CLI 설치:
npm install -g @railway/cli - 철도 로그인:
railway login - 프로젝트 링크:
railway link - 커서 설정 > MCP 서버에서 명령을
railway run 으로 설정합니다.