MCP Server API (user) documentation (#2302)

* MCP Server API (user) documentation

* chore: auto fixes from pre-commit.com hooks

* fix cspell

* added the tab in user docs

* chore: auto fixes from pre-commit.com hooks

* fixed th preflight issue

* chore: auto fixes from pre-commit.com hooks

* moved section up side down

* chore: auto fixes from pre-commit.com hooks

* fix the issue

* docs: Address PR review feedback for MCP documentation

- Simplify MCP section in main README, remove installation code
- Add links to both MCP overview and API reference docs
- Update status from 'testing and development' to 'technical preview'
- Add server startup instructions with examples for Cursor and Claude Desktop
- Remove 'Planned Implementation' section from API docs
- Move API Reference Summary to top of API documentation
- Remove planned WebSocket transport references

* chore: Add 'bindep' to cspell dictionary

---------

Co-authored-by: anushka-shukla-03 <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Alison Hart <[email protected]>
Co-authored-by: Shatakshi Mishra <[email protected]>

Author: 5 people

.config/dictionary.txt

@@ -30,6 +30,7 @@ Tomasz
 Towncrier
 antsibull
 autofetch
+bindep
 cfgs
 checode
 chromedriver

.markdownlint.yaml

@@ -4,3 +4,4 @@
 MD014: false # Dollar signs used before commands without showing output (we use mkdocs-material to add the real output)
 MD013: false # Line length (we should only use reformatting tool for this, like prettier)
 MD046: false # raises false possibilities with mkdocs-material admonitions https://squidfunk.github.io/mkdocs-material/reference/admonitions/
+MD060: false # Table column style - tables are valid even if not perfectly aligned

docs/README.md

@@ -363,6 +363,23 @@ which you can learn more about at
   block structures, is not yet implemented. Basic YAML highlighting will apply
   within these blocks.
 
+## Model Context Protocol (MCP) Server
+
+The extension includes an MCP server that enables AI assistants and LLM-powered tools to interact with Ansible development workflows. The MCP server provides 11 specialized tools (across multiple branches) for:
+
+- 🔍 Ansible playbook linting with automatic fixes
+- 🛠️ Development environment setup and management
+- 📦 Project scaffolding (playbooks and collections)
+- 🐳 Execution environment generation with schema validation
+- 📊 Environment diagnostics and information
+- 🚀 Playbook execution with ansible-navigator (auto-detection, Podman handling)
+- 📖 Ansible content best practices and guidelines
+
+### Learn More
+
+- **[MCP Server Overview](mcp/README.md)** - Features, architecture, and getting started guide
+- **[API Reference](mcp/api.md)** - Complete technical API documentation for all tools and resources
+
 ## Contact
 
 We welcome your feedback, questions and ideas. Learn how to

docs/mcp/README.md

@@ -0,0 +1,108 @@
+# Ansible MCP Server
+
+The Ansible MCP (Model Context Protocol) Server enables AI assistants and language models to interact with Ansible tooling through a standardized protocol. It provides intelligent automation capabilities for Ansible development workflows.
+
+## What is MCP?
+
+The Model Context Protocol (MCP) is an open protocol that standardizes how AI applications interact with external tools and data sources. The Ansible MCP Server implements this protocol to expose Ansible development tools to AI assistants.
+
+## Features
+
+The Ansible MCP Server provides the following capabilities:
+
+### 📚 Information & Documentation
+
+- **Zen of Ansible**: Access Ansible's design philosophy and principles
+- **Best Practices**: Get comprehensive guidelines for writing quality Ansible content
+- **Tool Discovery**: List all available MCP tools and their capabilities
+
+### 🔧 Environment Management
+
+- **Environment Info**: Check Python, Ansible, and development tool versions
+- **Setup Automation**: Automatically configure virtual environments and install dependencies
+- **Tool Installation**: Install and verify Ansible Development Tools (ADT)
+
+### 🏗️ Project Scaffolding
+
+- **Playbook Creation**: Generate new Ansible playbooks with proper structure
+- **Collection Creation**: Scaffold new Ansible collections with best practices
+
+### ✅ Code Quality
+
+- **Ansible Lint**: Automated linting with fix capabilities
+- **Execution Environment Builder**: Create and validate execution environment definitions
+
+### ▶️ Playbook Execution
+
+- **Ansible Navigator**: Execute playbooks with smart environment detection and container management
+
+## Getting Started
+
+The Ansible MCP Server is currently available as a technical preview.
+
+The server runs as a child process and communicates via stdio transport.
+
+### Requirements
+
+- Python 3.11 or higher
+- Node.js 18 or higher
+- Ansible development tools (can be auto-installed)
+
+### Starting the Server
+
+The MCP server is automatically started by MCP-compatible AI assistants when configured. No manual installation or server management is required.
+
+**For Cursor IDE:**
+
+The extension automatically starts the MCP server when accessed from Cursor's MCP integration.
+
+**For Claude Desktop:**
+
+Add the following configuration to your Claude Desktop settings:
+
+```json
+{
+  "mcpServers": {
+    "ansible": {
+      "command": "node",
+      "args": [
+        "/path/to/vscode-ansible/out/mcp/index.js"
+      ],
+      "env": {
+        "WORKSPACE_ROOT": "/path/to/your/ansible/project"
+      }
+    }
+  }
+}
+```
+
+## Architecture
+
+```text
+┌─────────────────┐
+│  AI Assistant   │
+└────────┬────────┘
+         │ MCP Protocol
+         │ (JSON-RPC 2.0)
+┌────────▼────────┐
+│  Ansible MCP    │
+│     Server      │
+└────────┬────────┘
+         │
+    ┌────┴────┐
+    │         │
+┌───▼───┐ ┌──▼──────┐
+│Ansible│ │ Ansible │
+│ Tools │ │  APIs   │
+└───────┘ └─────────┘
+```
+
+### Usage with AI Assistants
+
+The MCP server integrates with AI assistants that support the Model Context Protocol. When configured, AI assistants can:
+
+- Answer questions about Ansible best practices
+- Help set up development environments
+- Generate and validate Ansible content
+- Lint and fix playbook issues
+- Execute playbooks with intelligent error handling