@mandujs/mcp 0.9.19 → 0.9.21

package/src/resources/skills/mandu-deployment/rules/deploy-platform-vercel.md

@@ -0,0 +1,140 @@
+---
+title: Deploy to Vercel
+impact: MEDIUM
+impactDescription: Serverless deployment with edge functions
+tags: deployment, vercel, serverless, edge
+---
+
+## Deploy to Vercel
+
+**Impact: MEDIUM (Serverless deployment with edge functions)**
+
+Vercel을 사용하여 Mandu 앱을 서버리스로 배포하세요.
+
+**vercel.json 설정:**
+
+```json
+{
+  "buildCommand": "bun run build",
+  "outputDirectory": "dist",
+  "framework": null,
+  "functions": {
+    "api/**/*.ts": {
+      "runtime": "nodejs20.x",
+      "memory": 1024,
+      "maxDuration": 10
+    }
+  },
+  "rewrites": [
+    { "source": "/api/(.*)", "destination": "/api/$1" },
+    { "source": "/(.*)", "destination": "/index.html" }
+  ]
+}
+```
+
+**주의사항:**
+Vercel은 Bun 런타임을 직접 지원하지 않으므로, Node.js 호환 모드로 빌드해야 합니다.
+
+**Node.js 호환 빌드:**
+
+```typescript
+// scripts/build-vercel.ts
+await Bun.build({
+  entrypoints: ["./src/server.ts"],
+  outdir: "./dist",
+  target: "node",  // Node.js 타겟으로 빌드
+  minify: true,
+  external: ["@vercel/node"],
+});
+```
+
+## API Routes 변환
+
+```typescript
+// api/users/index.ts (Vercel Serverless Function)
+import type { VercelRequest, VercelResponse } from "@vercel/node";
+import { createHandler } from "@mandujs/vercel";
+import usersSlot from "../../app/users/slot";
+
+export default createHandler(usersSlot);
+```
+
+**createHandler 구현:**
+
+```typescript
+// lib/vercel.ts
+import type { VercelRequest, VercelResponse } from "@vercel/node";
+
+export function createHandler(slot: Slot) {
+  return async (req: VercelRequest, res: VercelResponse) => {
+    const method = req.method?.toLowerCase() || "get";
+    const handler = slot.handlers[method];
+
+    if (!handler) {
+      return res.status(405).json({ error: "Method not allowed" });
+    }
+
+    const ctx = createContext(req);
+    const result = await handler(ctx);
+
+    return res.status(result.status || 200).json(result.body);
+  };
+}
+```
+
+## Edge Functions
+
+```typescript
+// api/geo.ts
+export const config = {
+  runtime: "edge",
+};
+
+export default async function handler(request: Request) {
+  const geo = request.headers.get("x-vercel-ip-country");
+
+  return new Response(JSON.stringify({ country: geo }), {
+    headers: { "Content-Type": "application/json" },
+  });
+}
+```
+
+## 환경 변수
+
+```bash
+# Vercel CLI로 환경 변수 설정
+vercel env add DATABASE_URL production
+vercel env add SESSION_SECRET production
+
+# .env.local (로컬 개발)
+DATABASE_URL=postgresql://localhost:5432/mandu
+SESSION_SECRET=dev-secret
+```
+
+## 배포
+
+```bash
+# Vercel CLI 설치
+npm install -g vercel
+
+# 프로젝트 연결
+vercel link
+
+# Preview 배포
+vercel
+
+# Production 배포
+vercel --prod
+```
+
+## 추천 사용 케이스
+
+- 정적 사이트 + API routes
+- Edge에서 가벼운 처리가 필요한 경우
+- Vercel의 다른 서비스(Analytics, Speed Insights)와 통합
+
+**비추천:**
+- 장시간 실행 프로세스 (WebSocket, 스트리밍)
+- Bun 특화 기능 필요 시
+
+Reference: [Vercel Documentation](https://vercel.com/docs)

package/src/resources/skills/mandu-fs-routes/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: mandu-fs-routes
+description: |
+  File-system based routing for Mandu. Use when creating pages, API routes,
+  layouts, or dynamic routes. Triggers on tasks involving app/ folder,
+  page.tsx, route.ts, layout.tsx, [id], [...slug], or URL patterns.
+license: MIT
+metadata:
+  author: mandu
+  version: "1.0.0"
+---
+
+# Mandu FS Routes
+
+FS Routes는 파일 시스템 기반 라우팅입니다. `app/` 폴더의 파일 구조가 URL이 됩니다.
+
+## When to Apply
+
+Reference these guidelines when:
+- Creating new pages or API endpoints
+- Setting up dynamic routes with parameters
+- Implementing shared layouts
+- Organizing route groups
+- Working with catch-all routes
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | File Naming | CRITICAL | `routes-naming-` |
+| 2 | Page Routes | HIGH | `routes-page-` |
+| 3 | API Routes | HIGH | `routes-api-` |
+| 4 | Dynamic Routes | MEDIUM | `routes-dynamic-` |
+| 5 | Layouts | MEDIUM | `routes-layout-` |
+
+## Quick Reference
+
+### 1. File Naming (CRITICAL)
+
+- `routes-naming-page` - Use page.tsx for page components
+- `routes-naming-route` - Use route.ts for API handlers
+- `routes-naming-layout` - Use layout.tsx for shared layouts
+
+### 2. Page Routes (HIGH)
+
+- `routes-page-component` - Export default function component
+- `routes-page-metadata` - Export metadata object for SEO
+
+### 3. API Routes (HIGH)
+
+- `routes-api-methods` - Export GET, POST, PUT, DELETE functions
+- `routes-api-request` - Access Request object as first parameter
+
+### 4. Dynamic Routes (MEDIUM)
+
+- `routes-dynamic-param` - Use [id] for single parameter
+- `routes-dynamic-catchall` - Use [...slug] for catch-all
+- `routes-dynamic-optional` - Use [[...slug]] for optional catch-all
+
+### 5. Layouts (MEDIUM)
+
+- `routes-layout-wrapper` - Layouts wrap all child pages
+- `routes-layout-nesting` - Layouts can be nested
+
+## URL Mapping
+
+| File Path | URL |
+|-----------|-----|
+| `app/page.tsx` | `/` |
+| `app/about/page.tsx` | `/about` |
+| `app/users/[id]/page.tsx` | `/users/:id` |
+| `app/api/users/route.ts` | `/api/users` |
+| `app/(auth)/login/page.tsx` | `/login` |
+
+## How to Use
+
+Read individual rule files for detailed explanations:
+
+```
+rules/routes-naming-page.md
+rules/routes-dynamic-param.md
+```

package/src/resources/skills/mandu-fs-routes/metadata.json

@@ -0,0 +1,12 @@
+{
+  "version": "1.0.0",
+  "organization": "Mandu Framework",
+  "date": "February 2026",
+  "abstract": "파일 시스템 기반 라우팅 가이드. app/ 폴더 구조가 URL이 되는 규칙, 동적 라우트 [id], catch-all [...slug], 라우트 그룹 (group), 특수 파일 (page.tsx, route.ts, layout.tsx) 사용법을 다룹니다.",
+  "references": [
+    "https://nextjs.org/docs/app/building-your-application/routing",
+    "https://fresh.deno.dev/docs/concepts/routing",
+    "https://kit.svelte.dev/docs/routing"
+  ],
+  "tags": ["routes", "filesystem", "pages", "api", "mandu"]
+}

package/src/resources/skills/mandu-fs-routes/rules/_sections.md

@@ -0,0 +1,36 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. File Naming (routes-naming)
+
+**Impact:** CRITICAL
+**Description:** page.tsx, route.ts, layout.tsx 등 특수 파일 명명 규칙. 잘못된 파일명은 라우트로 인식되지 않습니다.
+
+## 2. Page Routes (routes-page)
+
+**Impact:** HIGH
+**Description:** page.tsx 컴포넌트 작성법. default export, metadata, props 접근 패턴을 다룹니다.
+
+## 3. API Routes (routes-api)
+
+**Impact:** HIGH
+**Description:** route.ts에서 HTTP 메서드 함수 export. GET, POST, PUT, DELETE 핸들러 작성법입니다.
+
+## 4. Dynamic Routes (routes-dynamic)
+
+**Impact:** MEDIUM
+**Description:** [id], [...slug], [[...slug]] 동적 세그먼트. URL 파라미터 캡처와 접근 방법을 다룹니다.
+
+## 5. Layouts (routes-layout)
+
+**Impact:** MEDIUM
+**Description:** layout.tsx로 페이지 감싸기. 중첩 레이아웃과 공유 UI 패턴입니다.
+
+## 6. Route Groups (routes-group)
+
+**Impact:** LOW
+**Description:** (group) 괄호로 URL에 영향 없이 폴더 구조 정리. 코드 구성에만 사용됩니다.

package/src/resources/skills/mandu-fs-routes/rules/_template.md

@@ -0,0 +1,69 @@
+# Rule Template
+
+Use this template when creating new rules for mandu-fs-routes.
+
+---
+
+```markdown
+---
+title: Rule Title Here
+impact: CRITICAL | HIGH | MEDIUM | LOW
+impactDescription: 영향 설명
+tags: routes, tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: {LEVEL} ({impactDescription})**
+
+규칙의 목적과 중요성을 설명합니다.
+
+**Incorrect (문제점 설명):**
+
+\`\`\`
+app/
+├── about/
+│   └── About.tsx      ❌ 인식되지 않음
+└── users/
+    └── index.tsx      ❌ 인식되지 않음
+\`\`\`
+
+**Correct (올바른 구조):**
+
+\`\`\`
+app/
+├── about/
+│   └── page.tsx       ✅ → /about
+└── users/
+    └── page.tsx       ✅ → /users
+\`\`\`
+
+## Code Example
+
+\`\`\`tsx
+// app/about/page.tsx
+
+export default function AboutPage() {
+  return <h1>About Us</h1>;
+}
+\`\`\`
+
+Reference: [관련 문서 링크](https://example.com)
+```
+
+---
+
+## Naming Convention
+
+- 파일명: `{section}-{rule-name}.md`
+- 예시: `routes-naming-page.md`, `routes-dynamic-param.md`
+
+## URL Mapping Quick Reference
+
+| File Path | URL |
+|-----------|-----|
+| `app/page.tsx` | `/` |
+| `app/about/page.tsx` | `/about` |
+| `app/users/[id]/page.tsx` | `/users/:id` |
+| `app/api/users/route.ts` | `/api/users` |
+| `app/(auth)/login/page.tsx` | `/login` |

package/src/resources/skills/mandu-fs-routes/rules/routes-api-methods.md

@@ -0,0 +1,65 @@
+---
+title: Export HTTP Method Functions for API Routes
+impact: HIGH
+impactDescription: RESTful API structure
+tags: routes, api, methods
+---
+
+## Export HTTP Method Functions for API Routes
+
+API routes use named exports for each HTTP method: GET, POST, PUT, PATCH, DELETE.
+
+**Incorrect (default export handler):**
+
+```typescript
+// app/api/users/route.ts
+export default function handler(req: Request) {
+  if (req.method === "GET") {
+    return Response.json({ users: [] });
+  }
+}
+```
+
+**Correct (named method exports):**
+
+```typescript
+// app/api/users/route.ts
+
+export function GET() {
+  return Response.json({ users: [] });
+}
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  return Response.json({ created: body }, { status: 201 });
+}
+
+export function DELETE() {
+  return new Response(null, { status: 204 });
+}
+```
+
+## Supported Methods
+
+```typescript
+export function GET(request: Request) { }
+export function POST(request: Request) { }
+export function PUT(request: Request) { }
+export function PATCH(request: Request) { }
+export function DELETE(request: Request) { }
+export function HEAD(request: Request) { }
+export function OPTIONS(request: Request) { }
+```
+
+## With Dynamic Parameters
+
+```typescript
+// app/api/users/[id]/route.ts
+
+export function GET(
+  request: Request,
+  { params }: { params: { id: string } }
+) {
+  return Response.json({ userId: params.id });
+}
+```

package/src/resources/skills/mandu-fs-routes/rules/routes-dynamic-param.md

@@ -0,0 +1,93 @@
+---
+title: Use [param] for Dynamic Route Parameters
+impact: MEDIUM
+impactDescription: Enables dynamic URLs
+tags: routes, dynamic, params
+---
+
+## Use [param] for Dynamic Route Parameters
+
+Wrap folder name in brackets to create dynamic routes that capture URL segments.
+
+**Incorrect (hardcoded routes):**
+
+```
+app/users/
+├── user1/page.tsx
+├── user2/page.tsx
+└── user3/page.tsx
+```
+
+**Correct (dynamic parameter):**
+
+```
+app/users/
+└── [id]/
+    └── page.tsx    → /users/:id
+```
+
+## Accessing Parameters
+
+### In Page Components
+
+```tsx
+// app/users/[id]/page.tsx
+
+interface Props {
+  params: { id: string };
+}
+
+export default function UserPage({ params }: Props) {
+  return <h1>User ID: {params.id}</h1>;
+}
+```
+
+### In API Routes
+
+```typescript
+// app/api/users/[id]/route.ts
+
+export function GET(
+  request: Request,
+  { params }: { params: { id: string } }
+) {
+  return Response.json({ userId: params.id });
+}
+```
+
+## Multiple Parameters
+
+```
+app/posts/[postId]/comments/[commentId]/page.tsx
+→ /posts/:postId/comments/:commentId
+```
+
+```tsx
+interface Props {
+  params: { postId: string; commentId: string };
+}
+
+export default function CommentPage({ params }: Props) {
+  return (
+    <div>
+      Post: {params.postId}, Comment: {params.commentId}
+    </div>
+  );
+}
+```
+
+## Catch-All Routes
+
+```
+app/docs/[...slug]/page.tsx → /docs/a, /docs/a/b, /docs/a/b/c
+```
+
+```tsx
+interface Props {
+  params: { slug: string[] };
+}
+
+export default function DocsPage({ params }: Props) {
+  return <p>Path: {params.slug.join("/")}</p>;
+}
+```

package/src/resources/skills/mandu-fs-routes/rules/routes-naming-page.md

@@ -0,0 +1,55 @@
+---
+title: Use page.tsx for Page Components
+impact: CRITICAL
+impactDescription: Required for routing to work
+tags: routes, page, naming
+---
+
+## Use page.tsx for Page Components
+
+Page components must be named `page.tsx`. This is how Mandu recognizes
+which files should become routes.
+
+**Incorrect (wrong filename):**
+
+```
+app/
+├── about/
+│   └── About.tsx      ❌ Won't be recognized
+└── users/
+    └── index.tsx      ❌ Won't be recognized
+```
+
+**Correct (page.tsx):**
+
+```
+app/
+├── about/
+│   └── page.tsx       ✅ → /about
+└── users/
+    └── page.tsx       ✅ → /users
+```
+
+## Page Component Structure
+
+```tsx
+// app/about/page.tsx
+
+export default function AboutPage() {
+  return (
+    <div>
+      <h1>About Us</h1>
+    </div>
+  );
+}
+```
+
+## Special Files
+
+| File | Purpose |
+|------|---------|
+| `page.tsx` | Page component |
+| `layout.tsx` | Shared layout |
+| `loading.tsx` | Loading UI |
+| `error.tsx` | Error boundary |
+| `route.ts` | API handler |

package/src/resources/skills/mandu-guard/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: mandu-guard
+description: |
+  Architecture guard system for Mandu. Use when checking layer dependencies,
+  enforcing architecture rules, or validating file locations. Triggers on
+  tasks involving architecture, layers, dependencies, or guard commands.
+license: MIT
+metadata:
+  author: mandu
+  version: "1.0.0"
+---
+
+# Mandu Guard
+
+Mandu Guard는 아키텍처 규칙을 강제하는 시스템입니다.
+레이어 간 의존성을 검사하고 위반을 실시간으로 감지합니다.
+
+## When to Apply
+
+Reference these guidelines when:
+- Setting up architecture rules
+- Checking layer dependencies
+- Validating import paths
+- Running architecture checks in CI
+- Configuring guard presets
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Layer Rules | CRITICAL | `guard-layer-` |
+| 2 | Presets | HIGH | `guard-preset-` |
+| 3 | Validation | HIGH | `guard-validate-` |
+| 4 | Configuration | MEDIUM | `guard-config-` |
+
+## Quick Reference
+
+### 1. Layer Rules (CRITICAL)
+
+- `guard-layer-direction` - Dependencies flow downward only
+- `guard-layer-violation` - Detect and fix layer violations
+- `guard-layer-same-level` - Restrict same-layer imports
+
+### 2. Presets (HIGH)
+
+- `guard-preset-mandu` - FSD + Clean hybrid (default)
+- `guard-preset-fsd` - Feature-Sliced Design
+- `guard-preset-clean` - Clean Architecture
+- `guard-preset-hexagonal` - Hexagonal/Ports & Adapters
+
+### 3. Validation (HIGH)
+
+- `guard-validate-import` - Check import path validity
+- `guard-validate-location` - Check file location
+- `guard-validate-naming` - Check naming conventions
+
+### 4. Configuration (MEDIUM)
+
+- `guard-config-rules` - Configure rule severity
+- `guard-config-ignore` - Configure ignored paths
+
+## Mandu Preset Layers
+
+### Frontend (FSD)
+
+```
+app          # Top: app entry point
+  ↓
+pages        # Page components
+  ↓
+widgets      # Complex UI blocks
+  ↓
+features     # Feature units
+  ↓
+entities     # Business entities
+  ↓
+shared       # Shared utilities
+```
+
+### Backend (Clean)
+
+```
+api          # Top: API entry point
+  ↓
+application  # Use cases
+  ↓
+domain       # Business logic
+  ↓
+infra        # Infrastructure (DB, external APIs)
+  ↓
+core         # Core utilities
+  ↓
+shared       # Shared
+```
+
+## Validation Rules
+
+| Rule ID | Description |
+|---------|-------------|
+| `LAYER_VIOLATION` | Layer dependency violation |
+| `GENERATED_DIRECT_EDIT` | Direct edit of generated files |
+| `WRONG_SLOT_LOCATION` | Wrong slot file location |
+| `SLOT_NAMING` | Slot file naming rule violation |
+| `FORBIDDEN_IMPORT` | Forbidden import (fs, child_process, etc.) |
+
+## CLI Commands
+
+```bash
+# Architecture check
+bunx mandu guard arch
+
+# Watch mode
+bunx mandu guard arch --watch
+
+# CI mode (exit 1 on violation)
+bunx mandu guard arch --ci
+
+# Use specific preset
+bunx mandu guard arch --preset fsd
+```
+
+## How to Use
+
+Read individual rule files for detailed explanations:
+
+```
+rules/guard-layer-direction.md
+rules/guard-preset-mandu.md
+```

package/src/resources/skills/mandu-guard/metadata.json

@@ -0,0 +1,12 @@
+{
+  "version": "1.0.0",
+  "organization": "Mandu Framework",
+  "date": "February 2026",
+  "abstract": "아키텍처 가드 시스템 가이드. 레이어 간 의존성 규칙을 강제하고 위반을 실시간으로 감지합니다. FSD, Clean Architecture, Hexagonal 등 다양한 프리셋을 지원하며, CI/CD 파이프라인에 통합할 수 있습니다.",
+  "references": [
+    "https://feature-sliced.design/",
+    "https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html",
+    "https://alistair.cockburn.us/hexagonal-architecture/"
+  ],
+  "tags": ["guard", "architecture", "layers", "dependencies", "mandu"]
+}