mcp-dndgrid 0.1.0

package/src/server.ts

@@ -0,0 +1,314 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import {
+  validateLayout,
+  ValidateLayoutInputSchema,
+} from './tools/validate-layout.js';
+import {
+  analyzeLayout,
+  AnalyzeLayoutInputSchema,
+} from './tools/analyze-layout.js';
+import {
+  applyTemplate,
+  ApplyTemplateInputSchema,
+} from './tools/apply-template.js';
+import {
+  generateLayout,
+  GenerateLayoutInputSchema,
+} from './tools/generate-layout.js';
+import {
+  interactiveBuilder,
+  InteractiveBuilderInputSchema,
+} from './tools/interactive-builder.js';
+
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+/**
+ * DndGrid MCP Server
+ * Provides tools and resources for generating and analyzing DndGrid layouts
+ */
+export class DndGridMCPServer {
+  private server: Server;
+
+  constructor() {
+    this.server = new Server(
+      {
+        name: 'dndgrid-mcp',
+        version: '0.1.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+          resources: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+  }
+
+  private setupHandlers(): void {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      console.error('ListToolsRequest received');
+      return {
+        tools: [
+          {
+            name: 'validate-layout',
+            description: 'Validate DndGrid layout structure and constraints',
+            inputSchema: zodToJsonSchema(ValidateLayoutInputSchema) as any,
+          },
+          {
+            name: 'analyze-layout',
+            description: 'Analyze existing DndGrid code and suggest improvements',
+            inputSchema: zodToJsonSchema(AnalyzeLayoutInputSchema) as any,
+          },
+          {
+            name: 'apply-template',
+            description: 'Apply a pre-defined layout template',
+            inputSchema: zodToJsonSchema(ApplyTemplateInputSchema) as any,
+          },
+          {
+            name: 'generate-layout',
+            description: 'Generate DndGrid layout code from natural language requirements',
+            inputSchema: zodToJsonSchema(GenerateLayoutInputSchema) as any,
+          },
+          {
+            name: 'interactive-builder',
+            description: 'Build layout interactively through guided steps',
+            inputSchema: zodToJsonSchema(InteractiveBuilderInputSchema) as any,
+          },
+        ],
+      };
+    });
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      console.error(`CallToolRequest received: ${name}`);
+
+      try {
+        switch (name) {
+          case 'validate-layout':
+            return await validateLayout(args as any);
+          case 'analyze-layout':
+            return await analyzeLayout(args as any);
+          case 'apply-template':
+            return await applyTemplate(args as any);
+          case 'generate-layout':
+            return await generateLayout(args as any);
+          case 'interactive-builder':
+            return await interactiveBuilder(args as any);
+          default:
+            throw new Error(`Unknown tool: ${name}`);
+        }
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            },
+          ],
+        };
+      }
+    });
+
+    // List available resources
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      return {
+        resources: [
+          {
+            uri: 'dndgrid://docs/architecture',
+            name: 'DndGrid Architecture',
+            description: 'Complete architecture documentation',
+            mimeType: 'text/markdown',
+          },
+          {
+            uri: 'dndgrid://templates/list',
+            name: 'Available Templates',
+            description: 'List of all available layout templates',
+            mimeType: 'application/json',
+          },
+          {
+            uri: 'dndgrid://docs/best-practices',
+            name: 'Best Practices',
+            description: 'Performance and integration guidelines',
+            mimeType: 'text/markdown',
+          },
+        ],
+      };
+    });
+
+    // Read resource content
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const { uri } = request.params;
+
+      if (uri === 'dndgrid://docs/architecture') {
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: 'text/markdown',
+              text: this.getArchitectureDoc(),
+            },
+          ],
+        };
+      }
+
+      if (uri === 'dndgrid://templates/list') {
+        const { BUILTIN_TEMPLATES } = await import('./types/template.js');
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(BUILTIN_TEMPLATES, null, 2),
+            },
+          ],
+        };
+      }
+
+      if (uri === 'dndgrid://docs/best-practices') {
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: 'text/markdown',
+              text: this.getBestPracticesDoc(),
+            },
+          ],
+        };
+      }
+
+      throw new Error(`Unknown resource: ${uri}`);
+    });
+  }
+
+  /**
+   * Get architecture documentation
+   */
+  private getArchitectureDoc(): string {
+    return `# DndGrid Architecture
+
+## Overview
+
+DndGrid is a tree-based drag-and-drop grid system for React applications.
+
+## Core Components
+
+### DndGridContainer
+- Root component
+- Props: \`width\`, \`height\`, \`children\`
+- Manages global state
+
+### DndGridSplit
+- Divides space into two sections
+- Props: \`direction\` ('horizontal' | 'vertical'), \`ratio\` (0-1), \`children\` (exactly 2)
+- Creates nested layouts
+
+### DndGridItem
+- Leaf node containing user components
+- Props: \`children\`
+- Can be dragged and rearranged
+
+## Key Concepts
+
+### Flat Rendering
+- All items rendered at same depth
+- Preserves React component state during DnD
+- Logical tree != rendering tree
+
+### Tree Structure
+- Binary tree: each Split has 2 children
+- ID system: binary indexing
+- Supports unlimited nesting (recommended < 4 levels)
+
+### Next.js Compatibility
+- Requires \`"use client"\` directive for App Router
+- All DndGrid components are client components
+
+## Performance
+
+- **Recommended:** < 20 items, < 4 depth levels
+- **Maximum:** < 50 items, < 6 depth levels
+- Flat rendering optimizes reconciliation
+`;
+  }
+
+  /**
+   * Get best practices documentation
+   */
+  private getBestPracticesDoc(): string {
+    return `# DndGrid Best Practices
+
+## Performance
+
+### Item Count
+- Keep below 20 items for optimal performance
+- Maximum 50 items
+
+### Tree Depth
+- Recommended: < 4 levels
+- Maximum: 6 levels
+
+### Split Ratios
+- Avoid extreme ratios (< 0.1 or > 0.9)
+- Use 0.2-0.8 range for better UX
+
+## Next.js Integration
+
+### App Router
+\`\`\`tsx
+"use client";
+
+import { DndGridContainer, DndGridSplit, DndGridItem } from 'zerojin/components';
+\`\`\`
+
+### Pages Router
+No "use client" directive needed
+
+## Common Patterns
+
+### IDE Layout
+- Sidebar: 20%
+- Editor: 56%
+- Terminal: 24%
+
+### Dashboard (2x2)
+- Equal splits: 50/50
+
+### Three Column
+- Left: 20%
+- Center: 60%
+- Right: 20%
+
+## Troubleshooting
+
+### State Reset on DnD
+- Cause: Server Component in Next.js App Router
+- Fix: Add "use client" to all DndGrid components
+
+### Performance Issues
+- Check item count and depth
+- Simplify nested structures
+- Consider lazy loading
+`;
+  }
+
+  /**
+   * Start the MCP server
+   */
+  async start(): Promise<void> {
+    const transport = new (
+      await import('@modelcontextprotocol/sdk/server/stdio.js')
+    ).StdioServerTransport();
+    await this.server.connect(transport);
+    console.error('DndGrid MCP Server started');
+  }
+}

