MCP 服务器

Trae MCP Monitor

Enables monitoring and management of tasks via WebSocket events and authorization requests through MCP tools.

README

Trae MCP Monitor - TypeScript

Servidor MCP (Model Context Protocol) desarrollado en TypeScript que permite monitorear y gestionar tareas a través de un sistema de eventos y autorizaciones.

🚀 Características

✅ TypeScript: Código tipado con validación estricta
✅ Validación con Zod: Esquemas de validación robustos
✅ Streamable HTTP Transport: Compatible con el protocolo MCP
✅ WebSocket Monitor: Conexión en tiempo real con el monitor
✅ Logging estructurado: Sistema de logs con Winston
✅ Reconexión automática: Manejo resiliente de conexiones
✅ Cierre graceful: Manejo adecuado de señales del sistema
🐳 Optimizado para Docker/Dokploy: Listo para despliegue

📦 Instalación

# Instalar dependencias
pnpm install

# Compilar el proyecto
pnpm run build

# Iniciar el servidor
pnpm start

🛠️ Scripts disponibles

pnpm run build - Compila TypeScript a JavaScript
pnpm start - Inicia el servidor compilado
pnpm run dev - Modo desarrollo con recarga automática
pnpm run dev:run - Compila y ejecuta en modo desarrollo
pnpm test - Ejecuta las pruebas

⚙️ Configuración

El servidor utiliza las siguientes variables de entorno:

Variable	Descripción	Valor por Defecto	Requerido
`MONITOR_URL`	URL del WebSocket del backend	`ws://localhost:2200`	✅
`LOG_LEVEL`	Nivel de logging	`info`	❌
`USER_ID`	ID del usuario por defecto	`687a8418096ca32b8c045cf8`	❌
`SOURCE_NAME`	Nombre identificador del cliente	`trae-mcp-monitor`	❌
`PORT`	Puerto del servidor HTTP	`3000`	❌
`NODE_ENV`	Entorno de Node.js	`production`	❌

🔧 Herramientas MCP disponibles

1. send_task_event

Envía eventos de tareas al monitor.

Parámetros:

taskId (string): ID único de la tarea
event (string): Tipo de evento (start, progress, complete, error)
data (object, opcional): Datos adicionales del evento

Ejemplo:

{
  "taskId": "task-123",
  "event": "complete",
  "data": {
    "result": "Tarea completada exitosamente",
    "duration": 5000
  }
}

2. request_authorization

Solicita autorización para ejecutar una acción.

Parámetros:

action (string): Acción que requiere autorización
resource (string): Recurso sobre el que se ejecuta la acción
metadata (object, opcional): Metadatos adicionales

Ejemplo:

{
  "action": "delete_file",
  "resource": "/path/to/important/file.txt",
  "metadata": {
    "reason": "Limpieza de archivos temporales"
  }
}

🌐 Endpoints HTTP

POST /mcp

Endpoint principal para solicitudes MCP usando JSON-RPC 2.0.

Ejemplo de solicitud:

curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  http://localhost:3000/mcp

Respuesta:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "send_task_event",
        "description": "Envía eventos de tareas al monitor",
        "inputSchema": {
          "type": "object",
          "properties": {
            "taskId": {"type": "string"},
            "event": {"type": "string"},
            "data": {"type": "object"}
          },
          "required": ["taskId", "event"]
        }
      }
    ]
  }
}

GET /health

Endpoint de verificación de salud del servidor.

Respuesta:

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 3600,
  "version": "1.0.0"
}

GET /

Endpoint raíz con información básica del servidor.

🔗 Configuración en Trae IDE

Crea o actualiza el archivo mcp.json en tu proyecto:

{
  "servers": {
    "trae-monitor": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

🎯 Configuración en Claude Desktop

Edita el archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trae-monitor": {
      "command": "node",
      "args": ["/ruta/completa/al/proyecto/build/index.js"],
      "env": {
        "MONITOR_URL": "ws://localhost:2200",
        "LOG_LEVEL": "info",
        "USER_ID": "tu-user-id"
      }
    }
  }
}

🐳 Despliegue con Docker

# Construir imagen
docker build -t trae-mcp-monitor .

# Ejecutar contenedor
docker run -d \
  --name trae-mcp-monitor \
  -p 3000:3000 \
  -e MONITOR_URL=ws://tu-backend:2200 \
  -e LOG_LEVEL=info \
  -e NODE_ENV=production \
  trae-mcp-monitor

🌐 Despliegue en Dokploy

1. Crear Aplicación en Dokploy

Tipo: Application
Source: Git Repository
Build Command: pnpm install && pnpm run build
Start Command: pnpm start
Port: 3000

2. Variables de Entorno en Dokploy

MONITOR_URL=ws://tu-backend:2200
LOG_LEVEL=info
NODE_ENV=production
USER_ID=687a8418096ca32b8c045cf8
SOURCE_NAME=trae-mcp-monitor
PORT=3000

🔍 Desarrollo

Estructura del proyecto

mcp-monitor/
├── src/
│   └── index.ts          # Código fuente principal
├── build/                # Código compilado
├── package.json          # Configuración del proyecto
├── tsconfig.json         # Configuración de TypeScript
├── .env.example          # Variables de entorno de ejemplo
└── README.md            # Este archivo

Debugging

Para debuggear el servidor:

# Compilar en modo desarrollo
pnpm run dev

# Ejecutar con logs detallados
LOG_LEVEL=debug pnpm start

# Probar con Inspector MCP
npx @modelcontextprotocol/inspector build/index.js

Testing

# Ejecutar pruebas
pnpm test

# Probar endpoint manualmente
curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"send_task_event","arguments":{"taskId":"test-123","event":"start"}}}' \
  http://localhost:3000/mcp

📊 Logs y Monitoreo

El servidor genera logs estructurados en JSON:

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "level": "info",
  "message": "Conectado al monitor MCP exitosamente",
  "service": "trae-mcp-monitor",
  "url": "ws://localhost:2200"
}