VISO TRUST MCP Server

VISO TRUST MCP 服务

一个 Model Context Protocol（MCP）服务，用于将 VISO TRUST API 功能集成到 AI 助手中。

托管远程服务

VISO TRUST 托管了此 MCP 服务的托管实例，因此你无需构建、运行或自行托管任何内容即可开始使用：

https://mcp.visotrust.com/mcp

使用 Streamable HTTP 传输方式将任意 MCP 客户端连接到此端点，并使用你的 VISO TRUST API 令牌进行身份验证。有关如何生成 API 令牌的信息，请参阅 VISO TRUST 支持文档。

客户端配置示例：

{
    "mcpServers": {
        "viso-mcp": {
            "type": "streamable-http",
            "url": "https://mcp.visotrust.com/mcp",
            "headers": {
                "Authorization": "Bearer <your-api-token>"
            }
        }
    }
}

若要使用 MCP Inspector 测试托管端点，请运行 npx @modelcontextprotocol/inspector，将 Transport Type 设为 Streamable HTTP，并使用上方的 URL。

本文档其余部分介绍如何自行运行此服务（在本地或自己的基础设施中）。

要求

• Java 21+
• Gradle
• Docker（容器化部署时可选）
• MCP Inspector（测试时可选）

配置

VISO TRUST API 配置

可为 VISO TRUST API 配置以下属性：

• visotrust.api.base-url：VISO TRUST API 的基础 URL（默认值：http://localhost:8080）
• visotrust.api.token：你在 VISO TRUST 平台上的 API 令牌（必填）
• visotrust.api.timeout：API 请求超时时间，单位为毫秒（默认值：30000）
• visotrust.api.connect-timeout：API 连接超时时间，单位为毫秒（默认值：5000）

有关如何为 visotrust.api.token 环境变量生成 API 令牌的信息，请参阅 VISO TRUST 支持文档。

应用配置文件

此应用支持 Spring Boot 配置文件，以便针对不同部署场景启用不同配置。

Remote 配置文件

remote 配置文件专为通过 Streamable HTTP 传输方式提供远程 MCP 支持而设计。此配置文件会将服务作为 Web 应用运行，以便通过 HTTP 与远程客户端通信。（Streamable HTTP 取代了已弃用的 SSE 传输方式；此处配置为无状态模式。）

remote 配置文件的主要区别：

• 作为 servlet Web 应用（Tomcat）在端口 3001 上运行，而非使用标准输入输出
• 在 POST /mcp 公开 MCP 端点（Streamable HTTP）
• 以无状态模式运行——不保留每个会话的服务端状态，因此可在负载均衡器后进行水平扩展，无需会话亲和性
• 针对远程客户端连接优化了服务设置
• 增强了日志记录，便于进行分布式调试

**注意：**客户端连接到单一的 Streamable HTTP 端点 …/mcp。不再提供旧版 SSE 端点（/sse + /mcp/message）。

激活 remote 配置文件的方法：

直接使用 Java 运行时：

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

使用 Gradle 运行时：

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

使用 Docker 时：

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

适用 remote 配置文件的场景：

• 将 MCP 服务部署到远程服务或云环境时
• 客户端将通过 Streamable HTTP 而非直接 stdio 连接时
• 分布式部署需要增强的日志记录和监控时
• 与通过 Streamable HTTP 连接的 Web AI 助手集成时

本地开发和直接 stdio 通信请使用默认配置文件（无需指定配置文件）。

安装

快速安装

点击下方任一按钮，在 VS Code 中安装 VISO MCP 服务：

使用 VS Code 手动设置

将以下 JSON 代码块添加到 VS Code 的用户设置（JSON）文件中。按 Ctrl + Shift + P，然后输入 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}"
        }
      }
    }
  }
}

也可以选择将类似示例（即不含 mcp 键）添加到工作区中的 .vscode/mcp.json 文件。这样便可与他人共享配置。

{
  "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}"
      }
    }
  }
}

在 Claude Desktop 和其他 MCP 客户端中使用

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"
            }
        }
    }
}

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"
            }
        }
    }
}

注意：JAVA_TOOL_OPTIONS 环境变量用于设置远程调试的 JVM 选项。可根据需要更改地址和端口。

💻 开发

Docker 设置

构建 Docker 镜像

docker build -t viso-mcp-server .

运行 Docker 容器

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

调试

安装 MCP Inspector

npm -g install @modelcontextprotocol/inspector

运行 MCP Inspector 进行测试

1. 构建 MCP 服务 JAR 文件

./gradlew bootJar

2. 运行 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

将 <version> 替换为项目的当前版本（例如，1.0.0 或最新版本中的版本号）。

CI/CD 流水线

本项目使用 GitHub Actions 进行持续集成和部署。工作流包含以下作业：

