CAST Imaging MCP Server Extension

A VS Code extension that provides seamless integration with the CAST Imaging MCP Server. This extension automatically manages Docker containers and creates the necessary MCP configuration for easy access to imaging services.

Overview
Prerequisites
Quick Start
Installation
Configuration
Available Commands
Server Management
Generated Files
Debug Mode Configuration
Usage Example
Troubleshooting
Technical Details

Overview

This VS Code extension provides developers with seamless access to CAST Imaging's architectural analysis capabilities directly within VS Code, including:

Automatic Docker container management
MCP configuration generation
SSL support for Control Panel connections
Debug mode for enhanced logging and troubleshooting
GitHub Copilot integration
Real-time server status monitoring

Prerequisites

Required

Docker installed and running
VS Code version 1.74.0 or higher
CAST Imaging Control Panel service running and accessible

Quick Start

Install the VS Code extension
Configure server settings (REQUIRED)
Start the MCP server
Enter your API key when prompted
Begin using imaging services

Installation

Step 1: Install the Extension

Install from the VS Code Marketplace or install the .vsix file directly.

Auto-generated files:

.vscode/mcp.json - MCP client configuration
.github/copilot-instructions.md - GitHub Copilot integration

Step 2: Configure Server Settings (REQUIRED)

⚠️ Important: You MUST configure server settings before starting the MCP server.

Open VS Code Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and run:

CAST Imaging MCP: Configure MCP Server

Configuration

Required Settings

Setting	Description	Default	Required
Host Control Panel	IP/hostname of Control Panel machine	`localhost`	✅ Yes
Port Control Panel	Control Panel port number	`8098`	✅ Yes

Optional Settings

Setting	Description	Default
Server Port	MCP server port	`8282`
Control Panel SSL Enabled	Enable SSL for Control Panel connections	`false`
Debug Mode	Enable enhanced logging and debugging features	`false`
Imaging Domain	The imaging domain to use	`default`
Auto Start	Auto-start server on VS Code startup	`false`

Configuration Methods

Access configuration through:

Command Palette → CAST Imaging MCP: Configure MCP Server
VS Code Settings → Search for "CAST Imaging MCP"

Start the MCP Server

After configuration, start the server:

CAST Imaging MCP: Start MCP Server

Server startup process:

Pulls necessary Docker images
Creates and starts containers
Updates status bar indicator
Generates MCP configuration files

Available Commands

Access these commands via Command Palette (Ctrl+Shift+P):

Primary Commands

Command	Description
`CAST Imaging MCP: Configure MCP Server`	Configure server settings (Run this first!)
`CAST Imaging MCP: Start MCP Server`	Start the MCP server containers
`CAST Imaging MCP: Stop MCP Server`	Stop the MCP server containers
`CAST Imaging MCP: Restart MCP Server`	Restart the MCP server containers

Management Commands

Command	Description
`CAST Imaging MCP: Install MCP Server`	Install Docker containers and dependencies
`CAST Imaging MCP: Reinstall MCP Server`	Clean reinstall of server components
`CAST Imaging MCP: Force Cleanup Containers`	Forcibly remove all containers (use if stuck)
`CAST Imaging MCP: Check Server Status`	Show current server status

Server Management

Status Bar Indicator

The extension displays server status in the VS Code status bar:

Indicator	Status	Description
🟢 Green Circle	Running	Server is operational
🔴 Red Circle	Stopped	Server is not running
🟡 Yellow Spinner	Transitioning	Starting/stopping
❌ Red X	Error	Error state detected

Interaction: Click the status bar item to check detailed status.

Find the "CAST Imaging MCP Server" panel in the Explorer sidebar for quick access to:

Server status overview
Action buttons (Start/Stop/Restart)
Configuration summary
Log viewing capabilities

Generated Files

The extension automatically creates these files in your workspace:

`.vscode/mcp.json`

Purpose: Configures VS Code MCP client connection

{
  "inputs": [
    {
      "id": "imaging-key",
      "type": "promptString",
      "description": "Imaging API Key"
    }
  ],
  "servers": {
    "CASTImaging": {
      "type": "http",
      "url": "http://your-host_control_panel:8282/mcp/",
      "headers": {
        "x-api-key": "${input:imaging-key}"
      }
    }
  }
}

`.github/copilot-instructions.md`

Purpose: Provides GitHub Copilot with context about imaging tools

Features:

Impact analysis workflows
Application architecture exploration guidance
Tool recommendations for different scenarios
Code modification best practices
Applied to all workspace files (applyTo: '**')

Debug Mode Configuration

Enable Debug Mode

Debug mode provides enhanced logging system capabilities for troubleshooting server issues and development purposes.

Configure Debug Mode in extension settings:

CAST Imaging MCP: Configure MCP Server → Debug Mode → Enable Debug Mode

Restart server to apply changes:
```
CAST Imaging MCP: Restart MCP Server
```

Enhanced Logging System

New Feature Added:

Custom Log File Integration - Implemented centralized logging system that combines FastMCP framework logs with custom application logs into a unified log file. The system creates structured log files in the logs/ folder at the installer root directory for comprehensive debugging and monitoring capabilities.
Configurable Log Levels - Added user-configurable log level settings to control logging verbosity:
- level=debug - Enables detailed debugging information including trace-level data for troubleshooting
- level=info - Standard operational logging with essential runtime information
- Dynamic log level switching without requiring application restart

Key Features:

Unified log aggregation from multiple sources (FastMCP + custom logs)
Structured log file organization in dedicated logs directory
Runtime log level configuration for flexible debugging
Persistent logging for post-incident analysis and system monitoring
Improved troubleshooting capabilities with detailed debug traces

