CAST Imaging MCP Server

CAST Imaging MCP 服务

概述

CAST Imaging MCP 服务通过模型上下文协议（MCP）提供全面的软件智能，弥合 AI Agent 与真实软件架构之间的鸿沟。用户可以通过向 AI Agent 提示词，获取有关其应用、事务、依赖关系、质量模式和架构结构的洞察。

此服务让 AI Agent 能够了解您的应用，从组合层级清单到细粒度对象关系。无论您是探索数据库架构、分析事务流，还是调查质量问题，MCP 服务都会提供精准的分页数据，助您做出明智的架构决策。

使用场景

• 组合层级探索：列出 CAST Imaging 中可用的应用，并提供有关这些应用的详细信息。
• 应用架构分析：探索不同层级的架构图并直观查看系统结构。
• 事务与数据流映射：分析事务，追踪数据实体交互网络，探索复杂对象和执行顺序。
• 质量与安全洞察：识别应用中的漏洞、云就绪障碍和结构缺陷。
• 数据库架构探索：浏览各应用中的数据库表、列、关系和约束。
• 对象层级调查：搜索对象及其属性，并分析调用方与被调用方关系。

---

目录

• 先决条件
• 快速开始
• 安装
• 配置参考
• 运行（HTTP）
• Windows 安装
• VS Code + GitHub Copilot 设置
• 验证与测试查询
• 工具集与工具
• 故障排除
• 安全说明
• 软件包内容
• 支持

---

先决条件

必需

• 已安装并运行 Docker 的 Linux 系统。
• 此主机能够访问 CAST Imaging‑APIs 服务
• 支持 MCP 的客户端（例如，VS Code 中的 GitHub Copilot、Claude Desktop）
• CAST Imaging API 密钥（从您的 Imaging 用户配置文件中生成）

下载

• 下载 CAST Imaging MCP 服务安装程序

MCP 服务应在 Linux 系统上运行。CAST Imaging‑APIs 可以在同一台或另一台 Linux 机器上运行。

---

快速开始

1. 确认 Imaging‑APIs 正在运行：

   curl -H "x-api-key: <your-imaging-api-key>"         http://{CONTROL_PANEL_HOST}:8090/imaging/apis/rest/ready
   # expected: true
   

2. 解压安装程序压缩包。
3. 配置 config/app.config 和 .env。
4. 使用 ./run.sh --install 启动服务。
5. 使用您的服务 URL 配置客户端（VS Code Copilot 或 Claude）。
6. 测试查询（请参阅下方示例）。

---

CAST Imaging MCP 服务的安装

1) 解压安装程序

com.castsoftware.imaging.mcpserver.docker.1.0.2-funcrel/
├─ config/
│  └─ app.config
├─ .env                      # hidden; use `ls -a`
├─ docker-compose.yml
├─ run.sh
├─ README.md
└─ copilot-instructions.md

2) 验证 CAST Imaging‑APIs

确保可以访问 Control Panel/registry，且 Imaging‑APIs 已就绪（请参阅快速开始步骤 #1）。

3) 配置服务

编辑 config/app.config：

HOST_CONTROL_PANEL="your-control-panel-host"   # REQUIRED: Control Panel service registry host/IP
PORT_CONTROL_PANEL=8098                        # Default Control Panel registry port
IMAGING_PAGE_SIZE=1000                         # Internal fetch batch size
IMAGING_DISPLAY_PAGE_SIZE=20                   # Page size in responses
IMAGING_CODE=False                             # Source code access via MCP (security sensitive)
DEBUG_MODE=false                               # Debug mode to see the activity in logs
IMAGING_DOMAIN="default"                       # Imaging domain/tenant
CONTROL_PANEL_SSL_ENABLED=false                # Set true only if Control Panel config/eureka is on HTTPS
MCP_TOOL_SURFACE_PROFILE="full"                # MCP tool exposure profile: "intents" or "full"
MCP_INTENTS_HIDDEN_FUNCTIONS=""                # Comma-separated structural functions hidden from intents mode
SERVICE_HOST="your-service-host"               # REQUIRED: The IP/hostname of the machine on which the MCP Server is running
SSL_CA_BUNDLE=""                               # Optional PEM bundle for private/self-signed CAs

