Ansible安全执行服务

# mcp_ansible Ansible为MCP Tool Server（HTTP） streamable-http）提供的项目。

1.一目了然

2.核心原则

• 禁止直接输入任意文件路径
• allow-list（ID）运行
• 记录审核日志（JSON line）
• 自动清理runs artifact（基于存档数量）

3.项目结构

mcp_ansible/
├─ main.py
├─ api/
│  ├─ mcp_router.py
│  └─ tools/
│     ├─ register.py
│     ├─ catalog_tools.py
│     ├─ run_tools.py
│     └─ context.py
├─ application/
│  ├─ env_loader.py
│  ├─ logging_config.py
│  ├─ registry_loader.py
│  └─ runner_wrapper.py
├─ domain/
│  └─ schemas.py
└─ policy/
   ├─ registry_playbooks.yaml
   ├─ registry_inventories.yaml
   └─ Playbook/

4.安装

pip install -e .

或

uv sync

5.部署封闭网络服务器（建议的过程）

5.1准备条件

• 封闭网络服务器Linux环境（例如Rocky9）
• 可以使用Python 3.11
• 准备Ansible执行环境
  • 方法A:在服务器上 ansible-core已安装
  • 方法B：脱机安装时 requirements-offline-with-ansible214.txt 使用

5.2在可上网的环境中准备软件包

Linux/macOS：

cd mcp_ansible
bash ./scripts/build_wheelhouse.sh

ansible-core包括：

cd mcp_ansible
REQUIREMENTS=requirements-offline-with-ansible214.txt bash ./scripts/build_wheelhouse.sh

Windows PowerShell：

cd mcp_ansible
powershell -ExecutionPolicy Bypass -File .\scripts\build_wheelhouse.ps1

ansible-core包括：

cd mcp_ansible
powershell -ExecutionPolicy Bypass -File .\scripts\build_wheelhouse.ps1 -Requirements requirements-offline-with-ansible214.txt

5.3复制到封闭网络服务器

复制以下内容。

• mcp_ansible/
• wheelhouse/

5.4在封闭网络服务器上脱机安装

Linux：

cd /engn/mcp/mcp_ansible
bash ./scripts/install_offline.sh

ansible-core 嵌入式安装：

cd /engn/mcp/mcp_ansible
REQUIREMENTS=requirements-offline-with-ansible214.txt bash ./scripts/install_offline.sh

Windows PowerShell：

cd D:\MCPTools\mcp_ansible
powershell -ExecutionPolicy Bypass -File .\scripts\install_offline.ps1

ansible-core包括：

cd D:\MCPTools\mcp_ansible
powershell -ExecutionPolicy Bypass -File .\scripts\install_offline.ps1 -Requirements requirements-offline-with-ansible214.txt

5.5 .env 设置（重要）