Lint

使用 Spotless 检查代码格式：

./gradlew spotlessCheck

构建

构建应用并创建 JAR 文件：

./gradlew build

发布

创建新版本时：

1. 更新 build.gradle 中的项目版本，使其与发布标签一致
2. 将带有发布标签版本号的 JAR 文件上传到 GitHub 发布页
3. 构建 Docker 镜像并推送到 Docker Hub，标签包括：
   • latest
   • 发布标签（例如，v1.0.0）

发布所需的密钥

要启用 Docker Hub 发布，请将以下密钥添加到 GitHub 仓库：

• DOCKERHUB_USERNAME：你的 Docker Hub 用户名
• DOCKERHUB_TOKEN：你的 Docker Hub 访问令牌

🛠️ 工具

本节介绍 VISO MCP 服务提供的工具。每个工具都有特定用途、输入参数和输出格式。

评估

get_assessment - 根据 ID 获取评估

• id：评估 ID（数字，必填）

返回特定评估的详细信息。

get_assessment_summary - 根据 ID 获取评估摘要

• id：评估 ID（数字，必填）

返回特定评估的摘要详情。

create_assessment - 为现有关系启动评估

• relationshipId：要为其创建评估的关系 ID（数字，必填）
• recipientEmail：评估接收人的电子邮件地址（字符串，可选）
• recipientFirstName：评估接收人的名字（字符串，可选）
• recipientLastName：评估接收人的姓氏（字符串，可选）
• publicDocumentUrls：要纳入评估的公开文档 URL（字符串数组，可选）
• followupType：后续跟进类型（字符串枚举，可选）
• followupRiskThreshold：触发后续跟进的风险级别阈值（字符串枚举，可选）
• followupTimeline：后续跟进行动的时间安排（字符串枚举，可选）
• collectionTimeline：供应商完成评估提交的时间安排（字符串枚举，可选）
• noVendorResponseAction：供应商未响应时采取的行动（字符串枚举，可选）
• aiProcessingOnly：是否仅使用 AI 处理，不进行人工审核（布尔值，可选）
• requestedAuditTypes：此评估要求的审计类型（字符串数组，可选）

返回已创建评估的详情。

update_assessment_expiration_date - 更新供应商必须提交评估回复的截止日期

• id：评估 ID（数字，必填）
• expirationDate：新的到期日期/时间，采用带偏移量的 ISO-8601 格式；必须是未来时间（字符串，必填）

返回确认消息。

update_assessment_followup - 更新评估的后续跟进配置

• id：评估 ID（数字，必填）
• followupType：后续跟进类型（字符串枚举，必填）
• followupRiskThreshold：触发后续评估的风险阈值（字符串枚举，可选）
• followupTimeline：后续跟进时间安排（字符串枚举，可选）

返回确认消息。

审计日志

get_user_audit_log_events - 获取组织中与用户相关的审计日志事件

• start：查询开始日期/时间，采用带偏移量的 ISO-8601 格式（字符串，必填）
• end：查询结束日期/时间，采用带偏移量的 ISO-8601 格式（字符串，必填）
• eventTypes：可选的事件类型筛选集合（例如 USER_LOGGED_IN）；留空表示获取所有事件（字符串数组，可选）

返回用户审计日志事件列表，最多 500 条记录。

get_audit_log_events - 获取筛选后的审计日志事件（用户、组织、评估和关系事件）

• start：查询开始日期/时间，采用带偏移量的 ISO-8601 格式（字符串，必填）
• end：查询结束日期/时间，采用带偏移量的 ISO-8601 格式（字符串，必填）
• eventTypes：可选的事件类型筛选集合（例如 ASSESSMENT_COMPLETED、RELATIONSHIP_CREATED）；留空表示获取所有事件（字符串数组，可选）

返回多态审计日志事件记录。每项至少包含 auditEventType 和 dateTime。

业务案例

get_all_business_cases - 获取组织中所有可用的业务案例

无需参数。

返回组织中所有可用业务案例的列表。

数据类型

get_all_datatypes - 获取组织中所有可用的数据类型

无需参数。

返回组织中所有可用数据类型的列表。

供应商目录

search_vendor_directory - 按 URL 或域名在 VISO TRUST 供应商目录中查找供应商

• urlOrDomain：要搜索的 URL 或域名，例如 example.com（string，必填）

返回基本供应商元数据（名称、主页、描述、favicon、已知域名）。

关系

get_all_relationships - 获取所有关系及其评估详情列表

无需参数。

返回第三方供应商的信息，包括其评估状态、风险级别和联系信息。

get_relationship_by_id - 按 ID 获取特定关系及其评估详情

• id：关系 ID（number，必填）

