ARCHITECTURE.md•5.44 kB
# 🏗️ Arquitectura Modular - Advanced Trello MCP Server
## 📁 Estructura del Proyecto
```
src/
├── index.ts # 🚀 Punto de entrada del MCP Server
├── types/
│ └── common.ts # 🔧 Tipos TypeScript comunes
├── utils/
│ └── api.ts # 🛠️ Utilidades para llamadas API
└── tools/ # 📦 Módulos de herramientas por API
├── boards.ts # 🏁 Boards API (1 herramienta)
├── lists.ts # 📋 Lists API (9 herramientas)
├── cards.ts # 🎫 Cards API (10 herramientas)
├── labels.ts # 🏷️ Labels API (8 herramientas)
└── actions.ts # ⚡ Actions API (4+ herramientas)
```
## 🎯 Principios de la Arquitectura
### 1. **Separación de Responsabilidades**
- **`index.ts`**: Solo punto de entrada y configuración del servidor
- **`tools/`**: Cada API de Trello en su propio módulo
- **`types/`**: Definiciones TypeScript reutilizables
- **`utils/`**: Funciones auxiliares compartidas
### 2. **Modularidad por Funcionalidad**
Cada módulo de `tools/` agrupa herramientas relacionadas:
```typescript
// tools/labels.ts
export function registerLabelsTools(server: McpServer, credentials: TrelloCredentials) {
// 8 herramientas de Labels API
server.tool('create-label', ...);
server.tool('get-label', ...);
server.tool('update-label', ...);
// ...
}
```
### 3. **Tipos Centralizados**
```typescript
// types/common.ts
export interface TrelloCredentials {
apiKey: string;
apiToken: string;
}
export const TrelloColorEnum = z.enum(['yellow', 'purple', 'blue', ...]);
```
### 4. **Utilidades Reutilizables**
```typescript
// utils/api.ts
export async function trelloGet(endpoint: string, credentials: TrelloCredentials) {
// Lógica común para GET requests
}
```
## 📊 Beneficios de la Modularización
### ✅ **Mantenibilidad**
- Cada API es independiente y fácil de mantener
- Cambios en una API no afectan otras
- Código más legible y organizado
### ✅ **Escalabilidad**
- Fácil agregar nuevas APIs (Boards, Members, Organizations)
- Cada módulo puede crecer independientemente
- Preparado para 182 herramientas totales
### ✅ **Colaboración**
- Múltiples desarrolladores pueden trabajar en APIs diferentes
- Conflictos de merge minimizados
- Responsabilidades claras por módulo
### ✅ **Testing**
- Tests unitarios por módulo
- Mocking más sencillo
- Cobertura específica por API
### ✅ **Performance**
- Lazy loading posible en el futuro
- Imports optimizados
- Bundle splitting preparado
## 🔄 Migración Realizada
### Antes (Monolítico)
```
src/
└── index.ts (2,408 líneas, 50KB)
├── 44 herramientas mezcladas
├── Tipos inline
├── Lógica API duplicada
└── Difícil de mantener
```
### Después (Modular)
```
src/
├── index.ts (114 líneas, 3KB) ✨
├── types/common.ts (60 líneas)
├── utils/api.ts (149 líneas)
└── tools/ (5 módulos especializados)
├── boards.ts (46 líneas)
├── lists.ts (539 líneas)
├── cards.ts (521 líneas)
├── labels.ts (427 líneas)
└── actions.ts (249 líneas)
```
## 🚀 Cómo Agregar Nuevas APIs
### 1. Crear Módulo
```typescript
// src/tools/members.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { TrelloCredentials } from '../types/common.js';
export function registerMembersTools(server: McpServer, credentials: TrelloCredentials) {
server.tool('get-member', ...);
server.tool('update-member', ...);
// ...
}
```
### 2. Registrar en Index
```typescript
// src/index.ts
import { registerMembersTools } from './tools/members.js';
// ...
registerMembersTools(server, credentials);
```
### 3. Compilar y Probar
```bash
npm run build
npm run dev
```
## 📈 Roadmap de Expansión
Con esta arquitectura modular estamos preparados para:
### **Fase 2 - Boards API Completa** (8 herramientas)
- `tools/boards.ts` → Expandir con todas las herramientas
### **Fase 3 - Members API** (12 herramientas)
- `tools/members.ts` → Nuevo módulo
### **Fase 4 - Organizations API** (15 herramientas)
- `tools/organizations.ts` → Nuevo módulo
### **Fase 5 - Advanced APIs** (100+ herramientas)
- `tools/checklists.ts`
- `tools/search.ts`
- `tools/webhooks.ts`
- `tools/customfields.ts`
## 🔧 Herramientas de Desarrollo
### Compilación
```bash
npm run build # Compila TypeScript → JavaScript
npm run dev # Modo desarrollo con watch
```
### Estructura de Archivos
```bash
# Backup del archivo original
src/index.original.ts # Archivo monolítico original (2,408 líneas)
# Nueva estructura modular
src/index.ts # Punto de entrada limpio (114 líneas)
src/tools/ # Módulos especializados
src/types/ # Tipos reutilizables
src/utils/ # Utilidades comunes
```
## 🎉 Resultado Final
### **Estado Actual**: 44 herramientas distribuidas en 5 módulos
### **Arquitectura**: Modular, escalable, mantenible
### **Cobertura API**: ~40% de Trello API
### **Preparado para**: 182 herramientas totales (100% cobertura)
---
*Esta arquitectura modular es la base sólida para convertir el Advanced Trello MCP Server en la herramienta más completa para integración con Trello API.*