VISO TRUST MCP Server

oficial

Acesse e gerencie seu programa de

Documentação

VISO TRUST MCP Server

Um servidor Model Context Protocol (MCP) para integrar as capacidades da API VISO TRUST com assistentes de IA.

Requisitos

  • Java 21+
  • Gradle
  • Docker (opcional para implantação em contêiner)
  • MCP Inspector (opcional para testes)

Configuração

Configuração da API VISO TRUST

As seguintes propriedades podem ser configuradas para a API VISO TRUST:

  • visotrust.api.base-url: A URL base para a API VISO TRUST (padrão: http://localhost:8080)
  • visotrust.api.token: Seu token de API da plataforma VISO TRUST (obrigatório)
  • visotrust.api.timeout: Tempo limite da requisição API em milissegundos (padrão: 30000)
  • visotrust.api.connect-timeout: Tempo limite de conexão API em milissegundos (padrão: 5000)

Para informações sobre como gerar um token de API para a variável de ambiente visotrust.api.token, consulte a documentação de suporte VISO TRUST.

Perfis de Aplicação

Esta aplicação suporta perfis Spring Boot para habilitar diferentes configurações para diferentes cenários de implantação.

Perfil Remoto

O perfil remote é projetado especificamente para suporte MCP remoto usando Server-Sent Events (SSE). Este perfil configura a aplicação para funcionar de forma otimizada em ambientes distribuídos onde o servidor MCP precisa se comunicar com clientes remotos através de conexões HTTP/SSE.

Principais diferenças no perfil remoto:

  • Configurado para comunicação baseada em SSE em vez de I/O padrão
  • Configurações de servidor otimizadas para conexões de clientes remotos
  • Logging aprimorado para depuração distribuída

Como ativar o perfil remoto:

Ao executar com Java diretamente:

java -jar viso-mcp-server-<version>.jar --spring.profiles.active=remote

Ao executar com Gradle:

./gradlew bootRun --args="--spring.profiles.active=remote"

Ao usar Docker:

docker run -i --rm \
  -e VISOTRUST_API_TOKEN=<your-api-token> \
  -e SPRING_PROFILES_ACTIVE=remote \
  viso-mcp-server

Quando usar o perfil remoto:

  • Ao implantar o servidor MCP em um servidor remoto ou ambiente de nuvem
  • Quando os clientes se conectarão via HTTP/SSE em vez de stdio direto
  • Quando você precisa de logging e monitoramento aprimorados para implantações distribuídas
  • Ao integrar com assistentes de IA baseados na web que exigem comunicação SSE

Para desenvolvimento local e comunicação stdio direta, use o perfil padrão (sem necessidade de especificação de perfil).

Instalação

Instalação Rápida

Clique em um dos botões abaixo para instalar o VISO MCP Server no VS Code:

Install with Docker in VS Code Install with Docker in VS Code Insiders

Configuração Manual com VS Code

Adicione o seguinte bloco JSON ao seu arquivo de Configurações do Usuário (JSON) no VS Code. Você pode fazer isso pressionando Ctrl + Shift + P e digitando Preferences: Open User Settings (JSON).

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "viso_baseurl",
        "description": "VISO TRUST API Base URL",
        "default": "https://app.visotrust.com"
      },
      {
        "type": "promptString",
        "id": "viso_token",
        "description": "VISO TRUST API Token",
        "password": true
      }
    ],
    "servers": {
      "viso-mcp": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "VISOTRUST_API_TOKEN",
          "-e",
          "VISOTRUST_API_BASEURL",
          "visotrustai/viso-mcp-server:latest"
        ],
        "env": {
          "VISOTRUST_API_BASEURL": "${input:viso_baseurl}",
          "VISOTRUST_API_TOKEN": "${input:viso_token}"
        }
      }
    }
  }
}

