CData Sync

Um servidor Model Context Protocol para CData Sync, permitindo replicação e transformação de dados.

Documentação

Servidor MCP CData Sync

Um servidor Model Context Protocol (MCP) abrangente para CData Sync com suporte a transporte duplo. Este servidor expõe a API REST do CData Sync como ferramentas MCP, permitindo que assistentes de IA como o Claude gerenciem trabalhos de sincronização de dados, conexões e operações de ETL.

Opções de Transporte:

stdio - Para uso em desktop com o aplicativo Claude Desktop
HTTP - Para implantações em servidores remotos e acesso via API

✨ Recursos

🔧 20 Ferramentas MCP Consolidadas - Operações de leitura/escrita simplificadas para todos os tipos de entidades
🚀 Suporte a Transporte Duplo - Tanto stdio (Claude Desktop) quanto HTTP Streamable (clientes web)
📡 Notificações em Tempo Real - Monitoramento ao vivo de execuções de trabalhos e chamadas de API via Server-Sent Events
🏗️ Arquitetura Pronta para Produção - TypeScript, tratamento de erros, registro de logs e segurança abrangente de tipos
🔐 Múltiplos Métodos de Autenticação - Suporte para tokens de API e autenticação básica
🌐 Suporte a Clientes Web - API HTTP RESTful com capacidades de streaming
📊 Gerenciamento de Trabalhos - Executar, monitorar e controlar trabalhos de sincronização de dados
🔌 Gerenciamento de Conexões - Testar, criar e gerenciar conexões de dados
👥 Gerenciamento de Usuários - Lidar com contas de usuário e permissões
📈 Histórico e Registros - Acessar histórico de execuções e registros detalhados

🚀 Início Rápido

Pré-requisitos

Node.js 18+
Instância do CData Sync em execução
Claude Desktop (para transporte stdio) ou navegador web (para transporte HTTP)

Instalação

Clone o repositório

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

Instale as dependências
```
npm install
```
Compile o projeto
```
npm run build
```

Configure as variáveis de ambiente

# 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

🔌 Opções de Transporte

Uso em Desktop: Transporte Stdio (Claude Desktop)

O transporte stdio é projetado para uso local em desktop com o aplicativo Claude Desktop. Esta é a abordagem recomendada para desenvolvedores individuais.

Configuração para o 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 somente stdio:

npm run start:stdio

Uso em Servidor: Transporte HTTP (Implantações Remotas)

O transporte HTTP é projetado para implantações em servidores onde o servidor MCP roda em uma máquina remota e aceita solicitações de API. Isso é ideal para:

Implantações em equipe
Ambientes Docker/Kubernetes
Integração com aplicações web
Cenários de acesso remoto

Iniciar servidor somente HTTP:

npm run start:http

Endpoints disponíveis:

GET /mcp/v1/info - Informações do servidor e do protocolo
GET /mcp/v1/health - Verificação de saúde
POST /mcp/v1/message - Enviar solicitações MCP
GET /mcp/v1/stream - Server-Sent Events para atualizações em tempo real

Exemplo 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);
};

Desenvolvimento: Transporte Duplo

Para desenvolvimento e testes, você pode executar ambos os transportes simultaneamente:

npm run start:both

Isso é útil para testar cenários de desktop e servidor durante o desenvolvimento.

🛠️ Ferramentas Disponíveis

Gerenciamento de Conexões

read_connections - Listar, contar, obter detalhes ou testar conexões
write_connections - Criar, atualizar ou excluir conexões
get_connection_tables - Listar tabelas na conexão
get_table_columns - Obter informações de esquema da tabela

Gerenciamento de Trabalhos

read_jobs - Listar, contar, obter detalhes, status, histórico ou registros
write_jobs - Criar, atualizar ou excluir trabalhos
execute_job - Executar um trabalho de sincronização imediatamente
cancel_job - Parar trabalho em execução
execute_query - Executar consultas SQL personalizadas

Gerenciamento de Tarefas

read_tasks - Listar, contar ou obter detalhes de tarefas
write_tasks - Criar, atualizar ou excluir tarefas

Gerenciamento de Transformações

read_transformations - Listar, contar ou obter detalhes de transformações
write_transformations - Criar, atualizar ou excluir transformações

Gerenciamento de Usuários

read_users - Listar, contar ou obter detalhes de usuários
write_users - Criar ou atualizar usuários

Gerenciamento de Solicitações/Registros

read_requests - Listar, contar ou obter detalhes de registros de solicitações
write_requests - Excluir registros de solicitações

Gerenciamento de Histórico

read_history - Listar ou contar registros de histórico de execuções

Gerenciamento de Certificados

read_certificates - Listar certificados
write_certificates - Criar certificados

Gerenciamento de Configuração

configure_sync_server - Obter ou atualizar configuração do servidor

📋 Padrões de Uso das Ferramentas

Operações Baseadas em Ação

Todas as ferramentas de leitura/escrita usam um parâmetro action para especificar a operação:

Exemplo: Lendo conexões

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

Exemplo: Criando uma conexão

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

Monitoramento em Tempo Real

O transporte HTTP fornece notificações em tempo real para:

Início/conclusão da execução de ferramentas
Progresso da execução de trabalhos
Alterações de configuração
Notificações de erro

// 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);
  }
};

🔧 Desenvolvimento

Scripts de Desenvolvimento

# 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

Variáveis de Ambiente

Variável	Descrição	Padrão
`CDATA_BASE_URL`	URL base da API do CData Sync	`http://localhost:8181/api.rsc`
`CDATA_AUTH_TOKEN`	Token de autenticação da API	-
`CDATA_USERNAME`	Nome de usuário para autenticação básica (alternativa ao token)	-
`CDATA_PASSWORD`	Senha para autenticação básica (alternativa ao token)	-
`CDATA_WORKSPACE`	UUID do workspace para escopo de todas as operações (opcional)	-
`MCP_TRANSPORT_MODE`	Modo de transporte: `stdio`, `http` ou `both`	`stdio`
`MCP_HTTP_PORT`	Porta do transporte HTTP	`3000`
`MCP_HTTP_PATH`	Caminho base do transporte HTTP	`/mcp/v1`
`NODE_ENV`	Ambiente do Node	`production`
`LOG_LEVEL`	Nível de registro de logs	`info`

🐳 Implantação

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/

Serviço 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

📡 Referência da API HTTP

Informações do 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"
  }
}

Verificação de Saúde

GET /mcp/v1/health

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

Enviar Solicitação MCP

POST /mcp/v1/message

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

Eventos em Tempo Real

GET /mcp/v1/stream

Fluxo de Server-Sent Events fornecendo notificações em tempo 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"}}

🧪 Testes

Executando Testes

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

Estrutura de Testes

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

🤝 Contribuição

Faça um fork do repositório
Crie sua branch de recurso (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add some amazing feature')
Envie para a branch (git push origin feature/amazing-feature)
Abra um Pull Request

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🆘 Suporte

Documentação: Documentação completa da API disponível no diretório docs
Problemas: Relate bugs e solicite recursos via GitHub Issues
Discussões: Suporte da comunidade via Comunidade CData

📚 Recursos Adicionais

Construído com ❤️ para o ecossistema MCP