package/src/tools/analyze-layout.ts

@@ -0,0 +1,193 @@
+import { z } from 'zod';
+import { ASTParser } from '../utils/ast-parser.js';
+import { Validator } from '../utils/validator.js';
+import { LayoutAnalyzer } from '../utils/layout-analyzer.js';
+
+/**
+ * Input schema for analyze-layout tool
+ */
+export const AnalyzeLayoutInputSchema = z.object({
+  code: z.string().describe('DndGrid code to analyze'),
+  analyzePerformance: z.boolean().optional().default(true).describe('Include performance analysis'),
+  checkBestPractices: z.boolean().optional().default(true).describe('Check against best practices'),
+});
+
+export type AnalyzeLayoutInput = z.infer<typeof AnalyzeLayoutInputSchema>;
+
+/**
+ * analyze-layout tool implementation
+ */
+export async function analyzeLayout(args: AnalyzeLayoutInput) {
+  const { code, analyzePerformance, checkBestPractices } = args;
+
+  let output = `# DndGrid Layout Analysis\n\n`;
+
+  // Parse the code
+  const parser = new ASTParser();
+  const layout = parser.parse(code);
+
+  if (!layout) {
+    output += `❌ **Failed to parse layout**\n\n`;
+    output += `The code does not contain a valid DndGrid structure.\n`;
+    return {
+      content: [{ type: 'text' as const, text: output }],
+    };
+  }
+
+  // Structure analysis
+  output += `## Structure\n\n`;
+  const metadata = LayoutAnalyzer.calculateMetadata(layout);
+  output += `- **Container:** ${layout.width}x${layout.height}px\n`;
+  output += `- **Items:** ${metadata.itemCount}\n`;
+  output += `- **Splits:** ${metadata.splitCount}\n`;
+  output += `- **Max Depth:** ${metadata.maxDepth} levels\n`;
+  output += `- **Components:** ${LayoutAnalyzer.collectComponents(layout.child).join(', ')}\n\n`;
+
+  // Performance analysis
+  if (analyzePerformance) {
+    output += `## Performance\n\n`;
+    output += `**Score:** ${metadata.estimatedPerformance}\n\n`;
+
+    const recommendations: string[] = [];
+
+    if (metadata.itemCount > 20) {
+      recommendations.push(`Reduce item count from ${metadata.itemCount} to < 20 for better performance`);
+    }
+
+    if (metadata.maxDepth > 4) {
+      recommendations.push(`Reduce tree depth from ${metadata.maxDepth} to < 4 levels`);
+    }
+
+    if (metadata.splitCount > metadata.itemCount) {
+      recommendations.push('More splits than items - consider simplifying structure');
+    }
+
+    if (recommendations.length > 0) {
+      output += `**Recommendations:**\n\n`;
+      recommendations.forEach((rec, i) => {
+        output += `${i + 1}. ${rec}\n`;
+      });
+      output += '\n';
+    } else {
+      output += `✅ No performance issues detected\n\n`;
+    }
+  }
+
+  // Best practices
+  if (checkBestPractices) {
+    output += `## Best Practices Check\n\n`;
+
+    const checks = [];
+
+    // Check for "use client"
+    if (code.includes('"use client"') || code.includes("'use client'")) {
+      checks.push({ rule: 'Next.js "use client" directive', passed: true });
+    } else {
+      checks.push({
+        rule: 'Next.js "use client" directive',
+        passed: false,
+        message: 'Add "use client"; for Next.js App Router compatibility',
+      });
+    }
+
+    // Check imports
+    if (code.includes('zerojin/components')) {
+      checks.push({ rule: 'Correct import path', passed: true });
+    } else {
+      checks.push({
+        rule: 'Correct import path',
+        passed: false,
+        message: 'Import from "zerojin/components"',
+      });
+    }
+
+    // Check for reasonable dimensions
+    if (layout.width >= 400 && layout.height >= 300) {
+      checks.push({ rule: 'Reasonable container dimensions', passed: true });
+    } else {
+      checks.push({
+        rule: 'Reasonable container dimensions',
+        passed: false,
+        message: 'Container should be at least 400x300px',
+      });
+    }
+
+    checks.forEach((check) => {
+      const icon = check.passed ? '✅' : '❌';
+      output += `${icon} ${check.rule}\n`;
+      if (!check.passed && check.message) {
+        output += `   - ${check.message}\n`;
+      }
+    });
+    output += '\n';
+  }
+
+  // Validation
+  const validator = new Validator();
+  const validation = validator.validate(layout, true);
+
+  if (validation.errors.length > 0 || validation.warnings.length > 0) {
+    output += `## Issues\n\n`;
+
+    if (validation.errors.length > 0) {
+      output += `**Errors:**\n\n`;
+      validation.errors.forEach((err, i) => {
+        output += `${i + 1}. [${err.type}] ${err.message}\n`;
+      });
+      output += '\n';
+    }
+
+    if (validation.warnings.length > 0) {
+      output += `**Warnings:**\n\n`;
+      validation.warnings.forEach((warn, i) => {
+        output += `${i + 1}. ${warn.message}\n`;
+      });
+      output += '\n';
+    }
+  }
+
+  // Refactoring opportunities
+  output += `## Refactoring Opportunities\n\n`;
+
+  const opportunities = findRefactoringOpportunities(layout);
+  if (opportunities.length > 0) {
+    opportunities.forEach((opp, i) => {
+      output += `${i + 1}. **${opp.description}** (${opp.impact})\n`;
+      if (opp.example) {
+        output += `\`\`\`\n${opp.example}\n\`\`\`\n`;
+      }
+    });
+  } else {
+    output += `✅ No obvious refactoring opportunities\n`;
+  }
+
+  return {
+    content: [{ type: 'text' as const, text: output }],
+  };
+}
+
+function findRefactoringOpportunities(layout: any) {
+  const opportunities: Array<{
+    description: string;
+    impact: 'high' | 'medium' | 'low';
+    example?: string;
+  }> = [];
+
+  const metadata = LayoutAnalyzer.calculateMetadata(layout);
+
+  if (metadata.maxDepth > 5) {
+    opportunities.push({
+      description: 'Deep nesting detected - consider flattening structure',
+      impact: 'high',
+    });
+  }
+
+  if (metadata.itemCount > 30) {
+    opportunities.push({
+      description: 'High item count - consider lazy loading or pagination',
+      impact: 'medium',
+    });
+  }
+
+  return opportunities;
+}