Opcionalmente, você pode adicionar um exemplo semelhante (ou seja, sem a chave mcp) a um arquivo chamado .vscode/mcp.json no seu espaço de trabalho. Isso permitirá que você compartilhe a configuração com outros.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "viso_baseurl",
      "description": "VISO TRUST API Base URL",
      "default": "https://app.visotrust.com"
    },
    {
      "type": "promptString",
      "id": "viso_token",
      "description": "VISO TRUST API Token",
      "password": true
    }
  ],
  "servers": {
    "viso-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "VISOTRUST_API_TOKEN",
        "-e",
        "VISOTRUST_API_BASEURL",
        "visotrustai/viso-mcp-server:latest"
      ],
      "env": {
        "VISOTRUST_API_BASEURL": "${input:viso_baseurl}",
        "VISOTRUST_API_TOKEN": "${input:viso_token}"
      }
    }
  }
}

Uso com Claude Desktop e outros Clientes MCP

Configuração Docker

{
    "mcpServers": {
        "viso-mcp": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e", "VISOTRUST_API_TOKEN",
                "-e", "VISOTRUST_API_BASEURL",
                "visotrustai/viso-mcp-server:latest"
            ],
            "env": {
                "VISOTRUST_API_TOKEN": "<your-api-token>",
                "VISOTRUST_API_BASEURL": "https://app.visotrust.com"
            }
        }
    }
}

Configuração Java

{
    "mcpServers": {
        "viso-mcp": {
            "command": "java",
            "args": [
                "-jar",
                "viso-mcp-server-<version>.jar",
                "--port",
                "8080",
                "--host",
                "localhost"
            ],
            "env": {
                "JAVA_TOOL_OPTIONS": "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005",
                "VISOTRUST_API_TOKEN": "<your-api-token>",
                "VISOTRUST_API_BASEURL": "https://app.visotrust.com"
            }
        }
    }
}

Nota: A variável de ambiente JAVA_TOOL_OPTIONS é usada para definir as opções da JVM para depuração remota. O endereço e a porta podem ser alterados conforme necessário.

💻 Desenvolvimento

Configuração Docker

Construir Imagem Docker

docker build -t viso-mcp-server .

Executar Contêiner Docker

docker run -i --rm -e VISOTRUST_API_TOKEN=<your-api-token> viso-mcp-server

Depuração

Instalar MCP Inspector

npm -g install @modelcontextprotocol/inspector

Executar MCP Inspector para Testes

  1. Construir Arquivo Jar do Servidor MCP
./gradlew bootJar
  1. Executar MCP Inspector
npx @modelcontextprotocol/inspector \
    -e JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=\*:5005 \
    -e VISOTRUST_API_TOKEN=<your-api-token> \
    java -jar build/libs/viso-mcp-server-<version>.jar \
    --port 8080 --host localhost

Substitua <version> pela versão atual do projeto (por exemplo, 1.0.0 ou a versão do último lançamento).

Pipeline CI/CD

Este projeto usa GitHub Actions para integração e implantação contínuas. O fluxo de trabalho inclui os seguintes jobs:

Lint

Verifica a formatação do código usando Spotless:

./gradlew spotlessCheck

Build

Constrói a aplicação e cria um arquivo JAR:

./gradlew build

Publish

Quando um novo lançamento é criado:

  1. Atualiza a versão do projeto no build.gradle para corresponder à tag de lançamento
  2. Envia o arquivo JAR para o lançamento do GitHub com a versão da tag de lançamento
  3. Constrói e envia a imagem Docker para o Docker Hub com tags:
    • latest
    • A tag de lançamento (por exemplo, v1.0.0)
Segredos Necessários para Publicação

Para habilitar a publicação no Docker Hub, adicione estes segredos ao seu repositório GitHub:

  • DOCKERHUB_USERNAME: Seu nome de usuário do Docker Hub
  • DOCKERHUB_TOKEN: Seu token de acesso do Docker Hub

🛠️ Ferramentas

Esta seção fornece documentação para as ferramentas expostas pelo VISO MCP Server. Cada ferramenta tem um propósito específico, parâmetros de entrada e formato de saída.

Assessments

get_assessment - Obter uma avaliação pelo seu ID

  • id: ID da avaliação (número, obrigatório)

Retorna informações detalhadas sobre uma avaliação específica.

get_assessment_summary - Obter o resumo de uma avaliação pelo seu ID

  • id: ID da avaliação (número, obrigatório)