返回第三方供应商的详细信息，包括评估状态、风险级别和联系信息。

get_relationship_assessment_history - 获取某个关系的评估历史记录

• id：关系 ID（number，必填）

返回与指定关系相关的评估列表。

create_relationship - 创建与第三方供应商的新关系

• name：关系/供应商名称（string，必填）
• homepage：供应商主页 URL（string，必填）
• businessOwnerEmail：业务负责人的电子邮件地址（string，必填）
• businessOwnerFirstName：业务负责人的名字（string，可选）
• businessOwnerLastName：业务负责人的姓氏（string，可选）
• description：关系/供应商描述（string，可选）
• contextTypes：此关系的业务上下文类型列表（object[]，可选）
• dataTypes：此关系中处理的数据类型列表（object[]，可选）
• tags：用于分类此关系的标签列表（string[]，可选）
• thirdPartyContact：第三方供应商代表的联系信息（object，可选）

返回创建的关系详情。

create_relationship_by_domain - 仅使用供应商域名创建新关系

• domain：供应商域名，例如 visotrust.com（string，必填）
• vendorName：供应商名称（string，必填）
• product：供应商提供的产品（string，可选）
• description：供应商关系的描述（string，可选）

返回创建的关系详情。

update_relationship - 更新与第三方供应商的现有关系

• id：关系 ID（number，必填）
• name：关系/供应商名称（string，必填）
• homepage：供应商主页 URL（string，可选）
• description：关系/供应商描述（string，可选）
• contextTypes：业务上下文类型列表（object[]，可选）
• dataTypes：此关系中处理的数据类型列表（object[]，可选）
• businessOwnerEmail：业务负责人的电子邮件地址（string，可选）
• businessOwnerFirstName：业务负责人的名字（string，可选）
• businessOwnerLastName：业务负责人的姓氏（string，可选）
• tags：标签列表（string[]，可选）

返回更新后的关系详情。

partially_update_relationship - 部分更新现有关系

接受与 update_relationship 相同的字段。仅更改请求中提供的字段；其他字段保持不变。

返回更新后的关系详情。

search_relationships - 按域名或供应商名称搜索关系

• domains：要搜索的域名列表（string[]，必填）
• name：要搜索的供应商/关系名称（string，必填）

返回匹配关系及其评估详情的列表。

create_tags - 创建用于分类关系的新标签

• tags：要创建的标签名称列表（string[]，必填）

返回所有标签的列表，包括新创建的标签。

update_third_party_contact - 更新第三方供应商的联系信息

• relationshipId：关系 ID（数字，必填）
• email：联系邮箱（字符串，必填）
• firstName：联系人名字（字符串，必填）
• lastName：联系人姓氏（字符串，必填）

返回更新后的关系详情。

onboard_relationship - 为关系办理入驻，可选择提供审批摘要和生命周期管理设置

• id：关系 ID（数字，必填）
• approvalSummary：入驻时记录的可选审批摘要（字符串，可选）
• lifecycleManagementUpdateRequest：可选的生命周期管理设置（对象，可选）
  • artifactUpdateSettings.artifactUpdateType：工件更新类型（字符串枚举）
  • recertificationSettings.recertificationType：重新认证类型（字符串枚举）
  • recertificationSettings.recertificationDate：下次重新认证的日期/时间，采用带偏移量的 ISO-8601 格式（字符串）
  • recertificationSettings.reviewFrequency：THREE_YEARS、TWO_YEARS、ANNUAL、SEMIANNUAL 或 QUARTERLY（字符串枚举）

返回已办理入驻的关系详情。

offboard_relationship - 为关系办理退出

• id：关系 ID（数字，必填）

返回已办理退出的关系详情。

archive_relationship - 归档关系

• id：关系 ID（数字，必填）

返回已归档的关系详情。

Webhook

get_all_webhooks - 获取所有 Webhook

无需参数。

返回所有 Webhook 配置的列表。

get_webhook - 根据 ID 获取 Webhook 配置

• id：Webhook ID（数字，必填）

返回指定 Webhook 配置的详情。

create_webhook_configuration - 创建 Webhook 配置

• request：Webhook 创建参数（对象，必填）
  • url：Webhook URL（字符串，必填）
  • secret：Webhook 密钥（字符串，必填）
  • eventTypes：触发 Webhook 的事件类型（字符串[]，必填）
  • serviceType：Webhook 的服务类型（字符串，必填）

返回创建的 Webhook 配置。

update_webhook_configuration - 更新 Webhook 配置

• request：Webhook 更新参数（对象，必填）
  • id：Webhook ID（数字，必填）
  • url：Webhook URL（字符串，可选）
  • secret：Webhook 密钥（字符串，可选）
  • eventTypes：触发 Webhook 的事件类型（字符串[]，可选）
  • serviceType：Webhook 的服务类型（字符串，可选）

