cmp-standards 2.0.1 → 2.6.0

package/standards/infrastructure/cloud-database.md

@@ -0,0 +1,287 @@
+# Infraestructura de Base de Datos Cloud
+
+## Stack Recomendado (100% Gratuito)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    ARQUITECTURA CLOUD                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │   Turso     │  │  Upstash    │  │  Upstash    │         │
+│  │  (SQLite)   │  │  (Vector)   │  │  (Redis)    │         │
+│  │             │  │             │  │             │         │
+│  │ • Tareas    │  │ • Embeddings│  │ • Cache     │         │
+│  │ • Mejoras   │  │ • Semantic  │  │ • Sessions  │         │
+│  │ • Sesiones  │  │   Search    │  │ • Config    │         │
+│  │ • Memorias  │  │             │  │             │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘         │
+│        │                │                │                  │
+│        └────────────────┼────────────────┘                  │
+│                         │                                   │
+│                         ▼                                   │
+│              ┌─────────────────────┐                        │
+│              │   MCP Server        │                        │
+│              │ (Vercel Edge)       │                        │
+│              └─────────────────────┘                        │
+│                         │                                   │
+│                         ▼                                   │
+│              ┌─────────────────────┐                        │
+│              │   Claude Code       │                        │
+│              └─────────────────────┘                        │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Turso (SQLite Edge)
+
+**Propósito**: Base de datos principal para tareas, mejoras, memorias.
+
+### Free Tier
+- 500M rows read/mes
+- 10M rows written/mes
+- 5GB storage
+- 100 databases
+- Sin tarjeta de crédito
+
+### Setup
+
+```bash
+# Instalar CLI
+brew install tursodatabase/tap/turso
+
+# Login
+turso auth login
+
+# Crear database
+turso db create cmp-memory
+
+# Obtener URL
+turso db show cmp-memory --url
+# → libsql://cmp-memory-username.turso.io
+
+# Crear token
+turso db tokens create cmp-memory
+```
+
+### Configuración
+
+```typescript
+// src/db/turso-client.ts
+import { createClient } from '@libsql/client'
+import { drizzle } from 'drizzle-orm/libsql'
+
+export function createTursoDB() {
+  const client = createClient({
+    url: process.env.TURSO_DATABASE_URL!,
+    authToken: process.env.TURSO_AUTH_TOKEN!
+  })
+
+  return drizzle(client)
+}
+```
+
+### Variables de Entorno
+
+```env
+TURSO_DATABASE_URL=libsql://cmp-memory-username.turso.io
+TURSO_AUTH_TOKEN=eyJ...
+```
+
+## Upstash Vector
+
+**Propósito**: Búsqueda semántica de memorias y contexto.
+
+### Free Tier
+- 200M vectors
+- 1GB data/metadata
+- 10K queries/día
+- Built-in embeddings
+
+### Setup
+
+```bash
+# Crear en dashboard: https://console.upstash.com/vector
+# Obtener UPSTASH_VECTOR_REST_URL y UPSTASH_VECTOR_REST_TOKEN
+```
+
+### Configuración
+
+```typescript
+// src/db/vector-client.ts
+import { Index } from '@upstash/vector'
+
+export const vectorIndex = new Index({
+  url: process.env.UPSTASH_VECTOR_REST_URL!,
+  token: process.env.UPSTASH_VECTOR_REST_TOKEN!
+})
+
+// Insertar con embedding automático
+await vectorIndex.upsert({
+  id: 'mem_123',
+  data: 'Este es el contenido de la memoria...',
+  metadata: {
+    type: 'memory',
+    domain: 'video-studio',
+    createdAt: new Date().toISOString()
+  }
+})
+
+// Buscar por similitud
+const results = await vectorIndex.query({
+  data: 'buscar memorias sobre video',
+  topK: 5,
+  includeMetadata: true
+})
+```
+
+### Variables de Entorno
+
+```env
+UPSTASH_VECTOR_REST_URL=https://abc-xyz.upstash.io
+UPSTASH_VECTOR_REST_TOKEN=AXxx...
+```
+
+## Upstash Redis
+
+**Propósito**: Cache de configuración y sesiones activas.
+
+### Free Tier
+- 10K commands/día
+- 256MB storage
+- Global replication
+
+### Setup
+
+```bash
+# Crear en dashboard: https://console.upstash.com/redis
+# Obtener UPSTASH_REDIS_REST_URL y UPSTASH_REDIS_REST_TOKEN
+```
+
+### Configuración
+
+```typescript
+// src/db/redis-client.ts
+import { Redis } from '@upstash/redis'
+
+export const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!
+})
+
+// Cache de config (TTL 1 hora)
+await redis.set('config:SWARMSCALE', config, { ex: 3600 })
+
+// Leer config
+const cached = await redis.get('config:SWARMSCALE')
+
+// Sesiones activas
+await redis.hset('sessions:active', {
+  [sessionId]: JSON.stringify(sessionData)
+})
+```
+
+### Variables de Entorno
+
+```env
+UPSTASH_REDIS_REST_URL=https://def-uvw.upstash.io
+UPSTASH_REDIS_REST_TOKEN=AYyy...
+```
+
+## Migración desde PlanetScale/Railway
+
+### Estrategia
+
+1. **Fase 1**: Dual-write (escribir a ambos)
+2. **Fase 2**: Read from Turso, write to both
+3. **Fase 3**: Full migration, keep PlanetScale as backup
+
+### Script de Migración
+
+```typescript
+// scripts/migrate-to-turso.ts
+import { db as planetscale } from './db/planetscale'
+import { db as turso } from './db/turso'
+
+async function migrate() {
+  console.log('Fetching memories from PlanetScale...')
+
+  const memories = await planetscale.query.devItems.findMany({
+    where: eq(devItems.system, 'SWARMSCALE')
+  })
+
+  console.log(`Found ${memories.length} memories`)
+
+  // Batch insert to Turso
+  for (const batch of chunk(memories, 100)) {
+    await turso.insert(devItems).values(batch)
+    console.log(`Migrated ${batch.length} items`)
+  }
+
+  console.log('Migration complete!')
+}
+```
+
+## Costos Estimados
+
+| Uso | Turso | Vector | Redis | Total |
+|-----|-------|--------|-------|-------|
+| Desarrollo | $0 | $0 | $0 | **$0** |
+| Producción pequeña | $0 | $0 | $0 | **$0** |
+| Producción media | $4.99 | $0 | $0 | **$4.99** |
+| Producción alta | $29 | $60 | $10 | **$99** |
+
+## Configuración Completa
+
+```env
+# .env.cloud
+
+# Turso (SQLite)
+TURSO_DATABASE_URL=libsql://cmp-memory-username.turso.io
+TURSO_AUTH_TOKEN=eyJ...
+
+# Upstash Vector
+UPSTASH_VECTOR_REST_URL=https://abc-xyz.upstash.io
+UPSTASH_VECTOR_REST_TOKEN=AXxx...
+
+# Upstash Redis
+UPSTASH_REDIS_REST_URL=https://def-uvw.upstash.io
+UPSTASH_REDIS_REST_TOKEN=AYyy...
+
+# Embeddings (para generar si no usas built-in de Upstash)
+OPENAI_API_KEY=sk-...
+```
+
+## Package Dependencies
+
+```json
+{
+  "dependencies": {
+    "@libsql/client": "^0.5.0",
+    "@upstash/vector": "^1.0.0",
+    "@upstash/redis": "^1.28.0",
+    "drizzle-orm": "^0.30.0"
+  }
+}
+```
+
+## Fallback Strategy
+
+Si un servicio falla, tener fallback:
+
+```typescript
+async function getMemories(query: string) {
+  try {
+    // Primary: Upstash Vector (semantic search)
+    return await vectorIndex.query({ data: query, topK: 10 })
+  } catch (error) {
+    console.error('Vector search failed, falling back to SQL')
+
+    // Fallback: Turso (SQL LIKE search)
+    return await turso.query.devItems.findMany({
+      where: like(devItems.content, `%${query}%`),
+      limit: 10
+    })
+  }
+}
+```

