cmp-standards 2.4.0 → 2.7.0

package/standards/mcp/server-design.md

@@ -1,243 +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
-```
+# 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
+```