@mandujs/mcp 0.9.19 → 0.9.21

package/src/resources/skills/index.ts

@@ -0,0 +1,12 @@
+export { GUIDES, getGuide, listGuides, type GuideId } from "./guides.js";
+export { RECIPES, getRecipe, listRecipes, type RecipeId } from "./recipes.js";
+
+// Agent Skills pattern
+export {
+  listSkills,
+  getSkill,
+  listSkillRules,
+  getSkillRule,
+  type SkillMeta,
+  type RuleMeta,
+} from "./loader.js";

package/src/resources/skills/loader.ts

@@ -0,0 +1,218 @@
+/**
+ * Mandu MCP Skills - File-based Skill Loader
+ * Agent Skills 패턴으로 구성된 스킬을 파일 시스템에서 로드
+ */
+
+import { readdir, readFile } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export interface SkillMeta {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  author: string;
+}
+
+export interface RuleMeta {
+  id: string;
+  title: string;
+  impact: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+  impactDescription: string;
+  tags: string[];
+}
+
+// Available skills
+const SKILL_IDS = [
+  "mandu-slot",
+  "mandu-fs-routes",
+  "mandu-hydration",
+  "mandu-guard",
+  "mandu-performance",
+  "mandu-composition",
+  "mandu-security",
+  "mandu-testing",
+  "mandu-deployment",
+  "mandu-styling",
+  "mandu-ui",
+];
+
+/**
+ * Parse YAML frontmatter from markdown content
+ */
+function parseFrontmatter(content: string): { frontmatter: Record<string, unknown>; body: string } {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const [, yamlStr, body] = match;
+  const frontmatter: Record<string, unknown> = {};
+
+  // Simple YAML parsing (key: value pairs)
+  for (const line of yamlStr.split("\n")) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex > 0) {
+      const key = line.slice(0, colonIndex).trim();
+      let value: unknown = line.slice(colonIndex + 1).trim();
+
+      // Handle multiline values (description with |)
+      if (value === "|") {
+        continue; // Will be captured in subsequent lines
+      }
+
+      // Parse arrays (tags)
+      if (typeof value === "string" && value.includes(",")) {
+        value = value.split(",").map((s) => s.trim());
+      }
+
+      frontmatter[key] = value;
+    }
+  }
+
+  return { frontmatter, body };
+}
+
+/**
+ * List all available skills
+ */
+export function listSkills(): SkillMeta[] {
+  return SKILL_IDS.map((id) => {
+    const name = id.replace("mandu-", "");
+    return {
+      id,
+      name,
+      description: getSkillDescription(id),
+      version: "1.0.0",
+      author: "mandu",
+    };
+  });
+}
+
+function getSkillDescription(id: string): string {
+  const descriptions: Record<string, string> = {
+    "mandu-slot": "Business logic with Mandu.filling() API",
+    "mandu-fs-routes": "File-system based routing patterns",
+    "mandu-hydration": "Island hydration and client components",
+    "mandu-guard": "Architecture enforcement and layer dependencies",
+    "mandu-performance": "Performance optimization patterns for Mandu apps",
+    "mandu-composition": "React composition patterns for Islands and state",
+    "mandu-security": "Security best practices for authentication and protection",
+    "mandu-testing": "Testing patterns with Bun test and Playwright",
+    "mandu-deployment": "Production deployment with Render, Supabase, Docker, and CI/CD",
+    "mandu-styling": "CSS framework integration with Tailwind, Panda CSS, and theming",
+    "mandu-ui": "UI component library integration with shadcn/ui and accessibility",
+  };
+  return descriptions[id] || "";
+}
+
+/**
+ * Get a skill's SKILL.md content
+ */
+export async function getSkill(skillId: string): Promise<{ meta: SkillMeta; content: string } | null> {
+  if (!SKILL_IDS.includes(skillId)) {
+    return null;
+  }
+
+  const skillPath = join(__dirname, skillId, "SKILL.md");
+
+  try {
+    const content = await readFile(skillPath, "utf-8");
+    const { frontmatter, body } = parseFrontmatter(content);
+
+    return {
+      meta: {
+        id: skillId,
+        name: (frontmatter.name as string) || skillId,
+        description: (frontmatter.description as string) || "",
+        version: ((frontmatter.metadata as Record<string, string>)?.version as string) || "1.0.0",
+        author: ((frontmatter.metadata as Record<string, string>)?.author as string) || "mandu",
+      },
+      content: body,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List rules for a skill
+ */
+export async function listSkillRules(skillId: string): Promise<RuleMeta[]> {
+  if (!SKILL_IDS.includes(skillId)) {
+    return [];
+  }
+
+  const rulesPath = join(__dirname, skillId, "rules");
+
+  try {
+    const files = await readdir(rulesPath);
+    const rules: RuleMeta[] = [];
+
+    for (const file of files) {
+      if (!file.endsWith(".md")) continue;
+
+      const ruleId = file.replace(".md", "");
+      const content = await readFile(join(rulesPath, file), "utf-8");
+      const { frontmatter } = parseFrontmatter(content);
+
+      rules.push({
+        id: ruleId,
+        title: (frontmatter.title as string) || ruleId,
+        impact: (frontmatter.impact as RuleMeta["impact"]) || "MEDIUM",
+        impactDescription: (frontmatter.impactDescription as string) || "",
+        tags: Array.isArray(frontmatter.tags)
+          ? (frontmatter.tags as string[])
+          : typeof frontmatter.tags === "string"
+            ? frontmatter.tags.split(",").map((s: string) => s.trim())
+            : [],
+      });
+    }
+
+    // Sort by impact priority
+    const impactOrder = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
+    return rules.sort((a, b) => impactOrder[a.impact] - impactOrder[b.impact]);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get a specific rule's content
+ */
+export async function getSkillRule(
+  skillId: string,
+  ruleId: string
+): Promise<{ meta: RuleMeta; content: string } | null> {
+  if (!SKILL_IDS.includes(skillId)) {
+    return null;
+  }
+
+  const rulePath = join(__dirname, skillId, "rules", `${ruleId}.md`);
+
+  try {
+    const content = await readFile(rulePath, "utf-8");
+    const { frontmatter, body } = parseFrontmatter(content);
+
+    return {
+      meta: {
+        id: ruleId,
+        title: (frontmatter.title as string) || ruleId,
+        impact: (frontmatter.impact as RuleMeta["impact"]) || "MEDIUM",
+        impactDescription: (frontmatter.impactDescription as string) || "",
+        tags: Array.isArray(frontmatter.tags)
+          ? (frontmatter.tags as string[])
+          : typeof frontmatter.tags === "string"
+            ? frontmatter.tags.split(",").map((s: string) => s.trim())
+            : [],
+      },
+      content: body,
+    };
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,91 @@
+---
+name: mandu-composition
+description: |
+  React composition patterns for Mandu applications. Use when designing
+  Island components, managing shared state, or building reusable component
+  APIs. Triggers on compound components, context providers, boolean props,
+  or component architecture tasks.
+license: MIT
+metadata:
+  author: mandu
+  version: "1.0.0"
+---
+
+# Mandu Composition
+
+Mandu 애플리케이션을 위한 React 컴포지션 패턴 가이드. Island 컴파운드 컴포넌트, 상태 관리 인터페이스, Provider 패턴, slot-client 분리를 다룹니다. Vercel의 Composition Patterns를 Mandu 컨텍스트로 변환하여 적용합니다.
+
+## When to Apply
+
+Reference these guidelines when:
+- Designing Island component architecture
+- Managing shared state between Islands
+- Building reusable component APIs
+- Refactoring components with boolean prop proliferation
+- Working with compound components or context providers
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Component Architecture | HIGH | `comp-arch-` |
+| 2 | State Management | HIGH | `comp-state-` |
+| 3 | Island Patterns | MEDIUM | `comp-island-` |
+| 4 | Implementation Patterns | MEDIUM | `comp-pattern-` |
+
+## Quick Reference
+
+### 1. Component Architecture (HIGH)
+
+- `comp-arch-avoid-boolean-props` - Use composition instead of boolean customization
+- `comp-arch-compound-components` - Structure Islands as compound components
+- `comp-arch-explicit-variants` - Create explicit variant components
+
+### 2. State Management (HIGH)
+
+- `comp-state-context-interface` - Define generic state/actions/meta interface
+- `comp-state-lift-state` - Move state into provider for sibling access
+- `comp-state-decouple-impl` - Provider is the only place knowing implementation
+
+### 3. Island Patterns (MEDIUM)
+
+- `comp-island-compound` - Compose Islands with shared context
+- `comp-island-event` - Communicate between Islands with useIslandEvent
+- `comp-island-slot-split` - Separate server logic (slot) from client (Island)
+
+### 4. Implementation Patterns (MEDIUM)
+
+- `comp-pattern-children` - Use children for composition over render props
+- `comp-pattern-provider-boundary` - Understand provider boundary vs visual nesting
+
+## Core Principle
+
+**Lift state, compose internals, make state dependency-injectable.**
+
+```
+┌─────────────────────────────────────────┐
+│  Provider (state + actions + meta)      │
+│  ┌───────────────────────────────────┐  │
+│  │  Composer.Frame                   │  │
+│  │  ┌─────────┐ ┌─────────────────┐  │  │
+│  │  │ Input   │ │ Footer          │  │  │
+│  │  └─────────┘ │ ┌─────┐ ┌─────┐ │  │  │
+│  │              │ │Emoji│ │Send │ │  │  │
+│  │              │ └─────┘ └─────┘ │  │  │
+│  │              └─────────────────┘  │  │
+│  └───────────────────────────────────┘  │
+│  ┌───────────────┐  ← Outside Frame     │
+│  │ Preview       │     but inside       │
+│  └───────────────┘     Provider!        │
+└─────────────────────────────────────────┘
+```
+
+## How to Use
+
+Read individual rule files for detailed explanations:
+
+```
+rules/comp-arch-compound-components.md
+rules/comp-state-context-interface.md
+rules/comp-island-event.md
+```

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

@@ -0,0 +1,13 @@
+{
+  "version": "1.0.0",
+  "organization": "Mandu Framework",
+  "date": "February 2026",
+  "abstract": "Mandu 애플리케이션을 위한 React 컴포지션 패턴 가이드. Island 컴파운드 컴포넌트, state/actions/meta 인터페이스, Provider 패턴, useIslandEvent를 통한 Island 간 통신, slot-client 분리 패턴을 다룹니다. Vercel Composition Patterns 기반으로 Mandu 컨텍스트에 맞게 변환되었습니다.",
+  "references": [
+    "https://react.dev/learn/passing-data-deeply-with-context",
+    "https://react.dev/learn/scaling-up-with-reducer-and-context",
+    "https://www.patterns.dev/react/compound-pattern",
+    "https://kentcdodds.com/blog/compound-components-with-react-hooks"
+  ],
+  "tags": ["composition", "compound", "context", "state", "island", "mandu"]
+}

package/src/resources/skills/mandu-composition/rules/_sections.md

@@ -0,0 +1,26 @@
+# 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. Component Architecture (comp-arch)
+
+**Impact:** HIGH
+**Description:** Boolean props 대신 컴포지션 사용, 컴파운드 컴포넌트 구조화. 코드베이스가 확장됨에 따라 유지보수성에 큰 영향을 미칩니다.
+
+## 2. State Management (comp-state)
+
+**Impact:** HIGH
+**Description:** state/actions/meta 인터페이스 정의, Provider를 통한 의존성 주입. 같은 UI를 다양한 상태 구현과 함께 재사용할 수 있게 합니다.
+
+## 3. Island Patterns (comp-island)
+
+**Impact:** MEDIUM
+**Description:** Mandu Island 특화 패턴. 컴파운드 Island, Island 간 이벤트 통신, slot-client 분리를 다룹니다.
+
+## 4. Implementation Patterns (comp-pattern)
+
+**Impact:** MEDIUM
+**Description:** children 활용, Provider 경계 이해 등 구현 세부 사항. 올바른 패턴 적용으로 유연성을 확보합니다.

package/src/resources/skills/mandu-composition/rules/_template.md

@@ -0,0 +1,77 @@
+# Rule Template
+
+Use this template when creating new rules for mandu-composition.
+
+---
+
+```markdown
+---
+title: Rule Title Here
+impact: HIGH | MEDIUM | LOW
+impactDescription: 영향 설명 (예: "enables flexible composition")
+tags: composition, tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: {LEVEL} ({impactDescription})**
+
+규칙의 목적과 아키텍처적 영향을 설명합니다.
+
+**Incorrect (문제가 되는 패턴):**
+
+\`\`\`tsx
+// ❌ Boolean props로 기능 추가
+function Composer({
+  showAttachments,
+  showFormatting,
+  showEmojis,
+  isCompact,
+  isReadOnly,
+}: Props) {
+  return (
+    <form>
+      {!isReadOnly && <Input />}
+      {showAttachments && <Attachments />}
+      {showFormatting && <Formatting />}
+      {showEmojis && <Emojis />}
+    </form>
+  );
+}
+```
+
+**Correct (컴포지션 패턴):**
+
+\`\`\`tsx
+// ✅ 컴포지션으로 유연하게 구성
+<Composer.Provider state={state} actions={actions}>
+  <Composer.Frame>
+    <Composer.Input />
+    <Composer.Footer>
+      <Composer.Emojis />
+      <Composer.Submit />
+    </Composer.Footer>
+  </Composer.Frame>
+</Composer.Provider>
+\`\`\`
+
+## Mandu Context
+
+Mandu Island에서 이 패턴을 적용하는 방법을 설명합니다.
+
+Reference: [관련 문서 링크](https://example.com)
+```
+
+---
+
+## Naming Convention
+
+- 파일명: `comp-{category}-{rule-name}.md`
+- 예시: `comp-arch-compound-components.md`, `comp-state-context-interface.md`
+
+## Core Principle
+
+**Lift state, compose internals, make state dependency-injectable.**
+
+UI는 조합 가능한 조각들이고, 상태는 Provider가 주입합니다.
+Provider를 바꾸면 UI는 그대로 유지됩니다.

package/src/resources/skills/mandu-composition/rules/comp-arch-avoid-boolean-props.md

@@ -0,0 +1,146 @@
+---
+title: Use Composition Instead of Boolean Props
+impact: HIGH
+impactDescription: Prevents prop explosion and improves flexibility
+tags: composition, boolean, props, architecture
+---
+
+## Use Composition Instead of Boolean Props
+
+**Impact: HIGH (Prevents prop explosion and improves flexibility)**
+
+동작을 커스터마이즈하기 위해 boolean props를 추가하지 마세요. 대신 컴포지션을 사용하세요.
+
+**Incorrect (boolean props 폭발):**
+
+```tsx
+// ❌ Boolean props가 계속 늘어남
+function Card({
+  title,
+  children,
+  showHeader,
+  showFooter,
+  showActions,
+  isCompact,
+  isHighlighted,
+  isBordered,
+  isClickable,
+  isLoading,
+}: CardProps) {
+  return (
+    <div className={cn(
+      "card",
+      isCompact && "card--compact",
+      isHighlighted && "card--highlighted",
+      isBordered && "card--bordered",
+      isClickable && "card--clickable",
+    )}>
+      {isLoading && <Spinner />}
+      {showHeader && <Header>{title}</Header>}
+      {children}
+      {showFooter && <Footer />}
+      {showActions && <Actions />}
+    </div>
+  );
+}
+
+// 사용 시 복잡한 props 조합
+<Card
+  title="Settings"
+  showHeader
+  showFooter
+  showActions
+  isCompact
+  isBordered
+  isClickable={false}
+  isLoading={loading}
+>
+  {content}
+</Card>
+```
+
+**Correct (컴포지션 패턴):**
+
+```tsx
+// ✅ 기본 Card와 조합 가능한 서브컴포넌트
+function Card({ children, className }: CardProps) {
+  return <div className={cn("card", className)}>{children}</div>;
+}
+
+function CardHeader({ children }: { children: React.ReactNode }) {
+  return <div className="card-header">{children}</div>;
+}
+
+function CardFooter({ children }: { children: React.ReactNode }) {
+  return <div className="card-footer">{children}</div>;
+}
+
+function CardActions({ children }: { children: React.ReactNode }) {
+  return <div className="card-actions">{children}</div>;
+}
+
+// Variants는 명시적 컴포넌트로
+function CompactCard({ children }: CardProps) {
+  return <Card className="card--compact">{children}</Card>;
+}
+
+function HighlightedCard({ children }: CardProps) {
+  return <Card className="card--highlighted">{children}</Card>;
+}
+
+// Export
+export { Card, CardHeader, CardFooter, CardActions, CompactCard, HighlightedCard };
+```
+
+**사용법:**
+
+```tsx
+// 필요한 것만 명시적으로 조합
+<Card>
+  <CardHeader>Settings</CardHeader>
+  <SettingsContent />
+  <CardFooter>
+    <CardActions>
+      <SaveButton />
+      <CancelButton />
+    </CardActions>
+  </CardFooter>
+</Card>
+
+// Compact variant
+<CompactCard>
+  <QuickStats />
+</CompactCard>
+```
+
+## Mandu Island에서의 적용
+
+```tsx
+// app/dashboard/client.tsx
+"use client";
+
+// ❌ 피해야 할 패턴
+export function DashboardIsland({
+  showCharts,
+  showStats,
+  showAlerts,
+  isCompact,
+}: Props) { ... }
+
+// ✅ 권장 패턴
+export const Dashboard = {
+  Provider: DashboardProvider,
+  Charts: DashboardCharts,
+  Stats: DashboardStats,
+  Alerts: DashboardAlerts,
+  CompactLayout: DashboardCompactLayout,
+};
+```
+
+## 언제 Boolean Props가 괜찮은가?
+
+- 단일 시각적 상태 (disabled, loading)
+- 토글 가능한 단일 기능 (checked, open)
+- 컴포지션이 과도한 경우의 간단한 변형
+
+Reference: [Avoid Boolean Props](https://spicefactory.co/blog/2019/03/26/how-to-avoid-the-boolean-trap-when-designing-react-components/)