Testing Guide for CipherTrust Manager MCP Server

This document provides comprehensive testing instructions for the CipherTrust Manager MCP Server using the Model Context Protocol Inspector and Python unit tests.

Overview
Prerequisites
Quick Start
Testing Methods
Configuration
Test Scenarios
Automation
Troubleshooting

Overview

The CipherTrust Manager MCP Server includes multiple testing approaches:

Interactive UI Testing: Visual interface for manual testing and debugging
CLI Automated Testing: Command-line automation for CI/CD integration
Python Unit Tests: Comprehensive unit testing for server components
Integration Tests: End-to-end testing with real CipherTrust Manager instances

Prerequisites

Required Software

Node.js (v18 or higher) - for MCP Inspector

# Windows (using winget)
winget install OpenJS.NodeJS

# Verify installation
node --version
npm --version
npx --version

Python 3.11+ and UV - already covered in main README.md
Git - for repository management

Environment Setup

Ensure your environment variables are configured:

# Required
CIPHERTRUST_URL=https://your-ciphertrust-manager.example.com
CIPHERTRUST_USER=your-username
CIPHERTRUST_PASSWORD=your-password

# Optional
CIPHERTRUST_NOSSLVERIFY=true  # for test environments
CIPHERTRUST_TIMEOUT=30
LOG_LEVEL=DEBUG  # for testing

Quick Start

1. Install Testing Dependencies

# Install Node.js packages for MCP Inspector
npm install

# Install Python testing dependencies
uv pip install pytest pytest-asyncio

2. Run Quick Test

# Interactive UI testing (opens browser)
npx @modelcontextprotocol/inspector --config tests/mcp_inspector_config.json --server ciphertrust-local

# Quick CLI testing
# Get tools
npx @modelcontextprotocol/inspector --cli --config tests/mcp_inspector_config.json --server ciphertrust-local --method tools/list
# Get system information
npx @modelcontextprotocol/inspector --cli --config tests/mcp_inspector_config.json --server ciphertrust-local --method tools/call --tool-name system_information --tool-arg action=get
# Get 2 keys
npx @modelcontextprotocol/inspector --cli --config tests/mcp_inspector_config.json --server ciphertrust-local --method tools/call --tool-name key_management --tool-arg action=list --tool-arg limit=2

3. Try Example AI Assistant Prompts

For hands-on testing with AI assistants like Claude Desktop or Cursor, see EXAMPLE_PROMPTS.md for ready-to-use prompts covering:

Key management operations
User and group management
CTE operations
Crypto operations
And many more scenarios

3. Using Test Scripts

# Windows
scripts\test_with_inspector.bat

# Unix/Linux/macOS
chmod +x scripts/test_with_inspector.sh
./scripts/test_with_inspector.sh

Available Options:

Interactive UI Testing - Real CipherTrust connection, opens browser
CLI Automated Testing - Real CipherTrust connection, command line
Python Unit Tests - Fast mock testing (~0.11s, no external connections)
Full Mock Test Suite - Comprehensive mock testing with validation
Full Integration Test Suite - Real CipherTrust Manager testing

Testing Methods

1. Manual JSON-RPC Testing (Direct stdin/stdout)

You can test the MCP server directly by sending JSON-RPC commands to it via stdin. This is useful for debugging and development without additional tools.

Setup for Manual Testing

Start the server in one terminal:

uv run ciphertrust-mcp-server

You should see output like:

2025-06-17 17:37:19,394 - ciphertrust_mcp_server.server - INFO - Successfully connected to CipherTrust Manager
2025-06-17 17:37:19,396 - ciphertrust_mcp_server.server - INFO - MCP server ready and waiting for JSON-RPC messages on stdin...

Send commands to the server (in the same terminal where the server is running)

Manual Test Commands

⚠️ Important: Each JSON command must be on a single line and end with Enter. Copy and paste these commands one by one:

1. Initialize the server:

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "clientInfo": {"name": "test-client", "version": "1.0.0"}, "capabilities": {"tools": {}}}}

2. Send initialized notification: (Server does not respond)

{"jsonrpc": "2.0", "method": "notifications/initialized"}

3. List available tools:

{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}

4. Test key management:

{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "key_management", "arguments": {"action": "list", "limit": 5}}}

5. Test system information:

{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "system_information", "arguments": {"action": "get"}}}

Expected Responses

Each command (except notifications) should return a JSON-RPC response:

{"jsonrpc": "2.0", "id": 1, "result": {...}}

Manual Testing Troubleshooting

No response after initialize: Check that all required environment variables are set
"Method not found" error: Ensure you send the initialize command first
Tool call failures: Verify connectivity to your CipherTrust Manager instance