在 .env（隐藏文件）中设置对外开放的端口：

MCP_SERVER_PORT=8282

**提示：**在 Linux 上，以点开头的文件（如 .env）是隐藏文件。使用 ls -a 查看。

4) 启动

chmod +x run.sh
./run.sh --install

这将启动 Docker Compose 堆栈和 MCP 服务。

如果您使用 SSL_CA_BUNDLE，请将 PEM 文件放在 docker-compose.yml 同级的 certificates/ 文件夹中。Compose 文件会将该文件夹挂载到容器中的 /app/certificates。

---

配置参考

HOST_CONTROL_PANEL（必需）

**默认值：**无（用户需要提供此值）
**说明：**运行 Control Panel Service 的机器的 IP 地址或主机名。

这是一个服务注册表，Imaging 使用它来注册和发现其内部服务。安装 Imaging 时会自动部署此服务。您应填写运行 Imaging Control Panel 服务的 Linux 机器的 IP 地址。

PORT_CONTROL_PANEL

默认值： 8098
描述： Control Panel 注册表端口。

IMAGING_PAGE_SIZE

默认值： 1000
描述： 设置 MCP 服务每次请求获取的记录数（内部批处理）。可根据吞吐量进行调整。

IMAGING_DISPLAY_PAGE_SIZE

默认值： 20
描述： 设置面向用户的响应中每页显示的记录数。可根据用户体验进行调整。

IMAGING_CODE

默认值： False
描述： 控制 Agent 是否可以通过 MCP 服务访问源代码。

默认值为 false，因为 Agent 通常处理的是开放仓库。启用此选项可能会向任何有权访问 MCP 的人暴露源代码，从而带来潜在的安全风险；对于无法直接访问代码仓库的 Claude 桌面版等客户端来说，这一点尤其值得注意。

DEBUG_MODE

默认值： false
描述： 调试模式会在日志中显示活动记录。设为 true 时，会显示每个用户提示词所选的工具、调用的 API 和结果。设为 false 时，只会显示所选的工具及相应调用的 API。

IMAGING_DOMAIN

默认值： default
描述： 在多租户环境中，用于获取数据的 Imaging 域/租户。

CONTROL_PANEL_SSL_ENABLED

默认值： false
描述： 当 Control Panel 配置/注册表端点使用 HTTPS 时，设为 true。

MCP_TOOL_SURFACE_PROFILE

默认值： full 描述： 选择 MCP 工具暴露配置。使用 full 暴露完整工具集，或使用 intents 暴露元工具界面。

MCP_INTENTS_HIDDEN_FUNCTIONS

默认值： 空 描述： 当 MCP_TOOL_SURFACE_PROFILE 设为 intents 时，要隐藏的结构函数列表，以逗号分隔。

SERVICE_HOST（必填）

默认值： 无（用户需要提供该值）
描述： MCP 服务运行所在机器的 IP 地址/主机名。

SSL_CA_BUNDLE

默认值： 空
描述： 可选的 PEM CA 证书包路径，用于私有/自签名证书链。使用 Docker 安装程序时，将 PEM 文件放在 ./certificates/ 下，并将其引用为 /app/certificates/<file>.pem。

---

运行（HTTP）

使用以下命令启动服务：

chmod +x run.sh
./run.sh --install

---

Windows 安装

本节详细介绍如何在 Windows 系统上安装和配置 CAST Imaging MCP Server。

Windows 前提条件

• Windows 系统
• CAST Imaging‑APIs 服务正在运行且可访问
• 支持 MCP 的客户端（例如，VS Code 中的 GitHub Copilot、Claude Desktop）
• CAST Imaging API Key（从 Imaging 用户个人资料中生成）

1) 下载并解压

1. 下载适用于 windows 的安装包。
2. 将 zip 文件解压到首选位置
3. 进入解压后的目录

安装包内容：

com.castsoftware.imaging.mcpserver.__MCP_VERSION__*/
├─ mcpserver/
├─ tools/
├─ configuration.conf
├─ mcp-server-installer.bat
└─ README.md

