DNM: Add MCP server for AI-agent access to AAP Gateway resources

[cidrblock]

Summary

Introduces an MCP (Model Context Protocol) server that exposes every ansible.platform resource as an AI-agent tool — dynamically generated from the collection's own DOCUMENTATION metadata. No per-resource boilerplate; ~800 lines of Python yield 22 tools with the same schema, validation, and idempotent behavior as the Ansible modules.

What's included

Two pip packages under packages/:

• ansible-platform-sdk — Makes the collection pip-installable under its ansible_collections.ansible.platform namespace so non-Ansible consumers (MCP servers, CLIs, etc.) can import and use the SDK directly. Uses pkgutil.extend_path namespace stubs and a build-time symlink to plugins/.

• ansible-platform-mcp — MCP server with stdio transport. Depends on ansible-platform-sdk. Compatible with Cursor, Claude Desktop, and any MCP client. Install: pip install -e packages/sdk -e packages/mcp-server.

Dual-mode tools:

Every tool supports two modes, selectable per invocation:

Mode	Behavior
execute	Calls the Gateway API via PlatformService and returns the structured result
emit	Returns the equivalent ansible.platform task YAML for playbook authoring

Documentation:

• docs/11-mcp-vision.md — Value proposition and strategic rationale for engineering leadership
• docs/12-mcp-architecture.md — Detailed design: startup lifecycle, data flow, module-level documentation, SDK packaging, testing with the mock server

Bugfix:

• Fix version_parse() fallback in registry.py when the packaging library is not installed — the standalone function was bound as an instance method on a dynamic class without staticmethod(), causing a "takes 1 positional argument but 2 were given" error.

Architecture

┌──────────────┐     ┌──────────────────────┐     ┌─────────────┐
│  AI Agent    │────▶│  ansible-platform-mcp│────▶│ AAP Gateway │
│  (Cursor,    │ MCP │                      │ SDK │             │
│   Claude,    │◀────│  discover / schema / │◀────│             │
│   etc.)      │     │  execute / emit      │     │             │
└──────────────┘     └──────────────────────┘     └─────────────┘

The server reuses the existing SDK — PlatformService, GatewayConfig, APIVersionRegistry — with zero code duplication. As modules are added to the collection, the MCP server gains tools automatically.

Tested

Full CRUD lifecycle verified against tools/mock_gateway_server.py:

• ✅ Create user → returns {id, changed: true}
• ✅ Find user → returns full resource
• ✅ Delete user → auto-lookup by name, then delete by ID
• ✅ Verify deletion → correctly reports "not found"
• ✅ Create team with org reference
• ✅ Emit mode → clean Ansible YAML output

Test plan

• pip install -e packages/sdk -e packages/mcp-server in a clean venv
• Start mock server: python tools/mock_gateway_server.py --port 9080
• Run MCP server: AAP_GATEWAY_URL=http://127.0.0.1:9080 AAP_USERNAME=admin AAP_PASSWORD=password AAP_VALIDATE_CERTS=false ansible-platform-mcp
• Verify tool listing (22 tools) via MCP client
• Test create/find/delete cycle in execute mode
• Test emit mode returns valid Ansible YAML
• Verify emit mode works without Gateway credentials