Prerequisites for Manual Testing

Server must be running (see "How to Start the Server" in main README)
Required environment variables must be set (CIPHERTRUST_URL, credentials, etc.)

2. Interactive UI Testing

The MCP Inspector provides a web-based interface for testing:

# Start with default configuration
npx @modelcontextprotocol/inspector uv run ciphertrust-mcp-server

# Start with custom configuration
npx @modelcontextprotocol/inspector --config tests/mcp_inspector_config.json --server ciphertrust-local

Features:

Visual tool testing interface
Real-time request/response viewing
Resource and prompt exploration
Connection management
Debug logging

Access: Open http://localhost:6274 in your browser

3. CLI Automated Testing

Command-line testing for automation and scripting:

# List available tools
npx @modelcontextprotocol/inspector --cli \
  --config tests/mcp_inspector_config.json \
  --server ciphertrust-local \
  --method tools/list

# Test specific tool
npx @modelcontextprotocol/inspector --cli \
  --config tests/mcp_inspector_config.json \
  --server ciphertrust-local \
  --method tools/call \
  --tool-name system_information \
  --tool-arg action=get

# Test with environment variables
npx @modelcontextprotocol/inspector --cli \
  -e CIPHERTRUST_URL=https://test.example.com \
  -e LOG_LEVEL=DEBUG \
  uv run ciphertrust-mcp-server \
  --method tools/list

3. Python Unit Tests

Comprehensive testing of server components:

# Run all tests
uv run python -m pytest tests/test_server.py -v

# Run specific test categories
uv run python -m pytest tests/test_server.py::TestCipherTrustMCPServer -v
uv run python -m pytest tests/test_server.py::TestToolFunctions -v

# Run with coverage
uv run python -m pytest tests/test_server.py --cov=ciphertrust_mcp_server

# Run integration tests (requires real environment)
uv run python -m pytest tests/test_server.py -m integration -v

5. Full Test Suite

Run comprehensive testing using the test scripts:

# Using test scripts (recommended)
scripts\test_with_inspector.bat    # Windows
./scripts/test_with_inspector.sh   # Unix/Linux/macOS

# Choose from 5 testing options:
# 3. Python Unit Tests (Mock - Fast, no external connections) 
# 4. Full Mock Test Suite (Comprehensive mock testing)
# 5. Full Integration Test Suite (Real CipherTrust Manager testing)

# Manual execution
uv run python -m pytest tests/test_server.py -v                    # Unit tests
uv run python -m pytest tests/test_integration_simple.py -v -s     # Integration tests

Configuration

Inspector Configuration

Edit tests/mcp_inspector_config.json to customize testing environments:

{
  "mcpServers": {
    "ciphertrust-local": {
      "command": "uv",
      "args": ["run", "ciphertrust-mcp-server"],
      "env": {
        "CIPHERTRUST_URL": "https://test.example.com",
        "CIPHERTRUST_USER": "test-user",
        "CIPHERTRUST_PASSWORD": "test-password",
        "LOG_LEVEL": "DEBUG"
      }
    },
    "ciphertrust-staging": {
      "command": "uv",
      "args": ["run", "ciphertrust-mcp-server"],
      "env": {
        "CIPHERTRUST_URL": "https://test.example.com",
        "CIPHERTRUST_USER": "test-user",
        "CIPHERTRUST_PASSWORD": "test-password",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Test Scenarios

Customize tests/test_scenarios.json for your testing needs:

{
  "test_scenarios": [
    {
      "name": "Key Management Workflow",
      "description": "Test complete key lifecycle",
      "commands": [
        {
          "method": "tools/call",
          "tool": "key_management",
          "args": {"action": "list", "limit": 5}
        },
        {
          "method": "tools/call", 
          "tool": "key_management",
          "args": {
            "action": "create",
            "name": "test-key-{{timestamp}}",
            "algorithm": "AES",
            "size": 256
          }
        }
      ]
    }
  ]
}

Test Scenarios

Manual JSON-RPC Test Scenarios

Basic Server Validation

Scenario 1: Server Initialization and Tool Discovery

# 1. Start server
uv run ciphertrust-mcp-server

# 2. Initialize (copy-paste each line one by one)
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "clientInfo": {"name": "manual-test", "version": "1.0.0"}, "capabilities": {"tools": {}}}}

# 3. Send initialized notification (No response from serrver for this notification)
{"jsonrpc": "2.0", "method": "notifications/initialized"}

# 4. List tools to verify server is working
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}

Expected Result: Should return a list of available tools including key_management, system_information, cte_client_management, etc.

Scenario 2: Basic Tool Functionality Test

# Test system information (after initialization above)
{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "system_information", "arguments": {"action": "get"}}}