2) 验证 CAST Imaging‑APIs

确保 Control Panel/注册表可访问，且 Imaging‑APIs 已就绪：

curl -H "x-api-key: <your-imaging-api-key>" 
     http://{HOSTNAME_CONTROL_PANEL}:8090/rest/ready
# expected: true

3) 配置服务

使用环境设置编辑 configuration.conf：

HOSTNAME_CONTROL_PANEL="your-control-panel-host"      # Required: IP or hostname of Control Panel server
SERVICE_HOST="your-service-host"                      # Required: IP/hostname of the MCP Server machine
PORT_CONTROL_PANEL=8098                               # Default Control Panel registry port  
MCP_SERVER_PORT=8282                                  # Default MCP server port
INSTALL_DIR=C:\Program Files\Cast\Imaging-MCP-Server  # Default installation location
CONFIG_DIR=C:\ProgramData\CAST\Imaging-MCP-Server     # Default config files location
IMAGING_PAGE_SIZE=1000                                # Records per internal request
IMAGING_DISPLAY_PAGE_SIZE=20                          # Records per response page
IMAGING_CODE=False                                    # Enable source code access (security consideration)
DEBUG_MODE=false                                      # Debug mode to see the activity in logs
IMAGING_DOMAIN=default                                # Imaging domain/tenant
CONTROL_PANEL_SSL_ENABLED=false                       # Set true only if Control Panel config/eureka is on HTTPS
MCP_TOOL_SURFACE_PROFILE=full                         # MCP tool exposure profile: full or intents
MCP_INTENTS_HIDDEN_FUNCTIONS=                         # Comma-separated structural functions hidden from intents mode
SSL_CA_BUNDLE=                                        # Optional PEM bundle for private/self-signed CAs

4) 安装为 Windows 服务

使用批处理脚本进行安装：

mcp-server-installer.bat --install configuration.conf

这会将 MCP 服务安装为 Windows 服务。安装成功后，你会在服务列表中看到名为 "CAST Imaging MCP Server" 的 Windows 服务。

5) 验证安装

检查服务是否正在运行：

• 打开 服务（services.msc）
• 查找 "CAST Imaging MCP Server"
• 确认状态为 "Running"

Windows 专属操作

更新 MCP 服务

更新现有安装：

mcp-server-installer.bat --update

更新无需更改配置。

卸载 MCP 服务

彻底移除 MCP 服务：

mcp-server-installer.bat --uninstall

此操作会移除 Windows 服务并清理所有与 MCP 相关的文件。

获取帮助

查看可用命令：

mcp-server-installer.bat --help

可用命令：

mcp-server-installer.bat --install configuration.conf   : Install CAST Imaging MCP server
mcp-server-installer.bat --update                       : Update CAST Imaging MCP server
mcp-server-installer.bat --uninstall                    : Uninstall CAST Imaging MCP server
mcp-server-installer.bat --help                         : Display help message

Windows 故障排除

问题	可能原因	解决方案
服务无法启动	配置错误	检查 %CONFIG_DIR%/setup-config/app.config
连接被拒绝	服务未运行	重启“CAST Imaging MCP Server”服务
安装失败	权限不足	以管理员身份运行安装程序

---

VS Code + GitHub Copilot 设置

本节详细介绍如何将 CAST Imaging MCP Server 与 Github Copilot 连接。

1) 在 VS code 上安装 GitHub Copilot

• 打开扩展视图（Ctrl+Shift+X 或 Cmd+Shift+X）。
• 搜索“GitHub Copilot”，然后点击“安装”。
• 按提示登录 GitHub

2) 生成 CAST Imaging API 密钥

• 登录 CAST Imaging
• 前往个人资料部分。
• 生成新的 API 密钥（请复制并妥善保存此密钥，后续步骤会用到）

3) 创建 MCP 配置（.vscode/mcp.json）

• 在 VS Code 中打开任意文件夹，并在其根目录下创建一个 .vscode 文件夹。然后在其中创建 mcp.json 文件。

