agent-master-devsecops 3.9.0 → 5.1.0

package/scripts/mcp/server.js

@@ -0,0 +1,408 @@
+/**
+ * scripts/mcp/server.js
+ * 
+ * Servidor MCP Nativo (Model Context Protocol) — Dispatcher Assíncrono Concorrente
+ * Compatível com a especificação JSON-RPC 2.0 / MCP 2024-11-05.
+ * Suporta execução síncrona e assíncrona não-bloqueante (Promise/setImmediate),
+ * injeção de streams para testes, auditoria oficial OASIS SARIF v2.1.0 e resiliência a falhas.
+ * 
+ * Versão: 5.1.0 Enterprise
+ */
+
+'use strict';
+
+const readline = require('node:readline');
+const { version: PKG_VERSION } = require('../../package.json');
+const { createSarifReport } = require('../core/sarif_engine.js');
+
+const {
+  TOOLS,
+  TOOL_PROFILES,
+  getActiveTools,
+  setMcpProfile,
+  getActiveProfile
+} = require('./tools_registry.js');
+
+const {
+  ResourcesRegistry,
+  RESOURCES,
+  handleResourcesList,
+  handleResourceRead,
+  handleResourceReadAsync
+} = require('./resources_registry.js');
+
+const {
+  handleToolCall,
+  handleToolCallAsync
+} = require('./tool_handlers.js');
+
+const PROTOCOL_VERSION = '2024-11-05';
+const JSONRPC_VERSION = '2.0';
+const DEFAULT_SERVER_NAME = 'agent-master-devsecops-mcp';
+
+/**
+ * Classe Canônica McpServer — Núcleo do Servidor Model Context Protocol
+ */
+class McpServer {
+  constructor(options = {}) {
+    this.serverName = options.serverName || DEFAULT_SERVER_NAME;
+    this.protocolVersion = options.protocolVersion || PROTOCOL_VERSION;
+    this.pkgVersion = options.pkgVersion || PKG_VERSION;
+    this.input = options.input || process.stdin;
+    this.output = options.output || process.stdout;
+    this.rl = null;
+    this.isRunning = false;
+    this.metrics = {
+      requestsTotal: 0,
+      errorsTotal: 0,
+      startedAt: new Date().toISOString()
+    };
+  }
+
+  static get PROTOCOL_VERSION() {
+    return PROTOCOL_VERSION;
+  }
+
+  static get JSONRPC_VERSION() {
+    return JSONRPC_VERSION;
+  }
+
+  static get SERVER_NAME() {
+    return DEFAULT_SERVER_NAME;
+  }
+
+  /**
+   * Responde ao handshake de inicialização MCP
+   */
+  handleInitialize(id) {
+    return {
+      jsonrpc: JSONRPC_VERSION,
+      id: id !== undefined ? id : null,
+      result: {
+        protocolVersion: this.protocolVersion,
+        capabilities: {
+          tools: {},
+          resources: {}
+        },
+        serverInfo: {
+          name: this.serverName,
+          version: this.pkgVersion
+        }
+      }
+    };
+  }
+
+  /**
+   * Lista as ferramentas disponíveis conforme o perfil ativo
+   */
+  handleToolsList(id) {
+    return {
+      jsonrpc: JSONRPC_VERSION,
+      id: id !== undefined ? id : null,
+      result: {
+        tools: getActiveTools()
+      }
+    };
+  }
+
+  /**
+   * Despachante unificado de mensagens JSON-RPC 2.0 (DRY: centraliza roteamento síncrono e assíncrono)
+   */
+  dispatch(message, { isAsync = false } = {}) {
+    if (!message || typeof message !== 'object' || Array.isArray(message)) {
+      this.metrics.errorsTotal++;
+      return {
+        jsonrpc: JSONRPC_VERSION,
+        id: null,
+        error: {
+          code: -32600,
+          message: 'Invalid Request: O payload deve ser um objeto JSON-RPC 2.0 válido.'
+        }
+      };
+    }
+
+    const { id, method, params } = message;
+    this.metrics.requestsTotal++;
+
+    // Notificações oficiais MCP: não produzem resposta
+    if (method === 'notifications/initialized' || method === 'notifications/cancelled') {
+      return null;
+    }
+
+    // Ping nativo do protocolo
+    if (method === 'ping') {
+      return {
+        jsonrpc: JSONRPC_VERSION,
+        id: id !== undefined ? id : null,
+        result: {}
+      };
+    }
+
+    // Handshake de inicialização
+    if (method === 'initialize') {
+      return this.handleInitialize(id);
+    }
+
+    // Catálogo de ferramentas
+    if (method === 'tools/list') {
+      return this.handleToolsList(id);
+    }
+
+    // Execução de ferramenta
+    if (method === 'tools/call') {
+      return isAsync
+        ? handleToolCallAsync(id, params)
+        : handleToolCall(id, params);
+    }
+
+    // Catálogo de recursos
+    if (method === 'resources/list') {
+      return handleResourcesList(id);
+    }
+
+    // Leitura de recurso
+    if (method === 'resources/read') {
+      return isAsync
+        ? handleResourceReadAsync(id, params)
+        : handleResourceRead(id, params);
+    }
+
+    // Método desconhecido
+    this.metrics.errorsTotal++;
+    return {
+      jsonrpc: JSONRPC_VERSION,
+      id: id !== undefined ? id : null,
+      error: {
+        code: -32601,
+        message: `Método não suportado: ${method}`
+      }
+    };
+  }
+
+  /**
+   * Processamento síncrono de mensagens JSON-RPC
+   */
+  processMessage(message) {
+    return this.dispatch(message, { isAsync: false });
+  }
+
+  /**
+   * Processamento assíncrono não-bloqueante de mensagens JSON-RPC
+   */
+  async processMessageAsync(message) {
+    const res = this.dispatch(message, { isAsync: true });
+    return res instanceof Promise ? await res : res;
+  }
+
+  /**
+   * Inicializa o loop de escuta stdio via interface readline
+   */
+  start(options = {}) {
+    if (this.isRunning && this.rl) {
+      return this;
+    }
+
+    const input = options.input || this.input || process.stdin;
+    const output = options.output || this.output || process.stdout;
+
+    this.rl = readline.createInterface({
+      input,
+      output,
+      terminal: false
+    });
+
+    this.isRunning = true;
+
+    this.rl.on('line', (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) return;
+
+      setImmediate(async () => {
+        try {
+          const request = JSON.parse(trimmed);
+          const response = await this.processMessageAsync(request);
+          if (response) {
+            output.write(JSON.stringify(response) + '\n');
+          }
+        } catch (err) {
+          this.metrics.errorsTotal++;
+          const errResponse = {
+            jsonrpc: JSONRPC_VERSION,
+            id: null,
+            error: {
+              code: -32700,
+              message: 'Parse error: JSON inválido.',
+              data: String(err)
+            }
+          };
+          output.write(JSON.stringify(errResponse) + '\n');
+        }
+      });
+    });
+
+    this.rl.on('close', () => {
+      this.isRunning = false;
+    });
+
+    return this;
+  }
+
+  /**
+   * Encerra o servidor e libera streams e event loop
+   */
+  stop() {
+    if (this.rl) {
+      this.rl.close();
+      this.rl = null;
+    }
+    this.isRunning = false;
+    return this;
+  }
+
+  /**
+   * Auditoria de integridade do servidor MCP no padrão OASIS SARIF v2.1.0
+   */
+  auditToSarif() {
+    const findings = [];
+    const activeTools = getActiveTools();
+    const activeProfile = getActiveProfile();
+
+    // 1. Validação estrutural de Ferramentas
+    for (const tool of activeTools) {
+      if (!tool.name || typeof tool.name !== 'string') {
+        findings.push({
+          ruleId: 'RULE-MCP-001',
+          severity: 'CRITICAL',
+          filename: 'scripts/mcp/tools_registry.js',
+          line: 1,
+          column: 1,
+          snippet: JSON.stringify(tool).slice(0, 80),
+          message: 'Ferramenta MCP sem propriedade "name" obrigatória.',
+          remediation: 'Definir nome canônico da ferramenta conforme especificação MCP.'
+        });
+      }
+      if (!tool.inputSchema || typeof tool.inputSchema !== 'object' || tool.inputSchema.type !== 'object') {
+        findings.push({
+          ruleId: 'RULE-MCP-001',
+          severity: 'HIGH',
+          filename: 'scripts/mcp/tools_registry.js',
+          line: 1,
+          column: 1,
+          snippet: `tool: ${tool.name}`,
+          message: `Ferramenta MCP '${tool.name}' possui inputSchema inválido (deve ter type: 'object').`,
+          remediation: 'Ajustar schema JSON Schema da ferramenta.'
+        });
+      }
+    }
+
+    // 2. Validação estrutural de Recursos
+    for (const res of RESOURCES) {
+      if (!res.uri || !res.name || !res.mimeType) {
+        findings.push({
+          ruleId: 'RULE-MCP-002',
+          severity: 'HIGH',
+          filename: 'scripts/mcp/resources_registry.js',
+          line: 1,
+          column: 1,
+          snippet: `resource: ${res.uri}`,
+          message: `Recurso MCP '${res.uri || 'sem uri'}' possui propriedades obrigatórias ausentes.`,
+          remediation: 'Garantir que uri, name e mimeType estejam preenchidos.'
+        });
+      }
+    }
+
+    return createSarifReport({
+      toolName: 'agent-master-mcp-server',
+      toolVersion: this.pkgVersion,
+      findings,
+      properties: {
+        serverName: this.serverName,
+        protocolVersion: this.protocolVersion,
+        activeProfile,
+        activeToolsCount: activeTools.length,
+        totalResourcesCount: RESOURCES.length,
+        metrics: this.metrics
+      }
+    });
+  }
+
+  /**
+   * Emite relatório executivo em Markdown com métricas de execução e estado do servidor
+   */
+  formatReport() {
+    const activeTools = getActiveTools();
+    const activeProfile = getActiveProfile();
+
+    return [
+      `# Relatório Executivo: Servidor MCP (${this.serverName})`,
+      '',
+      `- **Versão do Pacote:** v${this.pkgVersion}`,
+      `- **Protocolo MCP:** ${this.protocolVersion}`,
+      `- **Perfil Ativo:** \`${activeProfile}\``,
+      `- **Ferramentas Ativas:** ${activeTools.length}`,
+      `- **Recursos Canônicos:** ${RESOURCES.length}`,
+      `- **Status:** ${this.isRunning ? 'RUNNING' : 'STANDBY'}`,
+      `- **Requisições Processadas:** ${this.metrics.requestsTotal}`,
+      `- **Erros Registrados:** ${this.metrics.errorsTotal}`,
+      ''
+    ].join('\n');
+  }
+
+  static auditToSarif() {
+    return defaultServerInstance.auditToSarif();
+  }
+
+  static formatReport() {
+    return defaultServerInstance.formatReport();
+  }
+}
+
+// Instância singleton padrão para retrocompatibilidade
+const defaultServerInstance = new McpServer();
+
+function processMessage(message) {
+  return defaultServerInstance.processMessage(message);
+}
+
+async function processMessageAsync(message) {
+  return await defaultServerInstance.processMessageAsync(message);
+}
+
+function startServer(options) {
+  return defaultServerInstance.start(options);
+}
+
+function stopServer() {
+  return defaultServerInstance.stop();
+}
+
+function handleInitialize(id) {
+  return defaultServerInstance.handleInitialize(id);
+}
+
+function handleToolsList(id) {
+  return defaultServerInstance.handleToolsList(id);
+}
+
+module.exports = {
+  McpServer,
+  defaultServerInstance,
+  processMessage,
+  processMessageAsync,
+  startServer,
+  stopServer,
+  handleInitialize,
+  handleToolsList,
+  handleResourcesList,
+  handleResourceRead,
+  TOOLS,
+  RESOURCES,
+  TOOL_PROFILES,
+  getActiveTools,
+  setMcpProfile,
+  getActiveProfile,
+  auditToSarif: () => McpServer.auditToSarif(),
+  formatReport: () => McpServer.formatReport(),
+  PROTOCOL_VERSION,
+  JSONRPC_VERSION
+};