返回更新后的 Webhook 配置。

delete_webhook_configuration - 删除 Webhook 配置

• id：Webhook ID（数字，必填）

删除指定的 Webhook 配置。

情报报告

create_bitsight_intelligence_report - 创建新的 BitSight 情报报告

• request：BitSight 报告参数（对象，必填）
  • vendorDomain：供应商的主域名（字符串，必填）
  • reportDate：报告生成的日期/时间（ISO 8601 字符串，必填）
  • link：指向提供商界面的可选链接（字符串，可选）
  • guid：实体的 BitSight GUID（字符串，必填）
  • customId：BitSight 中的自定义标识符（字符串，可选）
  • name：BitSight 实体的显示名称（字符串，可选）
  • description：BitSight 实体的描述（字符串，可选）
  • primaryDomain：BitSight 实体的主域名（字符串，可选）
  • ratingRange：BitSight 评级范围（字符串，可选）
  • ratingColor：BitSight 评级颜色（字符串，可选）
  • confidence：BitSight 评级的置信度（字符串，可选）

返回创建的情报报告。

create_security_scorecard_intelligence_report - 创建新的 SecurityScorecard 情报报告

• request：SecurityScorecard 报告参数（对象，必填）
  • vendorDomain：供应商的主域名（字符串，必填）
  • reportDate：报告生成的日期/时间（ISO 8601 字符串，必填）
  • link：指向提供商 UI 的可选链接（字符串，可选）
  • grade：SecurityScorecard 字母等级（字符串，必填）
  • domain：与评分卡实体关联的域名（字符串，可选）
  • score：SecurityScorecard 的数值评分（数字，可选）

返回创建的情报报告。

create_recorded_future_intelligence_report - 创建新的 Recorded Future 情报报告

• request：Recorded Future 报告参数（对象，必填）
  • vendorDomain：供应商的主域名（字符串，必填）
  • reportDate：报告生成的日期/时间（ISO 8601 字符串，必填）
  • entityType：Recorded Future 实体类型，例如 Company（字符串，必填）
  • entity：Recorded Future 实体标识符（字符串，必填）
  • riskScore：数值风险评分（数字，必填）
  • riskLevel：风险级别标签，例如 Critical/High/Medium/Low（字符串，必填）
  • link：指向提供商 UI 中报告的可选链接（字符串，可选）
  • firstSeen：首次观察到该实体的日期，ISO 8601 格式（字符串，可选）
  • lastSeen：最近一次观察到该实体的日期，ISO 8601 格式（字符串，可选）
  • triggeredRuleCount：已触发的 Recorded Future 规则数量（数字，可选）
  • maxRuleCount：评估的 Recorded Future 规则最大数量（数字，可选）
  • summary：Recorded Future 提供的可选摘要文本（字符串，可选）
  • criticalityLabel：该实体的 Recorded Future 关键性标签（字符串，可选）

返回创建的情报报告。

get_intelligence_reports_by_vendor - 获取某个供应商的所有情报报告

• vendorDomain：供应商的主域名（字符串，必填）

返回指定供应商的情报报告列表。

get_latest_intelligence_report - 获取某个供应商来自指定来源的最新情报报告

• vendorDomain：供应商的主域名（字符串，必填）
• source：情报提供商（字符串枚举：BITSIGHT、SECURITY_SCORECARD 或 RECORDED_FUTURE，必填）

返回指定供应商和来源的最新情报报告。

用户

get_all_users - 获取组织中的所有用户

• page：要检索的结果页（数字，可选；默认值为 0）
• size：每页记录数（数字，可选；默认值为 20）
• sort：排序条件，格式为：property(,asc|desc)（字符串，可选）

返回分页的用户列表。

get_user_by_email - 按电子邮件地址获取用户

• email：用户的电子邮件地址（字符串，必填）

返回用户详细信息。

create_user - 创建新用户

• request：用户创建参数（对象，必填）
  • email：新用户的电子邮件地址（字符串，必填）
  • firstName：新用户的名字（字符串，必填）
  • lastName：新用户的姓氏（字符串，必填）

返回创建的用户。

代码格式化

本项目使用 Spotless 和 Google Java Format 进行代码格式化。系统会自动设置 pre-commit 钩子，以确保代码风格一致。

设置

克隆代码库后，运行任意 Gradle 命令时都会自动设置 pre-commit 钩子。

手动格式化

要手动格式化所有文件：

./gradlew spotlessApply

要检查文件格式是否正确：

./gradlew spotlessCheck

如果 pre-commit 钩子因格式问题拒绝了你的提交，只需运行 ./gradlew spotlessApply 修复格式，然后再次尝试提交。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。