# 🧩 Ansible MCP Server

一个完全遵循 **Model Context Protocol (MCP)** 标准的 Ansible 控制服务，通过 SSE 协议暴露工具接口，可接入任何支持 MCP 协议的 AI 客户端（如 Claude Desktop、Dify、Coze 等）。

## 工具列表

| 工具 | 说明 |
|------|------|
| `list_inventory` | 列出 Ansible Inventory 主机组结构（JSON） |
| `list_hosts` | 列出 Inventory 中所有主机 |
| `ping_hosts` | Ping 测试所有主机 |
| `run_ad_hoc` | 执行 Ansible ad-hoc 命令（模块白名单保护） |
| `validate_playbook` | 语法检查 Playbook 文件 |
| `run_playbook` | 执行 Playbook 并返回结果 |
| `list_playbooks` | 列出 playbooks 目录下的可用文件 |
| `generate_playbook` | 生成 Playbook 文件到 playbooks 目录 |
| `delete_playbook` | 删除 playbooks 目录下的文件 |
| `get_ansible_version` | 查询 Ansible 版本信息 |

## MCP 协议端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/sse` | GET | SSE 连接入口 |
| `/sse/messages/` | POST | 发送 JSON-RPC 消息 |
| `/health` | GET | 健康检查 |

## 调用方式

MCP 工具支持两种调用格式：

### 方式一：标准 MCP 协议
```json
{"method": "tools/call", "params": {"name": "list_hosts", "arguments": {}}}
```

### 方式二：直接方法名（兼容）
```json
{"method": "list_hosts", "params": {}}
```

## 安全特性

- **路径越界防护**：所有文件路径校验，阻止目录遍历攻击
- **模块白名单**：ad-hoc 命令仅允许 45 个常用安全模块
- **超时保护**：所有命令默认 60s 超时，Ping 默认 30s
- **异常保护**：所有错误返回 JSON-RPC 标准错误响应
- **参数安全**：所有工具参数均使用 `.get()` 安全访问，缺失参数返回明确错误提示

## 配置（环境变量）

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `ANSIBLE_MCP_TIMEOUT` | `60` | 命令超时时间（秒） |
| `ANSIBLE_MCP_PLAYBOOKS_DIR` | `./playbooks` | Playbook 存储目录 |
| `ANSIBLE_MCP_INVENTORY` | `./inventory.ini` | 默认 Inventory 文件路径 |

## 启动方式

### 使用 uv（推荐）
```bash
uv venv
uv pip install -r requirements.txt
uv run uvicorn main:app --host 0.0.0.0 --port 8080
```

### 后台运行
```bash
nohup uv run uvicorn main:app --host 0.0.0.0 --port 8080 \
  >/tmp/ansible_mcp.log 2>&1 &
```

### Docker
```bash
docker build -t ansible-mcp .
docker run -p 8080:8080 ansible-mcp
```

## 接入 MCP 客户端

在支持 MCP 的客户端中配置 SSE 连接地址：

```
http://<your-server-ip>:8080/sse
```

客户端会自动完成以下握手流程：
1. 连接 `/sse` 获取 `session_id`
2. 发送 `initialize` 请求完成握手
3. 调用 `tools/list` 自动发现工具列表
4. 调用 `tools/call` 执行具体工具

## 项目结构

```
ansible-mcp_python/
├── main.py              # FastAPI 入口
├── mcp_server.py        # 核心逻辑（MCP 协议 + 工具实现 + 安全校验）
├── inventory.ini        # Ansible 清单文件
├── playbooks/           # Playbook 存储目录（gitignored）
├── requirements.txt     # Python 依赖
├── Dockerfile           # 容器构建文件
├── README.md            # 文档
└── AGENTS.md            # 贡献者指南
```