CData Sync

Un servidor del Protocolo de Contexto de Modelo para CData Sync, que permite la replicación y transformación de datos.

Documentación

Servidor MCP de CData Sync

Un servidor de Protocolo de Contexto de Modelo (MCP) integral para CData Sync con soporte de transporte dual. Este servidor expone la API REST de CData Sync como herramientas MCP, lo que permite que asistentes de IA como Claude gestionen trabajos de sincronización de datos, conexiones y operaciones ETL.

Opciones de transporte:

stdio - Para uso de escritorio con la aplicación Claude Desktop
HTTP - Para implementaciones de servidor remoto y acceso a API

✨ Características

🔧 20 Herramientas MCP Consolidadas - Operaciones de lectura/escritura optimizadas para todos los tipos de entidades
🚀 Soporte de Transporte Dual - Tanto stdio (Claude Desktop) como HTTP Streamable (clientes web)
📡 Notificaciones en Tiempo Real - Monitoreo en vivo de ejecuciones de trabajos y llamadas API mediante Eventos Enviados por el Servidor
🏗️ Arquitectura Lista para Producción - TypeScript, manejo de errores, registro y seguridad integral de tipos
🔐 Múltiples Métodos de Autenticación - Soporte para tokens de API y autenticación básica
🌐 Soporte para Clientes Web - API HTTP RESTful con capacidades de transmisión
📊 Gestión de Trabajos - Ejecutar, monitorear y controlar trabajos de sincronización de datos
🔌 Gestión de Conexiones - Probar, crear y gestionar conexiones de datos
👥 Gestión de Usuarios - Manejar cuentas de usuario y permisos
📈 Historial y Registro - Acceder al historial de ejecuciones y registros detallados

🚀 Inicio Rápido

Requisitos Previos

Node.js 18+
Instancia de CData Sync en ejecución
Claude Desktop (para transporte stdio) o navegador web (para transporte HTTP)

Instalación

Clonar el repositorio

git clone https://github.com/CDataSoftware/cdata-sync-mcp-server.git
cd cdata-sync-mcp-server

Instalar dependencias
```
npm install
```
Compilar el proyecto
```
npm run build
```

Configurar variables de entorno

# Copy the example environment file
cp .env.example .env

# Edit with your CData Sync details
CDATA_BASE_URL="http://localhost:8181/api.rsc"
CDATA_AUTH_TOKEN="your-auth-token"
CDATA_WORKSPACE="your-workspace-uuid"  # Optional: scope operations to specific workspace
MCP_TRANSPORT_MODE="both"  # stdio, http, or both

🔌 Opciones de Transporte

Uso de Escritorio: Transporte Stdio (Claude Desktop)

El transporte stdio está diseñado para uso local de escritorio con la aplicación Claude Desktop. Este es el enfoque recomendado para desarrolladores individuales.

Configuración para Claude Desktop:

{
  "mcpServers": {
    "cdata-sync-server": {
      "command": "node",
      "args": ["/absolute/path/to/cdata-sync-mcp-server/dist/index.js"],
      "env": {
        "MCP_TRANSPORT_MODE": "stdio",
        "CDATA_AUTH_TOKEN": "your-token-here",
        "CDATA_BASE_URL": "http://localhost:8181/api.rsc",
        "CDATA_WORKSPACE": "your-workspace-uuid-here",
        "DISABLE_SSE": "true"
      }
    }
  }
}

Iniciar servidor solo-stdio:

npm run start:stdio

Uso de Servidor: Transporte HTTP (Implementaciones Remotas)

El transporte HTTP está diseñado para implementaciones de servidor donde el servidor MCP se ejecuta en una máquina remota y acepta solicitudes de API. Esto es ideal para:

Implementaciones de equipo
Entornos Docker/Kubernetes
Integración con aplicaciones web
Escenarios de acceso remoto

Iniciar servidor solo-HTTP:

npm run start:http

Puntos finales disponibles:

GET /mcp/v1/info - Información del servidor y protocolo
GET /mcp/v1/health - Verificación de estado
POST /mcp/v1/message - Enviar solicitudes MCP
GET /mcp/v1/stream - Eventos Enviados por el Servidor para actualizaciones en tiempo real

Ejemplo de uso de cliente HTTP:

// Connect to the server
const client = new MCPStreamableHttpClient('http://your-server:3000/mcp/v1');
await client.connect();

// List available tools
const tools = await client.listTools();

// Call a tool
const connections = await client.callTool('read_connections', {
  action: 'list',
  top: 5
});

// Set up real-time monitoring
client.onNotification = (method, params) => {
  console.log('Notification:', method, params);
};

Desarrollo: Transporte Dual

Para desarrollo y pruebas, puede ejecutar ambos transportes simultáneamente:

npm run start:both

Esto es útil para probar escenarios de escritorio y servidor durante el desarrollo.

🛠️ Herramientas Disponibles

Gestión de Conexiones

read_connections - Listar, contar, obtener detalles o probar conexiones
write_connections - Crear, actualizar o eliminar conexiones
get_connection_tables - Listar tablas en la conexión
get_table_columns - Obtener información del esquema de tablas

Gestión de Trabajos

read_jobs - Listar, contar, obtener detalles, estado, historial o registros
write_jobs - Crear, actualizar o eliminar trabajos
execute_job - Ejecutar un trabajo de sincronización inmediatamente
cancel_job - Detener trabajo en ejecución
execute_query - Ejecutar consultas SQL personalizadas

Gestión de Tareas

read_tasks - Listar, contar u obtener detalles de tareas
write_tasks - Crear, actualizar o eliminar tareas

Gestión de Transformaciones

read_transformations - Listar, contar u obtener detalles de transformaciones
write_transformations - Crear, actualizar o eliminar transformaciones

Gestión de Usuarios

read_users - Listar, contar u obtener detalles de usuarios
write_users - Crear o actualizar usuarios

Gestión de Solicitudes/Registros

read_requests - Listar, contar u obtener detalles de registros de solicitudes
write_requests - Eliminar registros de solicitudes

Gestión de Historial

read_history - Listar o contar registros de historial de ejecuciones

Gestión de Certificados

read_certificates - Listar certificados
write_certificates - Crear certificados

Gestión de Configuración

configure_sync_server - Obtener o actualizar configuración del servidor

📋 Patrones de Uso de Herramientas

Operaciones Basadas en Acciones

Todas las herramientas de lectura/escritura utilizan un parámetro action para especificar la operación:

Ejemplo: Lectura de conexiones

{
  "tool": "read_connections",
  "arguments": {
    "action": "list",
    "filter": "contains(Name,'prod')",
    "top": 10
  }
}

Ejemplo: Creación de una conexión

{
  "tool": "write_connections", 
  "arguments": {
    "action": "create",
    "name": "MyDatabase",
    "providerName": "System.Data.SqlClient",
    "connectionString": "Server=localhost;Database=test;"
  }
}

Monitoreo en Tiempo Real

El transporte HTTP proporciona notificaciones en tiempo real para:

Inicio/finalización de ejecución de herramientas
Progreso de ejecución de trabajos
Cambios de configuración
Notificaciones de errores

// Monitor all server events
const eventSource = new EventSource('http://localhost:3000/mcp/v1/stream');

eventSource.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  if (message.method === 'notifications/job_executed') {
    console.log('Job completed:', message.params);
  }
};

🔧 Desarrollo

Scripts de Desarrollo

# Start in development mode with both transports
npm run dev:both

# Start with stdio only
npm run dev:stdio

# Start with HTTP only
npm run dev:http

# Type checking
npm run typecheck

# Linting
npm run lint
npm run lint:fix

# Testing
npm test
npm run test:watch
npm run test:coverage

Variables de Entorno

