/cc-serverpod:endpoint — 서버 API 창구 자동 생성기

Serverpod endpoint 및 service 클래스 생성

/cc-serverpod:endpoint — 서버 API 창구 자동 생성기#

항목	내용
실행 명령	`/cc-serverpod:endpoint`
분류	워크플로우
난이도	●●○ 보통
MCP 서버	`serena`, `context7`

한마디로#

앱이 서버에 "데이터 좀 줘", "이거 저장해 줘"라고 요청하는 창구(API)를 자동으로 만들어 주는 명령입니다. 식당에 비유하면, 손님(앱) 주문을 받는 주문대와 주방(처리 로직)을 한 번에 차려 주는 도구예요.

누가·언제 쓰나요#

새로운 서버 API 창구가 필요할 때 (예: 배너 목록 불러오기, 책 정보 저장하기)
백엔드에서 실제로 데이터를 처리하는 로직을 짜야 할 때
전체 기능을 한 번에 만드는 /cc-flutter:feature:create 작업의 2번째 단계로 자동 호출될 때

무엇을 해주나요#

기능 폴더 안에 아래 같은 실제 코드 파일들을 만들어 줍니다.

{기능이름}_endpoint.dart — 앱이 쓰는 일반 창구 (로그인한 사용자용)
{기능이름}_console_endpoint.dart — 관리자 콘솔용 창구 (관리자 전용, 선택)
{기능이름}_service.dart — 실제 데이터 처리 로직(주방)
{기능이름}_validator.dart — 입력값 검사 (선택)

목록 조회, 단건 조회, 생성, 수정, 삭제 같은 기본 동작이 들어가고, 권한 체크·에러 기록·삭제 표시(soft delete) 같은 안전장치도 규칙대로 함께 들어갑니다.

어떻게 쓰나요#

# 배너용 창구 만들기 (일반 + 관리자 둘 다)
/cc-serverpod:endpoint banner Banner --type both

# 책용 창구 만들기 (앱용만, 원하는 동작만 골라서)
/cc-serverpod:endpoint books Book --type app
  --methods  " getBooks, getBook, createBook " 

 # 관리자 대시보드 창구 만들기
/cc-serverpod:endpoint dashboard Stats --type console
  --methods  " getOverview, getUserStats, getContentStats "

첫 번째 값(banner)은 기능 이름, 두 번째 값(Banner)은 데이터 이름입니다. (둘 다 필수)
--type 으로 창구 종류를 고릅니다: app(앱용·기본값) / console(관리자용) / both(둘 다).
--methods 로 만들고 싶은 동작만 골라서 지정할 수 있습니다.

안에서 무슨 일이 벌어지나요#

기존 방식 살펴보기 — 이미 만들어진 비슷한 창구 코드를 분석해 같은 스타일을 따릅니다.
창구 코드 만들기 — 앱용 창구와 (필요 시) 관리자용 창구를 정해진 규칙대로 생성합니다.
처리 로직 만들기 — 실제로 데이터를 조회·저장하는 service 코드를 분리해서 만듭니다.
마무리 등록 — 만든 창구를 서버가 인식하도록 코드 생성 명령(melos run backend:pod:generate)을 돌립니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Triggers#

When a new Serverpod API endpoint is needed
When backend business logic implementation is needed
Called in Step 2 of /cc-flutter:feature:create orchestration

Context Trigger Pattern#

/cc-serverpod:endpoint {feature_name} {entity_name} [--options]

Parameters#

Parameter	Required	Description	Example
`feature_name`	✅	Feature module name (snake_case)	`banner`, `books`
`entity_name`	✅	Entity name (PascalCase)	`Banner`, `Book`
`--type`	❌	Endpoint type	`app`, `console`, `both` (default: `app`)
`--methods`	❌	Methods to generate	`"getList, get, create, update, delete"`

Behavioral Flow#

1. Analyze Existing Patterns#

Use Serena MCP to analyze existing endpoint patterns:
- backend/kobic_server/lib/src/feature/banner/endpoint/banners_endpoint.dart
- backend/kobic_server/lib/src/feature/banner/service/banner_service.dart

2. Follow Import Order (Required)#

// 1. Serverpod framework
import 'package:serverpod/server.dart';

// 2. Generated protocol (models)
import 'package:kobic_server/src/generated/protocol.dart';

