@loggi87/mcp-custom-xs 1.0.0 → 1.0.3

package/README.md

@@ -0,0 +1,365 @@
+# mcp-custom-xs
+
+**MCP Server con reglas de código compartidas para proyectos React + TypeScript.**
+
+Un paquete de reglas y estándares que puedes usar en tus proyectos para mantener calidad, consistencia y arquitectura limpia.
+
+---
+
+## 📋 ¿Qué incluye?
+
+- ✅ **Max 80 líneas por archivo** - Mantén archivos pequeños y legibles
+- ✅ **Atomic Design** - Estructura de componentes: atoms → molecules → organisms
+- ✅ **Feature-based** - Organiza por features, no por tipo
+- ✅ **TypeScript Strict** - Type safety total
+- ✅ **Validación automática** - Valida tus archivos contra las reglas
+
+---
+
+## 🚀 Instalación
+
+### 1. Instalar el paquete
+
+```bash
+npm install @loggi87/mcp-custom-xs
+```
+
+### 2. Opción A: Usar en Claude.ai (recomendado para desarrollo)
+
+Agrega las reglas a tus **Custom Instructions** en Claude.ai:
+
+**Settings → Custom Instructions → Instructions**
+
+````
+# MCP Code Rules (@loggi87/mcp-custom-xs)
+
+## Reglas obligatorias para TODOS los features:
+
+1. **Max 80 líneas por archivo**
+    - Si necesitas más, divide en múltiples archivos
+    - Excepciones documentadas requieren comentario // LONG_FILE
+
+2. **Atomic Design para componentes**
+   ```
+   src/components/
+   ├── atoms/           (botones, inputs, etiquetas)
+   ├── molecules/       (formularios simples, tarjetas)
+   └── organisms/       (modales, headers complejos)
+   ```
+
+3. **Feature-based structure**
+   ```
+   src/features/{featureName}/
+   ├── components/      (atoms, molecules, organisms)
+   ├── hooks/
+   ├── services/
+   ├── types/
+   └── index.ts
+   ```
+
+4. **TypeScript Strict Mode**
+    - \`tsconfig.json\`: \`"strict": true\`
+    - No usar \`any\`
+    - Tipear siempre argumentos y retornos
+
+5. **Validar con tsc ANTES de terminar**
+   ```bash
+   tsc --noEmit
+   ```
+
+## Cuando generes código:
+1. Crea los archivos respetando estas reglas
+2. Muestra la estructura antes del código
+3. Al final, ejecuta \`tsc --noEmit\`
+4. Si hay errores de tipos, arréglalos
+5. Reporta: ✅ Validado o ❌ Errores encontrados
+
+## Ejemplo de request:
+"Crea el feature de AuthModal usando @loggi87/mcp-custom-xs"
+````
+
+**Listo.** Desde ese momento, cada código que te genere seguirá estas reglas automáticamente.
+
+### 3. Opción B: Usar en tu proyecto (para validación programática)
+
+```javascript
+// En tu proyecto
+const rules = require('@loggi87/mcp-custom-xs');
+
+// Validar un archivo
+const validation = rules.validateFile('./src/components/Button.tsx');
+
+console.log(validation);
+// {
+//   valid: true,
+//   errors: [],
+//   file: './src/components/Button.tsx',
+//   lineCount: 31
+// }
+```
+
+---
+
+## 📂 Estructura recomendada
+
+```
+proyecto/
+├── src/
+│   ├── components/
+│   │   ├── atoms/
+│   │   │   ├── Button.tsx           (30 líneas)
+│   │   │   └── Input.tsx            (28 líneas)
+│   │   ├── molecules/
+│   │   │   └── LoginForm.tsx        (65 líneas)
+│   │   └── organisms/
+│   │       └── AuthModal.tsx        (72 líneas)
+│   ├── features/
+│   │   ├── Auth/
+│   │   │   ├── components/
+│   │   │   ├── hooks/
+│   │   │   ├── services/
+│   │   │   ├── types/
+│   │   │   └── index.ts
+│   │   └── Dashboard/
+│   │       └── ...
+│   ├── hooks/
+│   ├── services/
+│   ├── types/
+│   └── index.ts
+├── tsconfig.json
+├── .eslintrc.json
+└── package.json
+```
+
+---
+
+## 🔧 Configuración recomendada
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"]
+  }
+}
+```
+
+### .eslintrc.json
+
+```json
+{
+  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+  "parser": "@typescript-eslint/parser",
+  "rules": {
+    "max-lines": ["error", { "max": 80 }],
+    "@typescript-eslint/no-explicit-any": "error",
+    "no-unused-vars": "warn"
+  }
+}
+```
+
+---
+
+## 💡 Ejemplos
+
+### ✅ Buen componente (respeta las reglas)
+
+**src/components/atoms/Button.tsx**
+```typescript
+import React from 'react';
+
+interface ButtonProps {
+  label: string;
+  onClick: () => void;
+  variant?: 'primary' | 'secondary';
+}
+
+export const Button: React.FC<ButtonProps> = ({
+  label,
+  onClick,
+  variant = 'primary',
+}) => {
+  const baseStyle = 'px-4 py-2 rounded font-semibold';
+  const variantStyle =
+    variant === 'primary'
+      ? 'bg-blue-500 text-white'
+      : 'bg-gray-200 text-black';
+
+  return (
+    <button
+      className={\`\${baseStyle} \${variantStyle}\`}
+      onClick={onClick}
+    >
+      {label}
+    </button>
+  );
+};
+```
+
+**Cumple:**
+- ✅ 31 líneas (< 80)
+- ✅ En \`atoms/\` (Atomic Design)
+- ✅ TypeScript tipado correctamente
+- ✅ Componente simple y reutilizable
+
+### ❌ Mal componente (no respeta reglas)
+
+```typescript
+// ❌ 120 líneas (> 80)
+// ❌ Lógica compleja + UI mezcladas
+// ❌ No está en estructura atómica
+// ❌ any types
+```
+
+---
+
+## 🤝 Mejoras y contribuciones
+
+¿Querés mejorar las reglas? ¡Excelente!
+
+1. **Fork el repo**
+2. **Crea una rama** (\`git checkout -b feature/nueva-regla\`)
+3. **Modifica \`index.js\`**
+4. **Testea** (\`npm test\`)
+5. **Haz PR** con descripción clara
+
+### Cambios comunes que podrías hacer:
+
+```javascript
+// En index.js, puedes agregar:
+
+// - Cambiar límite de líneas
+max_lines_per_file: 100,  // Era 80
+
+// - Agregar nuevas validaciones
+no_console_logs: true,
+
+// - Permitir excepciones
+exceptions: {
+"src/utils/constants.ts": { max_lines: 200 }
+}
+```
+
+---
+
+## 📦 Cómo se usa en un proyecto real
+
+### Paso 1: Instalar
+
+```bash
+npm install @loggi87/mcp-custom-xs
+```
+
+### Paso 2: Agregar a Claude Custom Instructions
+
+Copia el contenido arriba y pégalo en Claude.ai Settings.
+
+### Paso 3: Pedir features
+
+```
+"Crea el feature de LoginForm con:
+- Validación de email
+- Password con toggle visibility
+- Remember me checkbox
+
+Usa @loggi87/mcp-custom-xs"
+```
+
+Claude automáticamente:
+- ✅ Divide en atoms/molecules si es necesario
+- ✅ Mantiene archivos < 80 líneas
+- ✅ Usa TypeScript strict
+- ✅ Corre \`tsc --noEmit\`
+- ✅ Reporta si todo está ✅
+
+---
+
+## 📋 API
+
+### \`rules\`
+
+Objeto con todas las reglas definidas:
+
+```javascript
+const { rules } = require('@loggi87/mcp-custom-xs');
+
+console.log(rules);
+// {
+//   max_lines_per_file: 80,
+//   architecture: 'atomic',
+//   project_structure: 'feature-based',
+//   typescript_strict: true,
+//   run_tsc_before_finish: true
+// }
+```
+
+### \`validateFile(filePath)\`
+
+Valida un archivo contra las reglas:
+
+```javascript
+const { validateFile } = require('@loggi87/mcp-custom-xs');
+
+const result = validateFile('./src/components/atoms/Button.tsx');
+
+console.log(result);
+// {
+//   valid: true,
+//   errors: [],
+//   file: './src/components/atoms/Button.tsx',
+//   lineCount: 31
+// }
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### "Cannot find module '@loggi87/mcp-custom-xs'"
+
+```bash
+npm install @loggi87/mcp-custom-xs
+```
+
+### "TypeScript errors después de instalar"
+
+Verifica que \`tsconfig.json\` tiene \`"strict": true\`
+
+### "Claude no sigue las reglas"
+
+1. Verifica que copiaste las Custom Instructions correctamente
+2. Pide explícitamente: "usa @loggi87/mcp-custom-xs"
+3. Si no funciona, menciona las reglas en el mensaje
+
+---
+
+## 📞 Contacto
+
+¿Preguntas, bugs, o mejoras?
+
+- **Issues**: Abre un issue en GitHub
+- **Mejoras**: Haz un PR
+- **Contacto directo**: [@loggi87](https://github.com/loggi87)
+
+---
+
+## 📄 Licencia
+
+MIT - Úsalo libremente en tus proyectos
+
+---
+
+## Versión
+
+**@loggi87/mcp-custom-xs@1.0.0**
+
+Última actualización: Marzo 2026

package/index.js

@@ -1,56 +1,144 @@
-// index.js - MCP Server
+// index.js - MCP Server (@loggi87/mcp-custom-xs)
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { z } = require("zod");
 const fs = require("fs");
+const path = require("path");
 
-class CodeRulesMCP {
-    constructor() {
-        this.rules = {
-            max_lines_per_file: 80,
-            architecture: "atomic",
-            project_structure: "feature-based",
-            typescript_strict: true,
-            run_tsc_before_finish: true
-        };
+const RULES = {
+  max_lines_per_file: 80,
+  architecture: "atomic",
+  project_structure: "feature-based",
+  typescript_strict: true,
+  run_tsc_before_finish: true
+};
+
+function validateFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const lines = content.split("\n").length;
+    const errors = [];
+
+    if (lines > RULES.max_lines_per_file) {
+      errors.push({
+        type: "TOO_MANY_LINES",
+        message: `❌ ${lines} líneas (máx ${RULES.max_lines_per_file})`,
+        severity: "error"
+      });
     }
 
-    // Valida un archivo
-    validateFile(filePath) {
-        const content = fs.readFileSync(filePath, "utf-8");
-        const lines = content.split("\n").length;
+    if (filePath.endsWith(".ts") || filePath.endsWith(".tsx")) {
+      if (!content.includes("// @ts-check") && !content.includes("strict")) {
+        errors.push({
+          type: "NO_TYPESCRIPT_STRICT",
+          message: "❌ Falta TypeScript strict mode",
+          severity: "warn",
+          suggestion: "Agrega 'strict': true en tsconfig.json"
+        });
+      }
+    }
 
-        const errors = [];
+    if (filePath.includes("components")) {
+      const validDirs = ["/atoms/", "/molecules/", "/organisms/"];
+      if (!validDirs.some((dir) => filePath.includes(dir))) {
+        errors.push({
+          type: "WRONG_COMPONENT_STRUCTURE",
+          message: "❌ Componente no está en atoms/molecules/organisms",
+          severity: "error",
+          suggestion: "Estructura correcta: src/components/{atoms|molecules|organisms}/"
+        });
+      }
+    }
 
-        // Validar líneas
-        if (lines > this.rules.max_lines_per_file) {
-            errors.push(`❌ ${lines} líneas (máx ${this.rules.max_lines_per_file})`);
-        }
+    return {
+      valid: errors.length === 0,
+      file: filePath,
+      lineCount: lines,
+      errors,
+      summary: errors.length === 0
+          ? "✅ Archivo válido"
+          : `❌ ${errors.length} error(es) encontrado(s)`
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      file: filePath,
+      errors: [{ type: "FILE_READ_ERROR", message: error.message, severity: "error" }]
+    };
+  }
+}
 
-        // Validar TypeScript strict
-        if (!content.includes('// @ts-check')) {
-            errors.push("❌ Falta // @ts-check para TypeScript strict");
-        }
+function validateFeature(featureDir) {
+  const results = [];
 
-        // Validar estructura atómica
-        if (filePath.includes("components")) {
-            const validDirs = ["/atoms/", "/molecules/", "/organisms/"];
-            if (!validDirs.some((dir) => filePath.includes(dir))) {
-                errors.push("❌ Componente no está en atomic/molecules/organisms");
-            }
+  const walkDir = (dir) => {
+    try {
+      fs.readdirSync(dir).forEach((file) => {
+        const filePath = path.join(dir, file);
+        const stat = fs.statSync(filePath);
+        if (stat.isDirectory() && !file.startsWith(".")) {
+          walkDir(filePath);
+        } else if (/\.(ts|tsx|js)$/.test(file)) {
+          results.push(validateFile(filePath));
         }
+      });
+    } catch (e) {}
+  };
 
-        return {
-            valid: errors.length === 0,
-            errors,
-            suggestions: this.getSuggestions(errors)
-        };
-    }
+  walkDir(featureDir);
 
-    getSuggestions(errors) {
-        return {
-            tooManyLines: "Divide en múltiples archivos más pequeños",
-            noTypeScript: "Agrega strict mode a tsconfig.json",
-            wrongFolder: "Mueve a la carpeta de atomic design correcta"
-        };
-    }
+  const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
+  return {
+    valid: totalErrors === 0,
+    featureDir,
+    filesValidated: results.length,
+    totalErrors,
+    files: results,
+    summary: totalErrors === 0
+        ? `✅ Feature válido (${results.length} archivos)`
+        : `❌ ${totalErrors} error(es) en ${results.length} archivo(s)`
+  };
+}
+
+function getFormattedRules() {
+  return `# Reglas del proyecto (@loggi87/mcp-custom-xs)
+
+1. **Max ${RULES.max_lines_per_file} líneas por archivo**
+2. **Atomic Design** para componentes (atoms / molecules / organisms)
+3. **Feature-based** project structure
+4. **TypeScript Strict Mode**
+5. **Ejecutar tsc** antes de terminar cualquier tarea`;
 }
 
-module.exports = new CodeRulesMCP();
+// Servidor MCP
+const server = new McpServer({ name: "mcp-custom-xs", version: "1.0.3" });
+
+server.tool(
+    "validate_file",
+    "Valida un archivo contra las reglas del proyecto (líneas, atomic design, TypeScript)",
+    { filePath: z.string().describe("Ruta absoluta o relativa al archivo a validar") },
+    async ({ filePath }) => ({
+      content: [{ type: "text", text: JSON.stringify(validateFile(filePath), null, 2) }]
+    })
+);
+
+server.tool(
+    "validate_feature",
+    "Valida todos los archivos de un directorio/feature contra las reglas del proyecto",
+    { featureDir: z.string().describe("Ruta al directorio del feature a validar") },
+    async ({ featureDir }) => ({
+      content: [{ type: "text", text: JSON.stringify(validateFeature(featureDir), null, 2) }]
+    })
+);
+
+server.tool(
+    "get_rules",
+    "Devuelve las reglas de código del proyecto",
+    {},
+    async () => ({
+      content: [{ type: "text", text: getFormattedRules() }]
+    })
+);
+
+const transport = new StdioServerTransport();
+server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loggi87/mcp-custom-xs",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "publishConfig": {
     "access": "public"
   },
@@ -10,5 +10,9 @@
     "mcp",
     "rules",
     "atomic-design"
-  ]
-}
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "zod": "^4.3.6"
+  }
+}