{
  "inputs": [
    {
      "id": "imaging-key",
      "type": "promptString",
      "description": "CAST Imaging API Key"
    },
    {
      "id": "imaging-tenant",
      "type": "promptString",
      "description": "Imaging tenant"
    }
  ],
  "servers": {
    "imaging": {
      "type": "http",
      "url": "http://<your-mcp-server-host:port>/mcp/",
      "headers": {
        "x-api-key": "${input:imaging-key}",
        "x-user-tenant": "${input:imaging-tenant}"
      }
    }
  }
}

4) （替代方案）手动注册流程

如果 VS Code 未自动选取服务：

1. 打开 Copilot Chat → 齿轮图标 → 选择可用于聊天的工具
2. + 添加更多工具… → + 添加 MCP 服务… → 选择 HTTP
3. 输入 http(s)://<your-mcp-server-host:port>/mcp/ 并确认
4. VS Code 会写入 .vscode/copilot/mcp.json → 添加标头代码块：

"my-mcp-server-xxxx": {
  "url": "http://<your-mcp-server-host:port>/mcp/",
  "headers": {
    "x-api-key": "${input:imaging-key}",
    "x-user-tenant": "${input:imaging-tenant}"
  }
}

5) Copilot 的项目说明

从安装程序中复制 copilot-instructions.md，在 VScode 中创建名为 .github 的文件夹，然后将 copilot-instructions.md 文件粘贴到其中。这有助于 Agent 提供更好的回答。

---

验证与测试查询

连通性检查

# MCP container running
docker ps | grep mcp-server

# Imaging‑APIs health
curl -H "x-api-key: <your-key>"      http://{CONTROL_PANEL_HOST}:8090/imaging/apis/rest/ready

在 Copilot/Claude 中试用

List all applications
List 5 transactions for application <YourApp>
List available applications datagraphs
List applications insights

---

工具集与工具

服务将功能组织到工具集中。

可用工具集

工具集	描述
Portfolio Tools	Portfolio 级探索：列出应用程序、比较指标、扫描各系统中的热点。
Applications Tools	应用程序级分析：事务、质量问题、数据图、架构。
Objects Tools	对象元素探索：定位对象、引用、调用方/被调用方。

工具

Portfolio

• applications — 列出 CAST Imaging 中可用的应用程序
• all_applications — 列出所有应用程序（云构建）
• my_applications — 列出当前用户所属的应用程序（云构建）
• applications_transactions — 获取所有应用程序中的事务，支持筛选
• applications_data_graphs — 获取所有应用程序中的数据实体交互网络（数据图）
• applications_dependencies — 获取所有应用程序之间的依赖关系
• applications_quality_insights — 获取质量洞察，包括 CVE、云检测模式和绿色检测模式
• get_mcp_info — 获取 MCP 服务和 Imaging 的版本/环境信息

Applications

- **application_database_explorer** — 探索应用中的数据库表和列 - **stats** — 获取应用的基本统计信息 - **architectural_graph** — 获取特定层级（层、组件、子组件、技术类别、元素类型）的架构图数据（节点/链接） - **architectural_graph_focus** — 获取特定区域的聚焦架构图数据 - **quality_insights** — 获取质量相关洞察（CVE、云模式、绿色模式、结构缺陷、ISO-5055） - **quality_insight_violations** — 按 ID 获取质量洞察中的具体违规项，可选提供位置 - **packages** — 获取包信息和依赖项 - **package_interactions** — 按组件和版本获取与特定包的交互 - **transaction_profiles** — 获取可用的事务配置 - **transactions** — 获取事务，可按名称、全名或类型筛选 - **transaction_details** — 按 ID 获取事务的聚焦信息 - **add_view_document** — 为事务或数据图添加文档 - **data_graphs** — 获取数据实体交互网络（数据图），可选筛选 - **data_graph_profiles** — 获取可用的数据图配置 - **data_graph_details** — 按 ID 获取数据图的聚焦信息 - **inter_applications_dependencies** — 获取应用间的向内和向外依赖 - **inter_app_detailed_dependencies** — 获取两个特定应用之间的详细依赖 - **advisor_occurrences** — 获取支持所选顾问的出现记录 - **application_iso_5055_explorer** — 探索 ISO 5055 特性和弱点 - **api_inventory** — 获取应用的 API 清单 - **advisors** — 获取迁移/现代化顾问、规则和违规项 - **dynamic_views** — 列出自定义聚合视图 - **dynamic_view_details** — 获取自定义视图图表或自定义节点中的对象 - **manage_dynamic_view** — 创建、删除、重命名、发布或取消发布自定义视图 - **configure_dynamic_view** — 在自定义视图中添加或删除自定义节点 - **views** — 列出已保存的视图 - **view_details** — 获取已保存视图的详细信息 - **manage_view** — 创建、更新或删除已保存的视图 - **tags** — 列出应用中可用的标签