Retorna os detalhes do resumo para uma avaliação específica.

create_assessment - Iniciar uma avaliação para um relacionamento existente

  • relationshipId: O ID do relacionamento para o qual criar uma avaliação (número, obrigatório)
  • recipientEmail: Endereço de e-mail do destinatário da avaliação (string, opcional)
  • recipientFirstName: Primeiro nome do destinatário da avaliação (string, opcional)
  • recipientLastName: Sobrenome do destinatário da avaliação (string, opcional)
  • publicDocumentUrls: URLs de documentos públicos a incluir na avaliação (string[], opcional)
  • followupType: Tipo de acompanhamento (enum de string, opcional)
  • followupRiskThreshold: Limiar de nível de risco que aciona o acompanhamento (enum de string, opcional)
  • followupTimeline: Cronograma para ações de acompanhamento (enum de string, opcional)
  • collectionTimeline: Cronograma para o fornecedor concluir o envio da avaliação (enum de string, opcional)
  • noVendorResponseAction: Ação a tomar quando o fornecedor não responde (enum de string, opcional)
  • aiProcessingOnly: Se deve processar apenas usando IA sem revisão humana (booleano, opcional)
  • requestedAuditTypes: Tipos de auditorias solicitadas para esta avaliação (string[], opcional)

Retorna os detalhes da avaliação criada.

update_assessment_expiration_date - Atualizar o prazo até o qual o fornecedor deve enviar sua resposta de avaliação

  • id: ID da avaliação (número, obrigatório)
  • expirationDate: Nova data/hora de expiração, ISO-8601 com offset; deve estar no futuro (string, obrigatório)

Retorna uma mensagem de confirmação.

update_assessment_followup - Atualizar a configuração de acompanhamento para uma avaliação

  • id: ID da avaliação (número, obrigatório)
  • followupType: Tipo de acompanhamento (enum de string, obrigatório)
  • followupRiskThreshold: Limiar de risco no qual ou acima do qual uma avaliação de acompanhamento deve ser acionada (enum de string, opcional)
  • followupTimeline: Cronograma de acompanhamento (enum de string, opcional)

Retorna uma mensagem de confirmação.

Audit Logs

get_user_audit_log_events - Obter eventos de log de auditoria com escopo de usuário para sua organização

  • start: Data/hora de início da consulta, ISO-8601 com offset (string, obrigatório)
  • end: Data/hora de término da consulta, ISO-8601 com offset (string, obrigatório)
  • eventTypes: Conjunto opcional de tipos de evento para filtrar (por exemplo, USER_LOGGED_IN); deixe vazio para todos (string[], opcional)

Retorna uma lista de eventos de log de auditoria do usuário, limitada a 500 registros.

get_audit_log_events - Obter eventos de log de auditoria filtrados (eventos de usuário, organização, avaliação e relacionamento)

  • start: Data/hora de início da consulta, ISO-8601 com offset (string, obrigatório)
  • end: Data/hora de término da consulta, ISO-8601 com offset (string, obrigatório)
  • eventTypes: Conjunto opcional de tipos de evento para filtrar (por exemplo, ASSESSMENT_COMPLETED, RELATIONSHIP_CREATED); deixe vazio para todos (string[], opcional)

Retorna registros polimórficos de eventos de log de auditoria. Cada item tem pelo menos auditEventType e dateTime.

Business Cases

get_all_business_cases - Obter todos os casos de negócio disponíveis para sua organização

Nenhum parâmetro necessário.

Retorna uma lista de todos os casos de negócio disponíveis para sua organização.

Data Types

get_all_datatypes - Obter todos os tipos de dados disponíveis para sua organização

Nenhum parâmetro necessário.

Retorna uma lista de todos os tipos de dados disponíveis para sua organização.

Vendor Directory

search_vendor_directory - Procurar um fornecedor no diretório de fornecedores VISO TRUST por URL ou domínio

  • urlOrDomain: A URL ou nome de domínio a pesquisar, por exemplo, example.com (string, obrigatório)

