php-universal-mcp-server/docs/API.md

Servidor MCP universal para desenvolvimento PHP e criação de sites em qualquer provedor de hospedagem

# PHP Universal MCP Server - Documentação da API

Este documento descreve detalhadamente a API do PHP Universal MCP Server.

## Índice

1. [MCPServer](#mcpserver)
2. [Providers](#providers)
3. [Configuração](#configuração)
4. [Comandos MCP](#comandos-mcp)
5. [Streams](#streams)
6. [Extensibilidade](#extensibilidade)

## MCPServer

### Criação do Servidor

```javascript
const { createServer } = require('php-universal-mcp-server');

const server = createServer({
  mode: 'auto',
  apiKey: 'sua-api-key', // Opcional
  fallbackEnabled: true,
  simulateResponses: true,
  providerType: 'auto'
});
```

### Métodos Principais

#### `start()`

Inicia o servidor MCP.

```javascript
const status = server.start();
// { status: 'running', provider: 'mock-provider', mode: 'offline', timestamp: '2025-03-22T15:30:00.000Z' }
```

#### `stop()`

Para o servidor MCP e finaliza todas as sessões ativas.

```javascript
const status = server.stop();
// { status: 'stopped', timestamp: '2025-03-22T15:35:00.000Z' }
```

#### `processCommand(command)`

Processa um comando do protocolo MCP.

```javascript
const result = server.processCommand({
  type: 'execute',
  payload: {
    action: 'createSite',
    domain: 'example.com'
  }
});
```

#### `registerHandler(commandType, handler)`

Registra um handler personalizado para um tipo de comando MCP.

```javascript
server.registerHandler('customCommand', (command) => {
  // Processa o comando personalizado
  return {
    status: 'success',
    message: 'Custom command processed'
  };
});
```

## Providers

### Providers Disponíveis

- **MockProvider**: Provider simulado para desenvolvimento offline.
- **cPanel**: Provider para integração com servidores cPanel.
- **PleskProvider**: Provider para integração com servidores Plesk.
- **AWSProvider**: Provider para integração com Amazon Web Services.
- **AzureProvider**: Provider para integração com Microsoft Azure.
- **GCPProvider**: Provider para integração com Google Cloud Platform.

### Métodos Comuns

Todos os providers implementam a seguinte interface:

#### `getName()`

Retorna o nome do provider.

#### `execute(payload)`

Executa uma operação síncrona.

#### `createStream(payload)`

Inicia uma operação assíncrona com eventos.

#### `closeStream(stream)`

Fecha um stream ativo.

#### `cancel(sessionId)`

Cancela uma operação em andamento.

#### `isAvailable()`

Verifica se o provider está disponível no ambiente atual.

#### `checkStatus()`

Retorna o status atual do provider.

## Configuração

O servidor MCP aceita as seguintes opções de configuração:

| Opção | Tipo | Descrição | Valor padrão |
|-------|------|-----------|--------------|
| `mode` | String | Modo de operação ('online', 'offline', 'auto') | `'auto'` |
| `apiKey` | String | Chave de API do provedor | `''` |
| `fallbackEnabled` | Boolean | Habilita fallback para mock quando APIs falham | `true` |
| `simulateResponses` | Boolean | Habilita respostas simuladas | `true` |
| `providerType` | String | Tipo de provedor ('cpanel', 'plesk', 'aws', 'azure', 'gcp', 'mock', 'auto') | `'auto'` |
| `mockDataDir` | String | Diretório para dados simulados | Process CWD + `/mock-data` |

### Configurações Específicas por Provider

#### cPanel
- `cpanelUsername`: Nome de usuário do cPanel
- `cpanelPassword`: Senha do cPanel
- `cpanelDomain`: Domínio do servidor cPanel
- `cpanelApiToken`: Token de API do cPanel (alternativa a username/password)
- `cpanelPort`: Porta do cPanel (padrão: 2083)
- `cpanelUseSSL`: Usar SSL para conexões (padrão: true)

#### Plesk
- `pleskHost`: Host do servidor Plesk (padrão: localhost)
- `pleskPort`: Porta do servidor Plesk (padrão: 8443)
- `pleskUsername`: Nome de usuário do Plesk
- `pleskPassword`: Senha do Plesk
- `pleskApiKey`: Chave de API do Plesk (alternativa a username/password)

#### AWS
- `awsAccessKeyId`: ID da chave de acesso da AWS
- `awsSecretAccessKey`: Chave de acesso secreta da AWS
- `awsRegion`: Região da AWS (padrão: us-east-1)

#### Azure
- `azureSubscriptionId`: ID da assinatura do Azure
- `azureTenantId`: ID do tenant do Azure
- `azureClientId`: ID do cliente/aplicativo do Azure
- `azureClientSecret`: Segredo do cliente do Azure
- `azureResourceGroup`: Nome do grupo de recursos do Azure
- `azureRegion`: Região do Azure (padrão: eastus)

#### GCP
- `gcpProjectId`: ID do projeto do GCP
- `gcpKeyFilePath`: Caminho para o arquivo de credenciais do GCP
- `gcpCredentials`: Credenciais do GCP como objeto (alternativa ao arquivo)
- `gcpRegion`: Região do GCP (padrão: us-central1)
- `gcpZone`: Zona do GCP (padrão: us-central1-a)

## Comandos MCP

O servidor implementa os seguintes comandos do protocolo MCP:

### `status`

Retorna o status atual do servidor.

**Payload:** Nenhum

**Resposta:**
```javascript
{
  status: 'success',
  serverStatus: 'running',
  provider: 'mock-provider',
  mode: 'offline',
  activeSessions: 0,
  timestamp: '2025-03-22T15:30:00.000Z'
}
```

### `execute`

Executa uma operação síncrona.

**Payload:**
```javascript
{
  action: String, // Ação a ser executada
  // Outros parâmetros específicos da ação
}
```

**Resposta:**
```javascript
{
  status: 'success',
  sessionId: 'session-id',
  result: {
    // Resultado da execução
  },
  timestamp: '2025-03-22T15:30:00.000Z'
}
```

### `stream`

Inicia uma operação assíncrona com eventos.

**Payload:**
```javascript
{
  action: String, // Ação a ser executada
  // Outros parâmetros específicos da ação
}
```

**Resposta:**
```javascript
{
  status: 'success',
  sessionId: 'session-id',
  timestamp: '2025-03-22T15:30:00.000Z'
}
```

### `cancel`

Cancela uma operação em andamento.

**Payload:**
```javascript
{
  sessionId: String // ID da sessão a ser cancelada
}
```

**Resposta:**
```javascript
{
  status: 'success',
  message: 'Session session-id canceled',
  timestamp: '2025-03-22T15:30:00.000Z'
}
```

### `terminate`

Finaliza o servidor.

**Payload:** Nenhum

**Resposta:**
```javascript
{
  status: 'stopped',
  timestamp: '2025-03-22T15:30:00.000Z'
}
```

## Streams

Os streams permitem operações assíncronas com eventos.

### Eventos de Stream

- **start**: Emitido quando o stream inicia.
- **data**: Emitido quando há novos dados disponíveis.
- **end**: Emitido quando o stream termina com sucesso.
- **close**: Emitido quando o stream é fechado pelo usuário.
- **cancel**: Emitido quando o stream é cancelado.

### Exemplo de Uso de Stream

```javascript
const streamResult = server.processCommand({
  type: 'stream',
  payload: {
    action: 'deployFiles',
    siteId: 'site_123',
    files: ['index.php', 'style.css']
  }
});

const { sessionId } = streamResult;
const stream = streamResult.stream;

stream.emitter.on('start', (data) => {
  console.log('Stream iniciado:', data);
});

stream.emitter.on('data', (data) => {
  console.log('Progresso:', data.progress + '%');
});

stream.emitter.on('end', (data) => {
  console.log('Stream finalizado:', data);
});
```

## Ações Suportadas

O servidor suporta as seguintes ações em todos os providers:

| Ação | Descrição | Parâmetros | Disponível em |
|------|-----------|------------|--------------|
| `createSite` | Cria um novo site | `domain`, `template`, `options` | Todos os providers |
| `uploadFile` | Envia um arquivo para o servidor | `path`, `content`, `options` | Todos os providers | 
| `getDomainInfo` | Obtém informações de um domínio | `domain` | Todos os providers |
| `deployFiles` | Implanta arquivos em um site | `siteId`, `files` | Todos os providers |
| `setupDatabase` | Cria e configura um banco de dados | `name`, `type`, `options` | Todos exceto Mock |
| `createVM` | Cria uma máquina virtual | `name`, `size`, `options` | AWS, Azure, GCP |

### Ações Específicas do Provider

#### cPanel
- `createEmailAccount`: Cria uma conta de e-mail
- `setupSSL`: Configura SSL para um domínio

#### Plesk
- `createSubscription`: Cria uma assinatura Plesk
- `manageDNS`: Gerencia registros DNS

#### AWS
- `createS3Bucket`: Cria um bucket S3
- `setupCloudFront`: Configura uma distribuição CloudFront

#### Azure
- `createAppService`: Cria um serviço de aplicativo
- `setupAzureCDN`: Configura CDN do Azure

#### GCP
- `setupGCEInstance`: Configura uma instância do GCE
- `deployToAppEngine`: Implanta para o App Engine

## Extensibilidade

### Criando um Provider Personalizado

```javascript
const { providers } = require('php-universal-mcp-server');
const { BaseProvider } = providers;

class MyCustomProvider extends BaseProvider {
  constructor(config) {
    super(config);
  }
  
  getName() {
    return 'my-custom-provider';
  }
  
  execute(payload) {
    // Implementação da execução
    return {
      success: true,
      data: {
        // Dados do resultado
      }
    };
  }
  
  createStream(payload) {
    // Implementação do stream
    const streamId = crypto.randomUUID();
    const emitter = new EventEmitter();
    
    // Lógica de stream
    
    return {
      id: streamId,
      emitter: emitter
    };
  }
  
  // Implementar os outros métodos da interface
  closeStream(stream) { /* ... */ }
  cancel(sessionId) { /* ... */ }
  isAvailable() { /* ... */ }
}

// Usar o provider personalizado
const server = createServer({
  providerType: 'custom'
});

// Registrar o provider personalizado
server._initProvider = function() {
  return new MyCustomProvider(this.config);
};
```

### Criando Comandos Personalizados

```javascript
server.registerHandler('customCommand', (command) => {
  // Processar o comando personalizado
  const { payload } = command;
  
  // Lógica de processamento
  
  return {
    status: 'success',
    message: 'Custom command processed',
    data: {
      // Dados da resposta
    }
  };
});

// Usar o comando personalizado
const result = server.processCommand({
  type: 'customCommand',
  payload: {
    // Dados específicos do comando
  }
});
```