# 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.

## Table of Contents

- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [Testing Methods](#testing-methods)
- [Configuration](#configuration)
- [Test Scenarios](#test-scenarios)
- [Automation](#automation)
- [Troubleshooting](#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

1. **Node.js** (v18 or higher) - for MCP Inspector
   ```bash
   # Windows (using winget)
   winget install OpenJS.NodeJS
   
   # Verify installation
   node --version
   npm --version
   npx --version
   ```

2. **Python 3.11+** and **UV** - already covered in main [README.md](README.md)

3. **Git** - for repository management

### Environment Setup

Ensure your environment variables are configured:

```bash
# 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

```bash
# Install Node.js packages for MCP Inspector
npm install

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

### 2. Run Quick Test

```bash
# 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](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

```bash
# Windows
scripts\test_with_inspector.bat

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

**Available Options:**
1. **Interactive UI Testing** - Real CipherTrust connection, opens browser
2. **CLI Automated Testing** - Real CipherTrust connection, command line
3. **Python Unit Tests** - Fast mock testing (~0.11s, no external connections)
4. **Full Mock Test Suite** - Comprehensive mock testing with validation
5. **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

1. **Start the server** in one terminal:
   ```bash
   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...
   ```

2. **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:**
```json
{"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)
```json
{"jsonrpc": "2.0", "method": "notifications/initialized"}
```

**3. List available tools:**
```json
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}
```

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

**5. Test system information:**
```json
{"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:
```json
{"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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```json
{
  "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:

```json
{
  "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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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

1. **Server Initialization**
   ```bash
   npx @modelcontextprotocol/inspector --cli --config tests/mcp_inspector_config.json --server ciphertrust-local --method tools/list
   ```

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

3. **Error Handling**
   ```bash
   npx @modelcontextprotocol/inspector --cli --config tests/mcp_inspector_config.json --server ciphertrust-local --method tools/call --tool-name invalid_tool
   ```

### More Test Scenarios

1. **Key Management Workflow**
   - List existing keys
   - Create new key
   - Verify key creation
   - Delete test key

2. **CTE Client Management**
   - List CTE clients
   - Create new clients
   - Test client operations

3. **Connection Management**
   - Test database connections
   - Verify LDAP connectivity
   - Test authentication

## Automation

### NPM Scripts

Add these to your workflow:

```bash
# 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

1. **Node.js Not Found**
   ```bash
   # Error: 'node' is not recognized
   # Solution: Install Node.js or add to PATH
   winget install OpenJS.NodeJS
   ```

2. **Manual JSON-RPC Testing Issues**
   ```bash
   # 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
   ```

3. **MCP Inspector Connection Failed**
   ```bash
   # Error: Failed to connect to MCP server
   # Check: Environment variables and CipherTrust Manager connectivity
   echo $CIPHERTRUST_URL
   ```

4. **Python Import Errors**
   ```bash
   # 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 .
   ```

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

### Debug Mode

Enable verbose logging for troubleshooting:

```bash
# 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](EXAMPLE_PROMPTS.md) - Ready-to-use prompts for testing with Claude Desktop/Cursor
- [MCP Inspector Documentation](https://github.com/modelcontextprotocol/inspector)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Python pytest Documentation](https://docs.pytest.org/)
- [Node.js](https://nodejs.org/en)

---