Retorna metadados básicos do fornecedor (nome, página inicial, descrição, favicon, domínios conhecidos).

Relationships

get_all_relationships - Obter uma lista de todos os relacionamentos e seus detalhes de avaliação

Nenhum parâmetro necessário.

Retorna informações sobre fornecedores terceiros, incluindo status de avaliação, níveis de risco e detalhes de contato.

get_relationship_by_id - Obter um relacionamento específico e seus detalhes de avaliação por ID

  • id: ID do relacionamento (número, obrigatório)

Retorna informações detalhadas sobre um fornecedor terceiro, incluindo status de avaliação, níveis de risco e detalhes de contato.

get_relationship_assessment_history - Obter o histórico de avaliação de um relacionamento

  • id: ID do relacionamento (número, obrigatório)

Retorna uma lista de avaliações associadas ao relacionamento especificado.

create_relationship - Criar um novo relacionamento com um fornecedor terceiro

  • name: Nome do relacionamento/fornecedor (string, obrigatório)
  • homepage: URL da página inicial do fornecedor (string, obrigatório)
  • businessOwnerEmail: Endereço de e-mail do proprietário do negócio (string, obrigatório)
  • businessOwnerFirstName: Primeiro nome do proprietário do negócio (string, opcional)
  • businessOwnerLastName: Sobrenome do proprietário do negócio (string, opcional)
  • description: Descrição do relacionamento/fornecedor (string, opcional)
  • contextTypes: Lista de tipos de contexto de negócio para este relacionamento (object[], opcional)
  • dataTypes: Lista de tipos de dados tratados neste relacionamento (object[], opcional)
  • tags: Lista de tags para categorizar este relacionamento (string[], opcional)
  • thirdPartyContact: Detalhes de contato do representante do fornecedor terceiro (object, opcional)

Retorna os detalhes do relacionamento criado.

create_relationship_by_domain - Criar um novo relacionamento usando apenas o domínio do fornecedor

  • domain: Domínio do fornecedor, por exemplo, visotrust.com (string, obrigatório)
  • vendorName: Nome do fornecedor (string, obrigatório)
  • product: Produto oferecido pelo fornecedor (string, opcional)
  • description: Descrição do relacionamento com o fornecedor (string, opcional)

Retorna os detalhes do relacionamento criado.

update_relationship - Atualizar um relacionamento existente com um fornecedor terceiro

  • id: ID do relacionamento (número, obrigatório)
  • name: Nome do relacionamento/fornecedor (string, obrigatório)
  • homepage: URL da página inicial do fornecedor (string, opcional)
  • description: Descrição do relacionamento/fornecedor (string, opcional)
  • contextTypes: Lista de tipos de contexto de negócio (object[], opcional)
  • dataTypes: Lista de tipos de dados tratados neste relacionamento (object[], opcional)
  • businessOwnerEmail: Endereço de e-mail do proprietário do negócio (string, opcional)
  • businessOwnerFirstName: Primeiro nome do proprietário do negócio (string, opcional)
  • businessOwnerLastName: Sobrenome do proprietário do negócio (string, opcional)
  • tags: Lista de tags (string[], opcional)

Retorna os detalhes do relacionamento atualizado.

partially_update_relationship - Atualizar parcialmente um relacionamento existente

Aceita os mesmos campos que update_relationship. Apenas os campos fornecidos na requisição são alterados; outros campos permanecem inalterados.

Retorna os detalhes do relacionamento atualizado.

search_relationships - Pesquisar relacionamentos por nome de domínio ou nome do fornecedor

  • domains: Lista de nomes de domínio a pesquisar (string[], obrigatório)
  • name: Nome do fornecedor/relacionamento a pesquisar (string, obrigatório)

Retorna uma lista de relacionamentos correspondentes com seus detalhes de avaliação.

create_tags - Criar novas tags para categorizar relacionamentos

  • tags: Lista de nomes de tags a criar (string[], obrigatório)

Retorna uma lista de todas as tags, incluindo as recém-criadas.