policy/*.yaml的路径使用环境变量替换，因此将其设置为实际放置路径。

例子:

ANSIBLE_MCP_HOST=0.0.0.0
ANSIBLE_MCP_PORT=5000
ANSIBLE_MCP_HTTP_PATH=/mcp

ANSIBLE_MCP_PLAYBOOK_ROOT=/engn/ansible/playbook
ANSIBLE_MCP_INVENTORY_ROOT=/engn/ansible
ANSIBLE_CONFIG=/engn/ansible/ansible.cfg

ANSIBLE_MCP_RUNS_DIR=/var/lib/ansible-mcp/runs
ANSIBLE_MCP_STDOUT_MAX_LINES=300
ANSIBLE_MCP_LOG_LEVEL=INFO
ANSIBLE_MCP_LOG_DIR=/var/log/ansible-mcp
ANSIBLE_MCP_LOG_MAX_BYTES=10485760
ANSIBLE_MCP_LOG_BACKUP_COUNT=5

如果使用自定义env路径：

ANSIBLE_MCP_ENV_FILE=/etc/ansible-mcp/.env ./mcp_ansible/.venv/bin/python -m mcp_ansible.main

5.6服务器启动/停止/状态检查

机动：

cd /engn/mcp/mcp_ansible
bash ./scripts/start.sh

停止：

cd /engn/mcp/mcp_ansible
bash ./scripts/stop.sh

检查状态：

cd /engn/mcp/mcp_ansible
bash ./scripts/status.sh

5.7动作确认顺序

1. list_registered_playbooks
2. get_playbook_schema
3. list_registered_inventories
4. list_inventory_hosts （查看实际受控服务器列表）
5. 查询式诊断playbook run_playbook_apply
6. 变更型playbook run_playbook_check 后必要时 run_playbook_apply

6.MCP注册示例

[mcp_servers.ansible_http]
transport = "streamable_http"
url = "http://<ANSIBLE_SERVER_IP>:5000/mcp"

7.提供工具

8.运营者查询-Playbook映射

8.1推荐运行模式

• 查询型playbook command/shell 有很多基础任务，可以在Ansible check模式下跳过。
• 因此，下面的playbook 只读但是，为了实际查询 run_playbook_apply 建议使用。
  • ping_all, gather_facts_only
  • file_list_files, file_tail_file, file_grep_pattern, file_recent_changes
  • process_top_cpu, process_top_memory, process_threads_cpu, process_runtime_detail
  • service_status_detail, journal_service_errors, journal_recent_errors, kernel_recent_messages
  • directory_usage_snapshot, disk_io_snapshot
  • socket_connection_snapshot, port_listener_detail, connection_top_remote_ips, network_interface_detail
• 更改帐户/包/服务状态的变更playbook run_playbook_check先用检查 run_playbook_apply使用。

9.输入/输出规则

输入

• 执行 playbook_id, inventory_id 标准
• extra_vars是JSON object
• extra_vars是playbook inputs 基于模式的运行时验证（必需值/类型/enum）
• 策略文件的 path支持替换环境变量

输出

• run_id
• status
• rc
• host_summary
• failures
• artifact_dir
• stdout （默认：tail N行）
• stdout_line_count
• stdout_truncated

10.主要环境变量

11.运营建议

• policy/*.yaml只修改管理员
• apply前检查结果
• 最小化log/runs目录权限
• 使用Vault/外部Secret Manager获取机密信息

12.后台运行（Linux）

nohup 提供基于后台执行脚本。

bash ./scripts/start.sh

主要环境变量：

• APP_DIR （默认：基于脚本的项目根）
• PYTHON_BIN （默认： $APP_DIR/.venv/bin/python)
• LOG_DIR （默认： /var/log/ansible-mcp)
• PID_FILE （默认： $APP_DIR/ansible-mcp.pid)

停止：

bash ./scripts/stop.sh

检查状态：

bash ./scripts/status.sh

13.解决部署问题

12.1阻止执行PowerShell脚本

症状：

• running scripts is disabled on this system

解决方案：

powershell -ExecutionPolicy Bypass -File .\scripts\build_wheelhouse.ps1

12.2在Windows上强制下载Linux wheel pywin32 错误

症状：

• No matching distribution found for pywin32>=310; sys_platform == "win32"

原因：

• 同时评估Windows条件依赖性并与Linux目标wheel下载冲突

解决方案：

• 在WSL/Linux上创建wheelhouse而不是直接创建Windows

12.3在WSL python3.11: command not found

症状：

• ./scripts/build_wheelhouse.sh: line 15: python3.11: command not found

解决方案：

PYTHON_EXE=python bash ./scripts/build_wheelhouse.sh

包括Mansible-core：

PYTHON_EXE=python REQUIREMENTS=requirements-offline-with-ansible214.txt bash ./scripts/build_wheelhouse.sh

12.4脱机安装时 PyYAML>=6.0.2 未探测到

症状：

• No matching distribution found for PyYAML>=6.0.2

原因：

• wheelhouse ABI不匹配（例如： cp312 在Python3.11服务器上安装wheel）

确认：

ls wheelhouse | grep -i pyyaml

• 在文件名中 cp311 需要包括

解决方案：

• cp311 根据wheelhouse再生后重新复制

12.5服务器Python多版本问题

示例：

• python3 --version ->3.9.x
• python --version ->3.11.x

解决方案：

PYTHON_EXE=python REQUIREMENTS=requirements-offline-with-ansible214.txt bash ./scripts/install_offline.sh

14.最近执行情况摘要

• 将工具模块重构为 catalog_tools 和 run_tools 为了可维护性。
• 采用两步目录流程：摘要(list_registered_playbooks)然后是模式详细信息(get_playbook_schema).
• 添加了库存主机发现工具： list_inventory_hosts(inventory_id).
• 添加运行时 extra_vars 验证（必需/类型/枚举/未知键）。
• 使用结构化审计事件（JSON行）改进日志记录。
• 扩展的 .env-基于路径/配置注入和优先级项目根 .env 加载。
• 在运行响应中包含stdout： stdout, stdout_line_count, stdout_truncated.
• 添加 ANSIBLE_MCP_STDOUT_MAX_LINES 以控制响应stdout音量。
• 添加了运行工件保留清理（基于计数）。
• 标准化服务脚本 start.sh, stop.sh, status.sh.

15.整理日志文件

日志文件路径创建主体内容 | --- | --- | --- | | ${ANSIBLE_MCP_LOG_FILE} 或 ${ANSIBLE_MCP_LOG_DIR}/app.log | application/logging_config.py (mcp-ansible）|应用程序常规日志（错误/异常/生产日志）| | ${ANSIBLE_MCP_AUDIT_LOG_FILE} 或 ${ANSIBLE_MCP_LOG_DIR}/audit.log | api/tools/context.py的 audit_log() | Tool请求/结果/错误审计事件（JSON line）| | ${LOG_DIR}/server.out.log, ${LOG_DIR}/server.err.log （默认 /var/log/ansible-mcp) | scripts/start.sh (nohup 重定向）|流程标准输出/标准错误（Uvicorn动态消息，运行时stderr）|

执行交付项（artifact）：

路径内容 | --- | --- | | ${ANSIBLE_MCP_RUNS_DIR}/{run_id}/... （默认 /var/lib/ansible-mcp/runs) | stdout, job_events, command, status 等ansible-runner运行详细结果