Variable	Descripción	Predeterminado
`CDATA_BASE_URL`	URL base de la API de CData Sync	`http://localhost:8181/api.rsc`
`CDATA_AUTH_TOKEN`	Token de autenticación de API	-
`CDATA_USERNAME`	Nombre de usuario de autenticación básica (alternativa al token)	-
`CDATA_PASSWORD`	Contraseña de autenticación básica (alternativa al token)	-
`CDATA_WORKSPACE`	UUID del espacio de trabajo para limitar todas las operaciones (opcional)	-
`MCP_TRANSPORT_MODE`	Modo de transporte: `stdio`, `http` o `both`	`stdio`
`MCP_HTTP_PORT`	Puerto del transporte HTTP	`3000`
`MCP_HTTP_PATH`	Ruta base del transporte HTTP	`/mcp/v1`
`NODE_ENV`	Entorno de Node	`production`
`LOG_LEVEL`	Nivel de registro	`info`

🐳 Implementación

Docker

# Build image
docker build -t cdata-sync-mcp-server .

# Run with stdio transport
docker run -e CDATA_AUTH_TOKEN=your-token cdata-sync-mcp-server

# Run with HTTP transport
docker run -p 3000:3000 -e MCP_TRANSPORT_MODE=http -e CDATA_AUTH_TOKEN=your-token cdata-sync-mcp-server

Docker Compose

# Start with Docker Compose
docker-compose up -d cdata-sync-mcp-both

Kubernetes

# Deploy to Kubernetes
kubectl apply -f k8s/

Servicio Systemd

# Install as systemd service
sudo cp cdata-sync-mcp.service /etc/systemd/system/
sudo systemctl enable cdata-sync-mcp
sudo systemctl start cdata-sync-mcp

📡 Referencia de API HTTP

Información del Protocolo

GET /mcp/v1/info

{
  "protocol": "Model Context Protocol",
  "version": "2025-03-26", 
  "transport": "streamable-http",
  "endpoints": {
    "message": "http://localhost:3000/mcp/v1/message",
    "stream": "http://localhost:3000/mcp/v1/stream"
  }
}

Verificación de Estado

GET /mcp/v1/health

{
  "status": "healthy",
  "transport": "streamable-http",
  "timestamp": "2024-01-15T10:30:00Z",
  "pendingRequests": 0,
  "bufferedMessages": 0
}

Enviar Solicitud MCP

POST /mcp/v1/message

{
  "jsonrpc": "2.0",
  "id": "1", 
  "method": "tools/call",
  "params": {
    "name": "read_connections",
    "arguments": {
      "action": "list",
      "top": 5
    }
  }
}

Eventos en Tiempo Real

GET /mcp/v1/stream

Flujo de Eventos Enviados por el Servidor que proporciona notificaciones en tiempo real:

data: {"jsonrpc":"2.0","method":"notifications/tool_execution","params":{"tool":"read_connections","timestamp":"2024-01-15T10:30:00Z"}}

data: {"jsonrpc":"2.0","method":"notifications/job_executed","params":{"jobName":"TestJob","result":"success","timestamp":"2024-01-15T10:31:00Z"}}

🧪 Pruebas

Ejecución de Pruebas

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

Estructura de Pruebas

src/
├── __tests__/
│   ├── services/           # Service unit tests
│   ├── transport/          # Transport tests
│   ├── integration/        # Integration tests
│   └── utils/             # Utility tests

🤝 Contribuciones

Haga un fork del repositorio
Cree su rama de características (git checkout -b feature/amazing-feature)
Confirme sus cambios (git commit -m 'Add some amazing feature')
Envíe a la rama (git push origin feature/amazing-feature)
Abra una Solicitud de Extracción

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENCIA para más detalles.

🆘 Soporte

Documentación: Documentación completa de API disponible en el directorio docs
Problemas: Reporte errores y solicite funciones a través de Problemas de GitHub
Discusiones: Soporte comunitario a través de Comunidad CData

📚 Recursos Adicionales

Construido con ❤️ para el ecosistema MCP