update_third_party_contact - Atualizar os detalhes de contato de um fornecedor terceiro

  • relationshipId: ID do relacionamento (número, obrigatório)
  • email: E-mail de contato (string, obrigatório)
  • firstName: Primeiro nome do contato (string, obrigatório)
  • lastName: Sobrenome do contato (string, obrigatório)

Retorna os detalhes do relacionamento atualizado.

onboard_relationship - Integrar um relacionamento, opcionalmente com resumo de aprovação e configurações de gerenciamento do ciclo de vida

  • id: ID do relacionamento (número, obrigatório)
  • approvalSummary: Resumo de aprovação opcional registrado na integração (string, opcional)
  • lifecycleManagementUpdateRequest: Configurações opcionais de gerenciamento do ciclo de vida (objeto, opcional)
    • artifactUpdateSettings.artifactUpdateType: Tipo de atualização de artefato (enum de string)
    • recertificationSettings.recertificationType: Tipo de recertificação (enum de string)
    • recertificationSettings.recertificationDate: Data/hora da próxima recertificação, ISO-8601 com deslocamento (string)
    • recertificationSettings.reviewFrequency: THREE_YEARS, TWO_YEARS, ANNUAL, SEMIANNUAL ou QUARTERLY (enum de string)

Retorna os detalhes do relacionamento integrado.

offboard_relationship - Desintegrar um relacionamento

  • id: ID do relacionamento (número, obrigatório)

Retorna os detalhes do relacionamento desintegrado.

archive_relationship - Arquivar um relacionamento

  • id: ID do relacionamento (número, obrigatório)

Retorna os detalhes do relacionamento arquivado.

Webhooks

get_all_webhooks - Obter todos os webhooks

Nenhum parâmetro obrigatório.

Retorna uma lista de todas as configurações de webhook.

get_webhook - Obter uma configuração de webhook por id

  • id: ID do webhook (número, obrigatório)

Retorna detalhes de uma configuração de webhook específica.

create_webhook_configuration - Criar uma configuração de webhook

  • request: Parâmetros de criação do webhook (objeto, obrigatório)
    • url: URL do webhook (string, obrigatório)
    • secret: Segredo do webhook (string, obrigatório)
    • eventTypes: Tipos de eventos que acionarão o webhook (string[], obrigatório)
    • serviceType: Tipo de serviço para o webhook (string, obrigatório)

Retorna a configuração de webhook criada.

update_webhook_configuration - Atualizar uma configuração de webhook

  • request: Parâmetros de atualização do webhook (objeto, obrigatório)
    • id: ID do webhook (número, obrigatório)
    • url: URL do webhook (string, opcional)
    • secret: Segredo do webhook (string, opcional)
    • eventTypes: Tipos de eventos que acionarão o webhook (string[], opcional)
    • serviceType: Tipo de serviço para o webhook (string, opcional)

Retorna a configuração de webhook atualizada.

delete_webhook_configuration - Excluir uma configuração de webhook

  • id: ID do webhook (número, obrigatório)

Exclui a configuração de webhook especificada.

Relatórios de Inteligência

create_bitsight_intelligence_report - Criar um novo relatório de inteligência BitSight

  • request: Parâmetros do relatório BitSight (objeto, obrigatório)
    • vendorDomain: Nome de domínio principal do fornecedor (string, obrigatório)
    • reportDate: Data/hora em que o relatório foi gerado (string ISO 8601, obrigatório)
    • link: Link opcional para a interface do provedor (string, opcional)
    • guid: GUID BitSight para a entidade (string, obrigatório)
    • customId: Identificador personalizado do BitSight (string, opcional)
    • name: Nome de exibição da entidade BitSight (string, opcional)
    • description: Descrição da entidade BitSight (string, opcional)
    • primaryDomain: Domínio principal da entidade BitSight (string, opcional)
    • ratingRange: Faixa de classificação BitSight (string, opcional)
    • ratingColor: Cor da classificação BitSight (string, opcional)
    • confidence: Nível de confiança da classificação BitSight (string, opcional)

Retorna o relatório de inteligência criado.