# Test key management list
{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "key_management", "arguments": {"action": "list", "limit": 5}}}

Expected Result: Should return system information and a list of keys (up to 5) from your CipherTrust Manager.

Error Handling Tests

Scenario 3: Invalid Tool Test

# Test invalid tool name (after initialization)
{"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "nonexistent_tool", "arguments": {}}}

Expected Result: Should return an error response indicating the tool doesn't exist.

Scenario 4: Invalid Arguments Test

# Test invalid arguments (after initialization)
{"jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": {"name": "key_management", "arguments": {"invalid_action": "test"}}}

Expected Result: Should return an error response about invalid arguments.

MCP Inspector Test Scenarios

Basic Functionality Tests

Server Initialization

npx @modelcontextprotocol/inspector --cli --config tests/mcp_inspector_config.json --server ciphertrust-local --method tools/list

Tool Execution

npx @modelcontextprotocol/inspector --cli --config tests/mcp_inspector_config.json --server ciphertrust-local --method tools/call --tool-name system_information --tool-arg action=get

Error Handling

npx @modelcontextprotocol/inspector --cli --config tests/mcp_inspector_config.json --server ciphertrust-local --method tools/call --tool-name invalid_tool

More Test Scenarios

Key Management Workflow
- List existing keys
- Create new key
- Verify key creation
- Delete test key
CTE Client Management
- List CTE clients
- Create new clients
- Test client operations
Connection Management
- Test database connections
- Verify LDAP connectivity
- Test authentication

Automation

NPM Scripts

Add these to your workflow:

# Available npm scripts
npm run test:inspector:ui      # Open UI testing interface
npm run test:inspector:cli     # Run CLI automated tests
npm run test:python           # Run Python unit tests
npm run test:full             # Run complete test suite

Troubleshooting

Common Issues

Node.js Not Found

# Error: 'node' is not recognized
# Solution: Install Node.js or add to PATH
winget install OpenJS.NodeJS

Manual JSON-RPC Testing Issues

# Error: No response after initialize command
# Solution: Check environment variables
echo $CIPHERTRUST_URL
echo $CIPHERTRUST_USER

# Error: "Method not found"
# Solution: Ensure you send the initialize command first

# Error: Tool call failures
# Solution: Verify CipherTrust Manager connectivity

MCP Inspector Connection Failed

# Error: Failed to connect to MCP server
# Check: Environment variables and CipherTrust Manager connectivity
echo $CIPHERTRUST_URL

Python Import Errors

# Error: Module not found
# Solution: Ensure virtual environment is activated
uv venv
source .venv/bin/activate  # Unix/Linux/macOS
.venv\Scripts\activate     # Windows
uv pip install -e .

Permission Errors

# Error: Permission denied
# Solution: Run as administrator or fix permissions
chmod +x scripts/test_with_inspector.sh

Debug Mode

Enable verbose logging for troubleshooting:

# Set debug environment
export LOG_LEVEL=DEBUG
export CIPHERTRUST_NOSSLVERIFY=true

# Run with verbose output
npx @modelcontextprotocol/inspector --cli \
  --config tests/mcp_inspector_config.json \
  --server ciphertrust-local \
  --method tools/list \
  --verbose

Resources

Example AI Assistant Prompts - Ready-to-use prompts for testing with Claude Desktop/Cursor
MCP Inspector Documentation
Model Context Protocol Specification
Python pytest Documentation
Node.js

FilesExpand file tree

TESTING.md

Latest commit

History

TESTING.md

File metadata and controls

Testing Guide for CipherTrust Manager MCP Server

Table of Contents

Overview

Prerequisites

Required Software

Environment Setup

Quick Start

1. Install Testing Dependencies

2. Run Quick Test

3. Try Example AI Assistant Prompts

3. Using Test Scripts

Testing Methods

1. Manual JSON-RPC Testing (Direct stdin/stdout)

Setup for Manual Testing

Manual Test Commands

Expected Responses

Manual Testing Troubleshooting

Prerequisites for Manual Testing

2. Interactive UI Testing

3. CLI Automated Testing

3. Python Unit Tests

5. Full Test Suite

Configuration

Inspector Configuration

Test Scenarios

Test Scenarios

Manual JSON-RPC Test Scenarios

Basic Server Validation

Error Handling Tests

MCP Inspector Test Scenarios

Basic Functionality Tests

More Test Scenarios

Automation

NPM Scripts

Troubleshooting

Common Issues

Debug Mode

Resources