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
HTTPS Configuration
Debug Mode Configuration
Switching Between HTTP and HTTPS
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/HTTPS support with nginx proxy
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

Optional

SSL certificates (for HTTPS connections)

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`
HTTPS Enabled	Enable HTTPS with nginx proxy	`false`
Debug Mode	Enable enhanced logging and debugging features	`false`
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}"
      }
    }
  }
}

Note: URL automatically updates based on HTTP/HTTPS configuration

`.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: '**')

HTTPS Configuration

Enable HTTPS

Configure HTTPS in extension settings:

CAST Imaging MCP: Configure MCP Server → HTTPS Enabled → Enable HTTPS

Certificate setup:
- Extension creates .vscode/certificates folder
- Add your SSL certificates:
  - certificate.pem - SSL certificate
  - private_key.pem - Private key
Restart server:
```
CAST Imaging MCP: Restart MCP Server
```

Certificate Folder Structure

your-workspace/
├── .vscode/
│   ├── mcp.json
│   └── certificates/
│       ├── certificate.pem
│       └── private_key.pem
└── ...

HTTPS Architecture

When HTTPS is enabled, nginx acts as an SSL proxy:

Client Request (HTTPS:8443)
    ↓
nginx (SSL Termination)
    ↓ 
mcp-server:8282 (Main HTTP Backend)
mcp-server:8283 (Health Check Backend)

nginx capabilities:

SSL/TLS termination
Security headers management
Gzip compression
Load balancing
WebSocket upgrades
Request buffering and timeouts

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.

Switching Between HTTP and HTTPS

HTTP to HTTPS Migration

Stop the server:
```
CAST Imaging MCP: Stop MCP Server
```

Enable HTTPS:

Command Palette → CAST Imaging MCP: Configure MCP Server → HTTPS Enabled → Enable HTTPS

Add SSL certificates:
- Extension creates .vscode/certificates/ folder
- Place certificate files:
  - certificate.pem
  - private_key.pem
Start server:
```
CAST Imaging MCP: Start MCP Server
```

HTTPS to HTTP Migration

Stop the server:
```
CAST Imaging MCP: Stop MCP Server
```

Disable HTTPS:

Command Palette → CAST Imaging MCP: Configure MCP Server → HTTPS Enabled → Disable HTTPS

Start server:
```
CAST Imaging MCP: Start MCP Server
```

Migration Notes

✅ Automatic updates:

MCP configuration updates automatically
No container reinstall required
Different Docker Compose configurations used seamlessly
SSL certificates preserved when switching to HTTP

⚠️ Troubleshooting switching issues: If you encounter port conflicts or stuck containers:

Command Palette → CAST Imaging MCP: Force Cleanup Containers

This command will:

Stop all MCP-related containers
Remove stuck containers and networks
Free up all ports
Enable clean restart in any mode

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"

# 3. Optional: Enable HTTPS
Command Palette → "CAST Imaging MCP: Configure MCP Server"  
→ HTTPS Enabled → "Enable HTTPS"
→ Add certificates to .vscode/certificates/

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

# 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 HTTPS/Debug 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
SSL Certificate not found	Missing certificates (HTTPS mode)	Add certificates to `.vscode/certificates/`
nginx container fails	nginx configuration issues	Use `Reinstall MCP Server`
Port conflicts when switching	Stuck containers from previous mode	Use `Force Cleanup Containers`
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 config after HTTP/HTTPS switch	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/HTTPS + API Key Authentication)
nginx Proxy (HTTPS mode only) 
    ↓
Docker Container (MCP Server)
    ↓
CAST Imaging Control Panel Service

Container Architecture

Mode	Containers	Description
HTTP Mode	Single MCP server container	Direct HTTP connection
HTTPS Mode	MCP server + nginx proxy	SSL termination via nginx

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
SSL Certificates	`.vscode/certificates/`	Per-workspace certificates
Docker Files	Installation directory	Auto-generated configurations

Security Considerations

API Key Management: Handled by VS Code's built-in MCP client
SSL Certificate Storage: Workspace-specific and portable
Container Isolation: Docker provides process and network isolation
Configuration Separation: Per-workspace settings prevent cross-contamination

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

CAST Imaging MCP Server

CAST Imaging