package/src/tools/apply-template.ts

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { BUILTIN_TEMPLATES, type TemplateNode } from '../types/template.js';
+import type { LayoutTree, LayoutNode } from '../types/layout.js';
+import { CodeGenerator } from '../utils/code-generator.js';
+
+/**
+ * Input schema for apply-template tool
+ */
+export const ApplyTemplateInputSchema = z.object({
+  templateName: z
+    .enum(['ide-layout', 'dashboard-2x2', 'three-column', 'split-view'])
+    .describe('Template to apply'),
+  components: z
+    .record(z.string())
+    .describe('Mapping of template slots to component names'),
+  width: z.number().optional().default(1200).describe('Container width'),
+  height: z.number().optional().default(800).describe('Container height'),
+  framework: z
+    .enum(['react', 'nextjs-app', 'nextjs-pages'])
+    .optional()
+    .default('nextjs-app')
+    .describe('Target framework'),
+});
+
+export type ApplyTemplateInput = z.infer<typeof ApplyTemplateInputSchema>;
+
+/**
+ * apply-template tool implementation
+ */
+export async function applyTemplate(args: ApplyTemplateInput) {
+  const { templateName, components, width, height, framework } = args;
+
+  const template = BUILTIN_TEMPLATES[templateName];
+  if (!template) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `❌ Template "${templateName}" not found.\n\nAvailable templates: ${Object.keys(BUILTIN_TEMPLATES).join(', ')}`,
+        },
+      ],
+    };
+  }
+
+  // Validate that all required slots are provided
+  const missingSlots = template.slots.filter((slot) => !components[slot]);
+  if (missingSlots.length > 0) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `❌ Missing component mappings for slots: ${missingSlots.join(', ')}\n\nRequired slots: ${template.slots.join(', ')}`,
+        },
+      ],
+    };
+  }
+
+  // Apply components to template slots
+  const layoutNode = applyComponentsToSlots(template.tree, components);
+
+  // Build LayoutTree
+  const layout: LayoutTree = {
+    type: 'container',
+    width,
+    height,
+    child: layoutNode,
+  };
+
+  // Generate code
+  const generator = new CodeGenerator({
+    framework,
+    width,
+    height,
+  });
+  const code = generator.generate(layout);
+
+  // Format output
+  let output = `# Applied Template: ${template.name}\n\n`;
+  output += `${template.description}\n\n`;
+  output += `## Preview\n\n\`\`\`\n${template.preview}\n\`\`\`\n\n`;
+  output += `## Component Mapping\n\n`;
+  template.slots.forEach((slot) => {
+    output += `- **${slot}:** ${components[slot]}\n`;
+  });
+  output += `\n## Generated Code\n\n\`\`\`tsx\n${code}\`\`\`\n`;
+
+  return {
+    content: [{ type: 'text' as const, text: output }],
+  };
+}
+
+/**
+ * Apply component mappings to template slots
+ */
+function applyComponentsToSlots(
+  templateNode: TemplateNode,
+  components: Record<string, string>
+): LayoutNode {
+  if (templateNode.type === 'item') {
+    if (!templateNode.slot) {
+      throw new Error('Template item node missing slot');
+    }
+    const component = components[templateNode.slot];
+    if (!component) {
+      throw new Error(`No component provided for slot: ${templateNode.slot}`);
+    }
+    return {
+      type: 'item',
+      component,
+    };
+  }
+
+  // Split node
+  if (!templateNode.primary || !templateNode.secondary) {
+    throw new Error('Template split node missing children');
+  }
+
+  return {
+    type: 'split',
+    direction: templateNode.direction!,
+    ratio: templateNode.ratio!,
+    primary: applyComponentsToSlots(templateNode.primary, components),
+    secondary: applyComponentsToSlots(templateNode.secondary, components),
+  };
+}