package/standards/mcp/server-design.md

@@ -0,0 +1,243 @@
+# Diseño de Servidores MCP
+
+## Estructura Básica
+
+Un servidor MCP expone **herramientas** (tools) y **recursos** (resources) a Claude Code.
+
+```
+mcp-server/
+├── src/
+│   ├── index.ts           # Entry point
+│   ├── server.ts          # MCP server setup
+│   ├── tools/             # Tool definitions
+│   │   ├── index.ts
+│   │   └── [tool-name].ts
+│   ├── resources/         # Resource handlers
+│   │   └── index.ts
+│   └── utils/             # Shared utilities
+├── package.json
+└── README.md
+```
+
+## Configuración del Server
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+const server = new Server(
+  {
+    name: 'my-mcp-server',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  }
+)
+
+// Registrar handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [/* tool definitions */]
+}))
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  // Handle tool calls
+})
+
+// Conectar
+const transport = new StdioServerTransport()
+await server.connect(transport)
+```
+
+## Definición de Tools
+
+### Estructura de una Tool
+
+```typescript
+{
+  name: 'tool_name',           // snake_case
+  description: 'Qué hace',     // Conciso, <100 chars
+  inputSchema: {
+    type: 'object',
+    properties: {
+      param1: {
+        type: 'string',
+        description: 'Para qué sirve'
+      }
+    },
+    required: ['param1']
+  }
+}
+```
+
+### Nombres de Tools
+
+- **snake_case**: `memory_search`, `task_create`
+- **Prefijo del dominio**: `memory_*`, `pattern_*`, `task_*`
+- **Verbos claros**: `create`, `get`, `list`, `update`, `delete`, `search`
+
+```typescript
+// BIEN
+'memory_search'
+'memory_write'
+'task_start'
+'pattern_detect'
+
+// MAL
+'searchMemory'    // No camelCase
+'mem_srch'        // No abreviaciones
+'doSearch'        // Verbo genérico
+```
+
+### Respuestas de Tools
+
+```typescript
+// Éxito
+return {
+  content: [
+    {
+      type: 'text',
+      text: JSON.stringify(result, null, 2)
+    }
+  ]
+}
+
+// Error
+return {
+  content: [
+    {
+      type: 'text',
+      text: `Error: ${error.message}`
+    }
+  ],
+  isError: true
+}
+```
+
+## Manejo de Errores
+
+```typescript
+async function handleToolCall(name: string, args: unknown) {
+  try {
+    // Validar input
+    const validated = schema.parse(args)
+
+    // Ejecutar operación
+    const result = await executeOperation(validated)
+
+    return { content: [{ type: 'text', text: JSON.stringify(result) }] }
+
+  } catch (error) {
+    if (error instanceof ZodError) {
+      return {
+        content: [{ type: 'text', text: `Invalid input: ${error.message}` }],
+        isError: true
+      }
+    }
+
+    // Log para debugging, respuesta limpia para Claude
+    console.error('Tool error:', error)
+    return {
+      content: [{ type: 'text', text: `Operation failed: ${error.message}` }],
+      isError: true
+    }
+  }
+}
+```
+
+## Resources
+
+Los resources son datos que Claude puede leer (contexto estático).
+
+```typescript
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [
+    {
+      uri: 'memory://recent',
+      name: 'Recent Memories',
+      description: 'Last 10 memories created',
+      mimeType: 'application/json'
+    }
+  ]
+}))
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params
+
+  if (uri === 'memory://recent') {
+    const memories = await getRecentMemories()
+    return {
+      contents: [{
+        uri,
+        mimeType: 'application/json',
+        text: JSON.stringify(memories)
+      }]
+    }
+  }
+})
+```
+
+## Testing
+
+```typescript
+import { describe, it, expect } from 'vitest'
+
+describe('MCP Server', () => {
+  it('should list tools', async () => {
+    const result = await server.handleRequest({
+      method: 'tools/list'
+    })
+    expect(result.tools).toContainEqual(
+      expect.objectContaining({ name: 'memory_search' })
+    )
+  })
+
+  it('should handle tool call', async () => {
+    const result = await server.handleRequest({
+      method: 'tools/call',
+      params: {
+        name: 'memory_search',
+        arguments: { query: 'test' }
+      }
+    })
+    expect(result.isError).toBeFalsy()
+  })
+})
+```
+
+## Configuración en Claude Code
+
+```json
+// .claude/mcp.json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "node",
+      "args": ["path/to/server/dist/index.js"],
+      "env": {
+        "DATABASE_URL": "..."
+      }
+    }
+  }
+}
+```
+
+## Best Practices
+
+1. **Tools atómicas** - Una tool hace una cosa bien
+2. **Descripciones claras** - Claude decide basándose en la descripción
+3. **Validación con Zod** - Siempre validar input
+4. **Respuestas estructuradas** - JSON cuando hay datos complejos
+5. **Errores informativos** - Ayudar a Claude a entender qué falló
+6. **Logs en stderr** - No contaminar stdout (usado por MCP)
+
+```typescript
+// Usar stderr para logs
+console.error('[DEBUG] Processing request...')
+
+// stdout está reservado para MCP protocol
+// NO usar console.log para debugging
+```