Technical Impact:

Enhanced system observability and debugging capabilities
Centralized log management for better operational insights
Configurable verbosity levels for different deployment scenarios

Debug Mode vs Normal Mode

Feature	Normal Mode	Debug Mode
Log Level	Info (Standard)	Debug (Detailed)
Log Location	Container logs only	Unified logs/ directory
Performance	Optimized	Detailed diagnostics
Log Aggregation	Basic	FastMCP + Custom logs
Recommended Use	Production	Development/Troubleshooting

Configuration in app.config

When Debug Mode is enabled, the following is added to the server configuration:

DEBUG_MODE=true

This setting activates the enhanced logging system with centralized log file creation and configurable log levels within the MCP server container.

Control Panel SSL Configuration

When Control Panel SSL Enabled is configured, the following is added to the server configuration:

CONTROL_PANEL_SSL_ENABLED=true

This setting enables SSL/HTTPS when connecting to the CAST Imaging Control Panel. Enable this when your Control Panel is configured to use HTTPS connections.

Note: This SSL setting is for connections from the MCP server to your Control Panel, not for clients connecting to the MCP server. The MCP server itself runs on HTTP.

Usage Example

Typical Workflow

# 1. Install Extension (via VS Code Marketplace)

# 2. Configure Server Settings
Command Palette → "CAST Imaging MCP: Configure MCP Server"
→ Host Control Panel: "your-control-panel-host"
→ Port Control Panel: "8098"
→ Control Panel SSL Enabled: "false" (or "true" if Control Panel uses HTTPS)

# 3. Optional: Enable Debug Mode (for troubleshooting)
Command Palette → "CAST Imaging MCP: Configure MCP Server"
→ Debug Mode → "Enable Debug Mode"

# 4. Optional: Enable Control Panel SSL (if Control Panel uses HTTPS)
Command Palette → "CAST Imaging MCP: Configure MCP Server"
→ Control Panel SSL Enabled → "Enable Control Panel SSL"

# 5. Start Server
Command Palette → "CAST Imaging MCP: Start MCP Server"
→ Wait for green status indicator

# 6. Use MCP Features
→ VS Code prompts for API key on first connection
→ Enter your Imaging API key
→ Access imaging services through MCP

# 7. Mode Switching
→ Stop server → Change Debug/Control Panel SSL settings → Start server

API Key Setup

Generate API Key:
- Log into CAST Imaging instance
- Navigate to profile section
- Generate new API key
- Save securely
Enter in VS Code:
- First MCP feature use triggers prompt
- Enter saved API key
- Key is managed by VS Code's MCP client

Troubleshooting

Common Issues

Issue	Possible Cause	Solution
Docker not found	Docker not installed/running	Install Docker Desktop, ensure it's running
Server won't start	Incorrect Control Panel settings	Run `Configure MCP Server`, verify settings
Port already in use	Port conflict	Change Server Port in settings
Containers won't stop	Docker container issues	Use `Force Cleanup Containers` or restart Docker
API Key prompt missing	Missing MCP configuration	Check `.vscode/mcp.json` exists, reload VS Code
Configuration outdated	Stale configuration	Use `Reinstall MCP Server`
Server logs insufficient	Debug mode disabled	Enable Debug Mode for enhanced logging
Performance issues	Debug mode enabled in production	Disable Debug Mode for optimal performance

Debugging Steps

Enable Debug Mode for detailed diagnostics:

Command Palette → CAST Imaging MCP: Configure MCP Server → Debug Mode → Enable Debug Mode
Command Palette → CAST Imaging MCP: Restart MCP Server

Check server status:

Command Palette → CAST Imaging MCP: Check Server Status

View detailed logs:

Command Palette → CAST Imaging MCP: View Server Logs

Verify Docker containers:
```
docker compose ps
```

Test Control Panel connectivity:

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

Nuclear cleanup for persistent issues:

Command Palette → CAST Imaging MCP: Force Cleanup Containers
Command Palette → CAST Imaging MCP: Reinstall MCP Server

Getting Help

Troubleshooting escalation:

Enable Debug Mode for enhanced logging
View server logs for detailed error information
Check server status for container health
Verify Docker installation and network connectivity
Use force cleanup for persistent container issues
Use reinstall for persistent configuration issues
Restart VS Code for extension-related issues

Technical Details

Architecture Overview

VS Code MCP Client
    ↓ (HTTP + API Key Authentication)
Docker Container (MCP Server)
    ↓ (HTTP/HTTPS based on Control Panel SSL setting)
CAST Imaging Control Panel Service

Container Architecture

The extension uses a single Docker container running the MCP server:

MCP Server Container: Provides HTTP endpoint for MCP client connections
Control Panel Connection: Configurable HTTP or HTTPS connection to external Control Panel

File System Organization

Component	Location	Description
Server Installation	VS Code global storage	Per-machine installation
MCP Configuration	`.vscode/mcp.json`	Per-workspace configuration
Copilot Instructions	`.github/copilot-instructions.md`	Per-workspace instructions
Docker Files	Installation directory	Auto-generated configurations
Server Logs	Installation directory/logs	Debug mode log files

Security Considerations

API Key Management: Handled by VS Code's built-in MCP client
Container Isolation: Docker provides process and network isolation
Configuration Separation: Per-workspace settings prevent cross-contamination
Control Panel SSL: Optional SSL/TLS encryption for Control Panel connections

Ready to enhance your development workflow with CAST Imaging architectural insights!

CAST Imaging MCP Server

CAST Imaging