对象

• objects — 获取符合识别条件（名称、全名、名称修饰、类型、文件路径）的应用对象
• object_profiles — 获取可用的对象配置
• object_details — 获取对象的完整详细信息，包括属性、关系、代码片段和使用统计信息
• add_object_document — 为通过 ID 指定的对象添加文档文本
• manage_object_tags — 为明确指定的对象添加或删除标签
• bulk_manage_object_tags — 为符合服务端条件的对象添加或删除标签
• objects_relationships — 查找多个对象之间的关系
• pathfinder_hierarchy_details — 查找执行路径、调用链和层级详细信息
• source_files — 查找定义符合文件路径条件的代码对象的源文件
• source_file_details — 获取源文件及其代码元素的详细信息（清单、内部、向内、向外、测试）
• transactions_using_object — 获取使用符合指定条件的对象的事务
• data_graphs_involving_object — 获取涉及特定对象的数据实体交互网络（数据图）

结构搜索（intents 配置）

• get_structural_search_function_syntax — 获取结构搜索函数的语法和用法详情
• run_structural_search_function — 通过通用分发器执行结构搜索函数

---

故障排除

症状	可能原因	处理方法
客户端出现 ECONNREFUSED	服务未运行	运行 docker ps，然后运行 ./run.sh --install 启动服务
身份验证错误	Imaging API 密钥错误或已过期	从 Imaging 个人资料中重新生成密钥
答案为空	Imaging‑APIs 无法访问	重新检查 HOST_CONTROL_PANEL / PORT_CONTROL_PANEL 和健康检查端点
HTTPS 握手/错误	Control Panel 证书为私有证书或自签名证书	设置 CONTROL_PANEL_SSL_ENABLED=true 并配置 SSL_CA_BUNDLE
VS Code 未提示输入密钥	mcp.json 中缺少 inputs	添加 inputs 块（参见设置）

日志和检查

# Server logs
docker logs <mcp-container-id>

# Re‑verify Imaging‑APIs
curl -H "x-api-key: <your-key>"      http://{CONTROL_PANEL_HOST}:8090/imaging/apis/rest/ready

---

安全说明

• IMAGING_CODE 默认值为 False：启用后，MCP 客户端可以访问源代码 → 应通过策略、网络和凭据限制访问。
• 私有 CA 使用 SSL_CA_BUNDLE：建议使用 CA 证书包，而非禁用 TLS 验证。
• 最小权限原则：限制能够在 MCP 宿主中获取/输入 Imaging API 密钥的人员。

---

软件包内容

com.castsoftware.imaging.mcpserver.docker.__MCP_VERSION__/
├─ config/app.config
├─ docker-compose.yml
├─ run.sh
├─ .env                      # hidden
├─ README.md                 # original docs
└─ copilot-instructions.md   # optional, copy to .github/

---

支持

• 检查容器日志和 Imaging‑APIs 健康检查端点
• 验证 app.config、.env、mcp.json 的路径和值
• 确保客户端 ↔ 服务 ↔ Imaging‑APIs 之间的网络可达

---

许可证

此仓库仅包含文档。
本项目的源代码为专有，且未以开源许可证发布。

• 源代码依据单独的商业许可证授权，且不包含在此仓库中。
• 此仓库不授予任何源代码相关权利。
• 您可以自由查看和分享本文档，但不得据此推断或暗示您拥有专有软件的权利。

如需咨询商业授权事宜，请联系您当地的 CAST 代表 (https://www.castsoftware.com/overview)。

---