Ansible Collection Mcp Audit

Code Quality Ansible Sanity Security License REUSE status Galaxy Ask DeepWiki

Ansible collection for testing and auditing Model Context Protocol (MCP) servers. Provides comprehensive modules to verify MCP server implementations, test tools, resources, and prompts with detailed reporting capabilities.

Features

• Server Discovery: Gather comprehensive information about MCP server capabilities
• Tool Testing: Invoke and validate individual MCP tools with expected results
• Resource Testing: Retrieve and verify MCP resources with content validation
• Prompt Testing: Test prompt templates with argument validation
• Test Suites: Orchestrate multiple tests with comprehensive reporting
• LLM Integration: End-to-end testing with real LLMs via LiteLLM (100+ providers supported)
• Connection Pooling: Reuse connections across module calls for better performance (v1.1.0+)
• Multi-Transport: Support for stdio, SSE (Server-Sent Events), and HTTP transports
• Cross-Language: Tested with Python and TypeScript MCP servers
• RHEL Ready: Compatible with RHEL 9/10, Python 3.9-3.13, ansible-core 2.15-2.17

Installation

From Ansible Galaxy

ansible-galaxy collection install tosin2013.mcp_audit

The collection is automatically published to Ansible Galaxy when a version tag (e.g., v1.1.1) is pushed to the repository after all CI tests pass

See docs/GALAXY-PUBLISHING.md for details on the publishing workflow.

From Source

# Clone the repository
git clone https://github.com/tosin2013/ansible-collection-mcp-audit.git
cd ansible-collection-mcp-audit

# Install dependencies
pip install -r requirements.txt

# Build the collection
ansible-galaxy collection build

# Install locally
ansible-galaxy collection install mcp-audit-*.tar.gz

Requirements

• Python: 3.10 or later (MCP SDK requirement; see Issue #19)
• Ansible: ansible-core 2.15.0 or later
• MCP Python SDK: 1.19.0 or later (automatically installed)
• Operating Systems: Linux (RHEL 9+, Ubuntu 20.04+, Debian 11+), macOS 11+

Quick Start

Test an MCP Server

---
- name: Test MCP Server
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Get server information
      tosin2013.mcp_audit.mcp_server_info:
        transport: stdio
        server_command: python -m mcp_server_example
      register: server_info

    - name: Display capabilities
      ansible.builtin.debug:
        var: server_info.capabilities

Run a Tool Test

- name: Test calculator add tool
  tosin2013.mcp_audit.mcp_test_tool:
    transport: stdio
    server_command: python -m calculator_mcp_server
    tool_name: add
    tool_arguments:
      a: 5
      b: 3
    expected_result:
      result: 8
  register: tool_test

- name: Check test passed
  ansible.builtin.assert:
    that:
      - tool_test.success
      - tool_test.test_passed

Modules

Core Modules

Module	Description	Status
mcp_server_info	Discover server capabilities and metadata	✅ Available
mcp_test_tool	Test individual MCP tools	✅ Available
mcp_test_resource	Test MCP resources	✅ Available
mcp_test_prompt	Test MCP prompts	✅ Available
mcp_test_suite	Run comprehensive test suites	✅ Available
mcp_test_llm_integration	End-to-end testing with real LLMs	✅ Available

Transport Support

• stdio: Process-based communication (default)
• SSE: Server-Sent Events over HTTP
• HTTP: Direct HTTP/HTTPS communication

Documentation

• Galaxy Publishing Guide - How to publish to Ansible Galaxy
• Architectural Decision Records - All ADRs and design decisions
• Security Policy - Security reporting and vulnerability policy
• Contributing Guidelines - How to contribute to the project
• AI Agent Guidelines - Coding best practices for AI agents
• Module Documentation - See built-in ansible-doc for each module
• Examples & Tutorials - See integration tests in tests/integration/

Development

Setup Development Environment

# Clone and enter directory
git clone https://github.com/tosin2013/ansible-collection-mcp-audit.git
cd ansible-collection-mcp-audit

# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

Run Quality Checks

# Run all quality checks
make quality

# Run individual checks
make lint        # Linting (ruff, yamllint, ansible-lint)
make format      # Code formatting (ruff)
make type-check  # Type checking (mypy)
make test        # Unit tests (pytest)

Run Ansible Sanity Tests

ansible-test sanity --docker

Architecture

This collection follows Ansible best practices and is built on solid architectural decisions:

• ADR-0001: Collection namespace selection (currently tosin2013.mcp_audit)
• ADR-0002: MCP Python SDK selection
• ADR-0003: Module architecture pattern
• ADR-0008: Licensing strategy (GPL-3.0-or-later)
• All ADRs: Complete architectural decisions

License

This collection is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).

• Modules (plugins/modules/): GPL-3.0-or-later only
• Module utilities (plugins/module_utils/): Dual-licensed GPL-3.0-or-later OR BSD-2-Clause

See COPYING for the full GPL-3.0 license text and LICENSES/ for all license files.

This collection is REUSE compliant.

Security

Security is a top priority. Please report security vulnerabilities privately:

• Preferred: Use GitHub Security Advisories
• Email: [email protected] (Subject: [SECURITY] MCP Audit Collection)

See SECURITY.md for our complete security policy and response timelines.

Contributing

Contributions are welcome! Please see our Contributing Guidelines (coming soon) for:

• Code of Conduct
• Development workflow
• Pull request process
• Testing requirements
• Code quality standards

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: GitHub Wiki (coming soon)

Roadmap

Version 1.0.0 (Target: Q1 2025)

• ✅ Architectural foundation (Phase 0) - COMPLETE
• ✅ Infrastructure setup (Phase 1) - COMPLETE
• ✅ Module utilities development (Phase 2) - COMPLETE
• ✅ Core modules implementation (Phase 3) - COMPLETE
• ✅ Integration testing (Phase 4) - COMPLETE
• ✅ Galaxy publication (Phase 6) - COMPLETE (Published v1.0.0)
• 🚧 Documentation and examples (Phase 5) - IN PROGRESS

Version 1.1.0 (Released: 2025-10-30)

• ✅ LiteLLM integration (Phase 8) - COMPLETE
• ✅ End-to-end LLM → MCP tool → Result flow validated
• ✅ Multi-provider support (Ollama, OpenRouter, vLLM, 100+ providers)
• ✅ Secure credential management with Ansible Vault

Version 1.1.1 (Released: 2025-11-03)

• ✅ Bug fixes for GitHub Actions workflows
• ✅ Code quality improvements (ruff linting and formatting)
• ✅ Enhanced documentation for connection pooling features
• ✅ Python 3.11 and 3.13 compatibility verified across ansible-core 2.15-2.17

Current Status: ✅ v1.1.1 Published to Galaxy | Production ready

Credits

• Maintainer: Tosin Akinosho (@tosin2013)
• MCP Protocol: Model Context Protocol by Anthropic
• MCP Python SDK: modelcontextprotocol/python-sdk

Links

• Repository: https://github.com/tosin2013/ansible-collection-mcp-audit
• Ansible Galaxy: https://galaxy.ansible.com/ui/repo/published/tosin2013/mcp_audit/
• Model Context Protocol: https://modelcontextprotocol.io/
• MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk

---

Status: ✅ Published to Ansible Galaxy Version: 1.1.1 Galaxy: tosin2013.mcp_audit Last Updated: 2025-11-03