mcp-adr-analysis-server

# Ansible Testing Setup for MCP Server

This guide explains how to set up and use Ansible with Python 3.11 to test the MCP ADR Analysis Server using the `tosin2013.mcp_audit` collection from Ansible Galaxy.

## Overview

We use Ansible playbooks to automate testing and validation of the MCP server. This setup uses:

- **Python 3.11**: Virtual environment for Ansible
- **Ansible**: Automation tool for testing
- **tosin2013.mcp_audit**: Ansible Galaxy collection for MCP server testing

## Quick Start

### 1. Create and Activate Virtual Environment

The virtual environment has already been created at `venv-ansible/`. To activate it:

```bash
source venv-ansible/bin/activate
```

### 2. Verify Setup

```bash
# Check Python version (should be 3.11.x)
python --version

# Check Ansible installation
ansible --version

# Verify collection is installed
ansible-galaxy collection list | grep mcp_audit
```

### 3. Run Tests

```bash
cd playbooks
ansible-playbook test-mcp-server.yml
```

## Detailed Setup

### Step 1: Create Python 3.11 Virtual Environment

```bash
# Create virtual environment
python3.11 -m venv venv-ansible

# Activate virtual environment
source venv-ansible/bin/activate
```

### Step 2: Install Ansible and MCP SDK

```bash
# Upgrade pip
pip install --upgrade pip setuptools wheel

# Install Ansible
pip install ansible

# Install MCP Python SDK (required by mcp_audit collection)
pip install mcp
```

### Step 3: Install MCP Audit Collection

```bash
# Install from Ansible Galaxy
ansible-galaxy collection install tosin2013.mcp_audit

# Or install from requirements file
ansible-galaxy collection install -r ansible-requirements.yml
```

### Step 4: Verify Installation

```bash
# Check Ansible version
ansible --version

# List installed collections
ansible-galaxy collection list

# Check available MCP modules
ansible-doc -l | grep mcp
```

## Project Structure

```
mcp-adr-analysis-server/
├── venv-ansible/              # Python 3.11 virtual environment
├── ansible.cfg                # Ansible configuration
├── ansible-requirements.yml   # Collection requirements
├── playbooks/                 # Ansible playbooks
│   ├── README.md             # Playbook documentation
│   └── test-mcp-server.yml   # Main test playbook
└── ANSIBLE_SETUP.md          # This file
```

## Usage

### Running the Test Playbook

```bash
# Activate virtual environment
source venv-ansible/bin/activate

# Navigate to playbooks directory
cd playbooks

# Run the test playbook
ansible-playbook test-mcp-server.yml
```

### Testing with Custom Options

```bash
# Run with verbose output
ansible-playbook test-mcp-server.yml -v

# Run with extra verbose output (for debugging)
ansible-playbook test-mcp-server.yml -vvv

# Override server path
ansible-playbook test-mcp-server.yml -e "mcp_server_path=/custom/path"

# Increase timeout
ansible-playbook test-mcp-server.yml -e "mcp_timeout=60"
```

## What Gets Tested

The test playbook validates:

1. **Server Availability**: Verifies the server binary exists and can be executed
2. **Server Information**: Retrieves server name, version, and capabilities
3. **Tool Endpoints**: Tests that tools can be listed and called
4. **Resource Endpoints**: Tests that resources can be listed
5. **Prompt Endpoints**: Tests that prompts can be listed

## Troubleshooting

### Issue: Python 3.11 Not Found

**Solution**: Install Python 3.11 using Homebrew:

```bash
brew install python@3.11
```

### Issue: Collection Not Found

**Solution**: Install the collection explicitly:

```bash
source venv-ansible/bin/activate
ansible-galaxy collection install tosin2013.mcp_audit --force
```

### Issue: Server Binary Not Found

**Solution**: Build the server first:

```bash
npm run build
```

### Issue: Module Import Errors

**Solution**: Ensure the MCP Python SDK is installed:

```bash
source venv-ansible/bin/activate
pip install mcp

# Verify installation
python -c "from mcp import ClientSession; print('MCP SDK OK')"
```

### Issue: Permission Errors

**Solution**: Ensure the server binary is executable:

```bash
chmod +x dist/src/index.js
```

## Integration with CI/CD

You can integrate these tests into your CI/CD pipeline:

```yaml
# Example GitHub Actions workflow
- name: Setup Python 3.11
  uses: actions/setup-python@v4
  with:
    python-version: '3.11'

- name: Install Ansible
  run: |
    python -m venv venv-ansible
    source venv-ansible/bin/activate
    pip install ansible

- name: Install MCP Audit Collection
  run: |
    source venv-ansible/bin/activate
    ansible-galaxy collection install tosin2013.mcp_audit

- name: Run Ansible Tests
  run: |
    source venv-ansible/bin/activate
    cd playbooks
    ansible-playbook test-mcp-server.yml
```

## Additional Resources

- [Ansible Galaxy Collection](https://galaxy.ansible.com/ui/repo/published/tosin2013/mcp_audit/)
- [Ansible Documentation](https://docs.ansible.com/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Python Virtual Environments](https://docs.python.org/3/tutorial/venv.html)

## Maintenance

### Updating Collections

```bash
source venv-ansible/bin/activate
ansible-galaxy collection install tosin2013.mcp_audit --upgrade
```

### Recreating Virtual Environment

```bash
# Remove old environment
rm -rf venv-ansible

# Create new environment
python3.11 -m venv venv-ansible

# Activate and install dependencies
source venv-ansible/bin/activate
pip install --upgrade pip setuptools wheel
pip install ansible
ansible-galaxy collection install -r ansible-requirements.yml
```

## Support

For issues with:
- **Ansible setup**: Check this documentation
- **MCP Audit Collection**: Visit [Ansible Galaxy](https://galaxy.ansible.com/ui/repo/published/tosin2013/mcp_audit/)
- **MCP Server**: Check the main project README.md