// 3. Feature internal services
import 'package:kobic_server/src/feature/{feature}/service/{feature}_service.dart';

// 4. Common utilities
import 'package:kobic_server/src/common/authenticated_mixin.dart';

3. Generate Endpoint Classes#

App Endpoint ({feature}_endpoint.dart):

/// {Feature} endpoint
///
/// - Provides list, single, create, update, delete functionality
/// - Accessible only to authenticated users
class {Feature}Endpoint extends Endpoint with AuthenticatedMixin {
  /// Retrieves the {entity} list.
  Future<{Entity}ListResponse> get{Entity}s(
    Session session, {
    int? limit,
    int? offset,
    {Entity}Category? category,
  }) async {
    return {Feature}Service.get{Entity}s(
      session,
      limit: limit ?? 20,
      offset: offset ?? 0,
      category: category,
    );
  }

  /// Creates a {entity}.
  Future<{Entity}> create{Entity}(
    Session session,
    {Entity}CreateRequest request,
  ) async {
    final user = await requireCurrentUserInfo(session);
    return {Feature}Service.create{Entity}(session, request, user.id!);
  }

  // ... remaining CRUD methods
}

Console Endpoint ({feature}_console_endpoint.dart):

/// {Feature} console endpoint (admin only)
class {Feature}ConsoleEndpoint extends Endpoint {
  @override
  bool get requireLogin => true;

  @override
  Set<Scope> get requiredScopes => {Scope.admin};

  /// Retrieves the full {entity} list (admin only).
  Future<List<{Entity}>> getAll{Entity}s(
    Session session, {
    int? limit,
    int? offset,
    bool includeDeleted = false,
  }) async {
    return {Feature}Service.getAll{Entity}sForAdmin(
      session,
      limit: limit,
      offset: offset,
      includeDeleted: includeDeleted,
    );
  }
}

4. Generate Service Class#

/// {Feature} business logic service
class {Feature}Service {
  /// Retrieves the {entity} list.
  static Future<{Entity}ListResponse> get{Entity}s(
    Session session, {
    required int limit,
    required int offset,
    {Entity}Category? category,
  }) async {
    try {
      final entities = await {Entity}.db.find(
        session,
        where: (t) {
          var condition = t.isDeleted.equals(false);
          if (category != null) {
            condition = condition & t.category.equals(category);
          }
          return condition;
        },
        orderBy: (t) => t.createdAt,
        orderDescending: true,
        limit: limit,
        offset: offset,
      );

      final total = await {Entity}.db.count(session, where: ...);

      return {Entity}ListResponse(
        items: entities,
        total: total,
        hasMore: offset + entities.length < total,
      );
    } on Exception catch (error, stackTrace) {
      session.log(
        '{Feature} list query failed: $error',
        exception: error,
        level: LogLevel.error,
        stackTrace: stackTrace,
      );
      rethrow;
    }
  }

  // ... remaining business logic
}

Output Files#

backend/kobic_server/lib/src/feature/{feature_name}/
├── endpoint/
│   ├── {feature_name}_endpoint.dart       # App endpoint
│   └── {feature_name}_console_endpoint.dart  # Console endpoint (optional)
├── service/
│   └── {feature_name}_service.dart        # Business logic
└── validation/
    └── {feature_name}_validator.dart      # Input validation (optional)

Post-Generation Commands#

# Code generation (endpoint registration)
melos run backend:pod:generate

MCP Integration#

Serena: Analyze existing endpoint patterns, symbol search
Context7: Serverpod endpoint documentation reference

Examples#

/cc-serverpod:endpoint banner Banner --type both

Create book endpoint#

/cc-serverpod:endpoint books Book --type app
  --methods  " getBooks, getBook, createBook "

Create admin dashboard endpoint#

/cc-serverpod:endpoint dashboard Stats --type console
  --methods  " getOverview, getUserStats, getContentStats "

Reference Agent#

See ${CLAUDE_PLUGIN_ROOT}/agents/backend/serverpod-endpoint-agent.md for detailed implementation rules

Core Rules Summary#

Follow import order (Serverpod → Protocol → Feature → Utils)
Use AuthenticatedMixin (for authenticated methods)
Set permissions on Console endpoints (requireLogin, requiredScopes)
Separate business logic into Services
Error handling and logging (session.log)
Apply soft delete pattern