create_security_scorecard_intelligence_report - Criar um novo relatório de inteligência SecurityScorecard

  • request: Parâmetros do relatório SecurityScorecard (objeto, obrigatório)
    • vendorDomain: Nome de domínio principal do fornecedor (string, obrigatório)
    • reportDate: Data/hora em que o relatório foi gerado (string ISO 8601, obrigatório)
    • link: Link opcional para a interface do provedor (string, opcional)
    • grade: Nota em letra do SecurityScorecard (string, obrigatório)
    • domain: Domínio associado à entidade do scorecard (string, opcional)
    • score: Pontuação numérica do SecurityScorecard (número, opcional)

Retorna o relatório de inteligência criado.

create_recorded_future_intelligence_report - Criar um novo relatório de inteligência Recorded Future

  • request: Parâmetros do relatório Recorded Future (objeto, obrigatório)
    • vendorDomain: Nome de domínio principal do fornecedor (string, obrigatório)
    • reportDate: Data/hora em que o relatório foi gerado (string ISO 8601, obrigatório)
    • entityType: Tipo de entidade Recorded Future, ex. Company (string, obrigatório)
    • entity: Identificador da entidade Recorded Future (string, obrigatório)
    • riskScore: Pontuação de risco numérica (número, obrigatório)
    • riskLevel: Rótulo do nível de risco, ex. Critical/High/Medium/Low (string, obrigatório)
    • link: Link opcional para o relatório na interface do provedor (string, opcional)
    • firstSeen: Data mais antiga observada para a entidade, ISO 8601 (string, opcional)
    • lastSeen: Data mais recente observada para a entidade, ISO 8601 (string, opcional)
    • triggeredRuleCount: Número de regras Recorded Future que foram acionadas (número, opcional)
    • maxRuleCount: Número máximo de regras Recorded Future avaliadas (número, opcional)
    • summary: Texto de resumo opcional do Recorded Future (string, opcional)
    • criticalityLabel: Rótulo de criticalidade Recorded Future para a entidade (string, opcional)

Retorna o relatório de inteligência criado.

get_intelligence_reports_by_vendor - Obter todos os relatórios de inteligência de um fornecedor

  • vendorDomain: Nome de domínio principal do fornecedor (string, obrigatório)

Retorna uma lista de relatórios de inteligência para o fornecedor especificado.

get_latest_intelligence_report - Obter o relatório de inteligência mais recente de um fornecedor de uma fonte específica

  • vendorDomain: Nome de domínio principal do fornecedor (string, obrigatório)
  • source: Provedor de inteligência (enum de string: BITSIGHT, SECURITY_SCORECARD ou RECORDED_FUTURE, obrigatório)

Retorna o relatório de inteligência mais recente para o fornecedor e fonte especificados.

Usuários

get_all_users - Obter todos os usuários da sua organização

  • page: Página de resultados a recuperar (número, opcional; padrão 0)
  • size: Número de registros por página (número, opcional; padrão 20)
  • sort: Critérios de ordenação no formato: propriedade(,asc|desc) (string, opcional)

Retorna uma lista paginada de usuários.

get_user_by_email - Obter um usuário por email

  • email: Endereço de email do usuário (string, obrigatório)

Retorna os detalhes do usuário.

create_user - Criar um novo usuário

  • request: Parâmetros de criação do usuário (objeto, obrigatório)
    • email: Endereço de email do novo usuário (string, obrigatório)
    • firstName: Primeiro nome do novo usuário (string, obrigatório)
    • lastName: Sobrenome do novo usuário (string, obrigatório)

Retorna o usuário criado.

Formatação de Código

Este projeto utiliza Spotless com Google Java Format para formatação de código. Um hook de pre-commit é configurado automaticamente para garantir um estilo de código consistente.

Configuração

Após clonar o repositório, o hook de pre-commit será configurado automaticamente quando você executar qualquer comando Gradle.

Formatação Manual

Para formatar todos os arquivos manualmente:

./gradlew spotlessApply

Para verificar se os arquivos estão formatados corretamente:

./gradlew spotlessCheck

Se o hook de pre-commit rejeitar seu commit devido a problemas de formatação, simplesmente execute ./gradlew spotlessApply para corrigir a formatação e tente commitar novamente.

Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.