cmp-standards 2.4.0 → 2.7.0

package/standards/mcp/tool-patterns.md

@@ -1,354 +1,354 @@
-# Patrones de Diseño para MCP Tools
-
-## Patrón: CRUD Básico
-
-Para entidades que necesitan operaciones estándar:
-
-```typescript
-// tools/entity.ts
-export const entityTools = [
-  {
-    name: 'entity_create',
-    description: 'Create a new entity',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        title: { type: 'string' },
-        data: { type: 'object' }
-      },
-      required: ['title']
-    }
-  },
-  {
-    name: 'entity_get',
-    description: 'Get entity by ID',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        id: { type: 'string' }
-      },
-      required: ['id']
-    }
-  },
-  {
-    name: 'entity_list',
-    description: 'List entities with optional filters',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        limit: { type: 'number', default: 10 },
-        filter: { type: 'object' }
-      }
-    }
-  },
-  {
-    name: 'entity_update',
-    description: 'Update entity by ID',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        id: { type: 'string' },
-        updates: { type: 'object' }
-      },
-      required: ['id', 'updates']
-    }
-  },
-  {
-    name: 'entity_delete',
-    description: 'Delete entity by ID',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        id: { type: 'string' }
-      },
-      required: ['id']
-    }
-  }
-]
-```
-
-## Patrón: Search Tool
-
-Para búsquedas con múltiples criterios:
-
-```typescript
-{
-  name: 'memory_search',
-  description: 'Search memories by content, domain, tags, or date range',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      query: {
-        type: 'string',
-        description: 'Text to search in title and body'
-      },
-      domain: {
-        type: 'string',
-        description: 'Filter by domain (e.g., "architecture", "performance")'
-      },
-      tags: {
-        type: 'array',
-        items: { type: 'string' },
-        description: 'Filter by tags (AND logic)'
-      },
-      dateFrom: {
-        type: 'string',
-        description: 'ISO date string for start range'
-      },
-      dateTo: {
-        type: 'string',
-        description: 'ISO date string for end range'
-      },
-      limit: {
-        type: 'number',
-        default: 10,
-        description: 'Max results to return'
-      }
-    }
-  }
-}
-```
-
-**Handler Pattern:**
-
-```typescript
-async function handleSearch(args: SearchArgs) {
-  const conditions: SQL[] = []
-
-  if (args.query) {
-    conditions.push(
-      or(
-        like(memories.title, `%${args.query}%`),
-        like(memories.body, `%${args.query}%`)
-      )
-    )
-  }
-
-  if (args.domain) {
-    conditions.push(eq(memories.domain, args.domain))
-  }
-
-  // Build query with all conditions
-  const results = await db.query.memories.findMany({
-    where: and(...conditions),
-    limit: args.limit ?? 10,
-    orderBy: desc(memories.createdAt)
-  })
-
-  return results
-}
-```
-
-## Patrón: Batch Operations
-
-Para operaciones sobre múltiples items:
-
-```typescript
-{
-  name: 'tasks_batch_update',
-  description: 'Update status of multiple tasks at once',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      ids: {
-        type: 'array',
-        items: { type: 'string' },
-        description: 'Task IDs to update'
-      },
-      status: {
-        type: 'string',
-        enum: ['pending', 'in_progress', 'completed']
-      }
-    },
-    required: ['ids', 'status']
-  }
-}
-```
-
-**Handler con Promise.all:**
-
-```typescript
-async function handleBatchUpdate(args: BatchUpdateArgs) {
-  const results = await Promise.allSettled(
-    args.ids.map(id =>
-      db.update(tasks)
-        .set({ status: args.status, updatedAt: new Date() })
-        .where(eq(tasks.id, id))
-    )
-  )
-
-  const succeeded = results.filter(r => r.status === 'fulfilled').length
-  const failed = results.filter(r => r.status === 'rejected').length
-
-  return {
-    total: args.ids.length,
-    succeeded,
-    failed
-  }
-}
-```
-
-## Patrón: Aggregation Tool
-
-Para datos agregados/estadísticas:
-
-```typescript
-{
-  name: 'analytics_summary',
-  description: 'Get aggregated analytics for a time period',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      period: {
-        type: 'string',
-        enum: ['day', 'week', 'month'],
-        default: 'week'
-      },
-      metrics: {
-        type: 'array',
-        items: {
-          type: 'string',
-          enum: ['memories_created', 'patterns_detected', 'tasks_completed']
-        }
-      }
-    }
-  }
-}
-```
-
-## Patrón: Composite Tool
-
-Cuando una operación necesita múltiples pasos:
-
-```typescript
-{
-  name: 'session_init',
-  description: 'Initialize a new work session with context loading',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      projectPath: { type: 'string' },
-      loadMemories: { type: 'boolean', default: true },
-      checkPatterns: { type: 'boolean', default: true }
-    },
-    required: ['projectPath']
-  }
-}
-```
-
-**Handler:**
-
-```typescript
-async function handleSessionInit(args: SessionInitArgs) {
-  const results: Record<string, unknown> = {}
-
-  // Step 1: Load project config
-  results.config = await loadProjectConfig(args.projectPath)
-
-  // Step 2: Parallel operations
-  const [memories, patterns] = await Promise.all([
-    args.loadMemories ? loadRecentMemories() : [],
-    args.checkPatterns ? detectPatterns() : []
-  ])
-
-  results.memories = memories
-  results.patterns = patterns
-
-  // Step 3: Generate context summary
-  results.summary = generateContextSummary(results)
-
-  return results
-}
-```
-
-## Patrón: Validation Tool
-
-Para validar datos antes de operaciones costosas:
-
-```typescript
-{
-  name: 'schema_validate',
-  description: 'Validate data against a schema before processing',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      schemaName: { type: 'string' },
-      data: { type: 'object' }
-    },
-    required: ['schemaName', 'data']
-  }
-}
-```
-
-## Anti-Patterns
-
-### NO: Tools Demasiado Genéricas
-
-```typescript
-// MAL - demasiado genérica
-{
-  name: 'do_database_operation',
-  inputSchema: {
-    properties: {
-      operation: { type: 'string' },  // "insert", "update", "delete"
-      table: { type: 'string' },
-      data: { type: 'object' }
-    }
-  }
-}
-
-// BIEN - específica y clara
-{
-  name: 'memory_create',
-  // ...
-}
-```
-
-### NO: Tools con Demasiados Parámetros
-
-```typescript
-// MAL - 15 parámetros
-{
-  name: 'complex_search',
-  inputSchema: {
-    properties: {
-      // ... 15 propiedades
-    }
-  }
-}
-
-// BIEN - dividir en tools más simples
-{
-  name: 'search_by_content',
-  // 2-3 parámetros
-}
-{
-  name: 'search_by_metadata',
-  // 2-3 parámetros
-}
-```
-
-### NO: Efectos Secundarios Ocultos
-
-```typescript
-// MAL - hace más de lo que dice
-async function handleGetMemory(id: string) {
-  const memory = await getMemory(id)
-  await updateAccessCount(id)  // Efecto secundario oculto
-  await logAccess(id)          // Otro efecto secundario
-  return memory
-}
-
-// BIEN - solo hace lo que dice
-async function handleGetMemory(id: string) {
-  return await getMemory(id)
-}
-```
-
-## Tips de Rendimiento
-
-1. **Paginación obligatoria** para list operations
-2. **Índices** en campos de búsqueda
-3. **Caché** para datos que no cambian frecuentemente
-4. **Parallel queries** con Promise.all cuando son independientes
-5. **Streaming** para respuestas grandes (futuro de MCP)
+# Patrones de Diseño para MCP Tools
+
+## Patrón: CRUD Básico
+
+Para entidades que necesitan operaciones estándar:
+
+```typescript
+// tools/entity.ts
+export const entityTools = [
+  {
+    name: 'entity_create',
+    description: 'Create a new entity',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string' },
+        data: { type: 'object' }
+      },
+      required: ['title']
+    }
+  },
+  {
+    name: 'entity_get',
+    description: 'Get entity by ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' }
+      },
+      required: ['id']
+    }
+  },
+  {
+    name: 'entity_list',
+    description: 'List entities with optional filters',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', default: 10 },
+        filter: { type: 'object' }
+      }
+    }
+  },
+  {
+    name: 'entity_update',
+    description: 'Update entity by ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        updates: { type: 'object' }
+      },
+      required: ['id', 'updates']
+    }
+  },
+  {
+    name: 'entity_delete',
+    description: 'Delete entity by ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' }
+      },
+      required: ['id']
+    }
+  }
+]
+```
+
+## Patrón: Search Tool
+
+Para búsquedas con múltiples criterios:
+
+```typescript
+{
+  name: 'memory_search',
+  description: 'Search memories by content, domain, tags, or date range',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'Text to search in title and body'
+      },
+      domain: {
+        type: 'string',
+        description: 'Filter by domain (e.g., "architecture", "performance")'
+      },
+      tags: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Filter by tags (AND logic)'
+      },
+      dateFrom: {
+        type: 'string',
+        description: 'ISO date string for start range'
+      },
+      dateTo: {
+        type: 'string',
+        description: 'ISO date string for end range'
+      },
+      limit: {
+        type: 'number',
+        default: 10,
+        description: 'Max results to return'
+      }
+    }
+  }
+}
+```
+
+**Handler Pattern:**
+
+```typescript
+async function handleSearch(args: SearchArgs) {
+  const conditions: SQL[] = []
+
+  if (args.query) {
+    conditions.push(
+      or(
+        like(memories.title, `%${args.query}%`),
+        like(memories.body, `%${args.query}%`)
+      )
+    )
+  }
+
+  if (args.domain) {
+    conditions.push(eq(memories.domain, args.domain))
+  }
+
+  // Build query with all conditions
+  const results = await db.query.memories.findMany({
+    where: and(...conditions),
+    limit: args.limit ?? 10,
+    orderBy: desc(memories.createdAt)
+  })
+
+  return results
+}
+```
+
+## Patrón: Batch Operations
+
+Para operaciones sobre múltiples items:
+
+```typescript
+{
+  name: 'tasks_batch_update',
+  description: 'Update status of multiple tasks at once',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      ids: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Task IDs to update'
+      },
+      status: {
+        type: 'string',
+        enum: ['pending', 'in_progress', 'completed']
+      }
+    },
+    required: ['ids', 'status']
+  }
+}
+```
+
+**Handler con Promise.all:**
+
+```typescript
+async function handleBatchUpdate(args: BatchUpdateArgs) {
+  const results = await Promise.allSettled(
+    args.ids.map(id =>
+      db.update(tasks)
+        .set({ status: args.status, updatedAt: new Date() })
+        .where(eq(tasks.id, id))
+    )
+  )
+
+  const succeeded = results.filter(r => r.status === 'fulfilled').length
+  const failed = results.filter(r => r.status === 'rejected').length
+
+  return {
+    total: args.ids.length,
+    succeeded,
+    failed
+  }
+}
+```
+
+## Patrón: Aggregation Tool
+
+Para datos agregados/estadísticas:
+
+```typescript
+{
+  name: 'analytics_summary',
+  description: 'Get aggregated analytics for a time period',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      period: {
+        type: 'string',
+        enum: ['day', 'week', 'month'],
+        default: 'week'
+      },
+      metrics: {
+        type: 'array',
+        items: {
+          type: 'string',
+          enum: ['memories_created', 'patterns_detected', 'tasks_completed']
+        }
+      }
+    }
+  }
+}
+```
+
+## Patrón: Composite Tool
+
+Cuando una operación necesita múltiples pasos:
+
+```typescript
+{
+  name: 'session_init',
+  description: 'Initialize a new work session with context loading',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      projectPath: { type: 'string' },
+      loadMemories: { type: 'boolean', default: true },
+      checkPatterns: { type: 'boolean', default: true }
+    },
+    required: ['projectPath']
+  }
+}
+```
+
+**Handler:**
+
+```typescript
+async function handleSessionInit(args: SessionInitArgs) {
+  const results: Record<string, unknown> = {}
+
+  // Step 1: Load project config
+  results.config = await loadProjectConfig(args.projectPath)
+
+  // Step 2: Parallel operations
+  const [memories, patterns] = await Promise.all([
+    args.loadMemories ? loadRecentMemories() : [],
+    args.checkPatterns ? detectPatterns() : []
+  ])
+
+  results.memories = memories
+  results.patterns = patterns
+
+  // Step 3: Generate context summary
+  results.summary = generateContextSummary(results)
+
+  return results
+}
+```
+
+## Patrón: Validation Tool
+
+Para validar datos antes de operaciones costosas:
+
+```typescript
+{
+  name: 'schema_validate',
+  description: 'Validate data against a schema before processing',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      schemaName: { type: 'string' },
+      data: { type: 'object' }
+    },
+    required: ['schemaName', 'data']
+  }
+}
+```
+
+## Anti-Patterns
+
+### NO: Tools Demasiado Genéricas
+
+```typescript
+// MAL - demasiado genérica
+{
+  name: 'do_database_operation',
+  inputSchema: {
+    properties: {
+      operation: { type: 'string' },  // "insert", "update", "delete"
+      table: { type: 'string' },
+      data: { type: 'object' }
+    }
+  }
+}
+
+// BIEN - específica y clara
+{
+  name: 'memory_create',
+  // ...
+}
+```
+
+### NO: Tools con Demasiados Parámetros
+
+```typescript
+// MAL - 15 parámetros
+{
+  name: 'complex_search',
+  inputSchema: {
+    properties: {
+      // ... 15 propiedades
+    }
+  }
+}
+
+// BIEN - dividir en tools más simples
+{
+  name: 'search_by_content',
+  // 2-3 parámetros
+}
+{
+  name: 'search_by_metadata',
+  // 2-3 parámetros
+}
+```
+
+### NO: Efectos Secundarios Ocultos
+
+```typescript
+// MAL - hace más de lo que dice
+async function handleGetMemory(id: string) {
+  const memory = await getMemory(id)
+  await updateAccessCount(id)  // Efecto secundario oculto
+  await logAccess(id)          // Otro efecto secundario
+  return memory
+}
+
+// BIEN - solo hace lo que dice
+async function handleGetMemory(id: string) {
+  return await getMemory(id)
+}
+```
+
+## Tips de Rendimiento
+
+1. **Paginación obligatoria** para list operations
+2. **Índices** en campos de búsqueda
+3. **Caché** para datos que no cambian frecuentemente
+4. **Parallel queries** con Promise.all cuando son independientes
+5. **Streaming** para respuestas grandes (futuro de MCP)