Ansible Adv MCP Server

Ansible MCP服务器

一个全面的模型上下文协议（MCP）服务器，使AI助手能够使用Ansible管理基础设施。此服务器提供Ansible存储库的智能解析、执行和管理，支持企业功能和未来的AWX/AAP集成。

特性

🔧 基础设施管理

• Ansible存储库解析：深入了解ansible.cfg、库存、group_vars、host_vars，角色和集合
• 多存储库支持：同时管理多个Ansible存储库
• 剧本管理：使用灵活的YAML输入创建、验证和执行Ansible剧本
• 硬件发现：全面的硬件扫描和库存生成
• 安全审计：安全扫描、端口扫描、密码策略审核

🤖 AI优化设计

• 灵活输入：接受YAML字符串、对象和结构化数据
• 全面的错误处理：详细的错误报告和恢复机制
• 上下文持久性：维护操作之间的会话状态和上下文
• 动态工具加载：用于添加新工具和服务的可扩展架构

🚀 与跨平台支持

• 容器化部署：基于Docker的部署，实现一致性和可扩展性
• Linux服务器部署：服务器基础架构的主要目标
• 远程服务器管理：安全的远程服务器管理功能

🛠️ MCP工具

Git管理工具

• clone-repository -将远程Ansible存储库克隆到本地项目
• pull-repository -从已配置的远程存储库中提取更新
• remove-repository -从项目中删除已配置的存储库

Ansible核心工具

• create-playbook-flexible -使用YAML字符串或对象创建剧本
• ansible-playbook -使用--检查和直接执行模式执行剧本
• ansible-task -执行临时可执行任务
• ansible-role -执行现有角色、创建新角色、管理依赖关系
• ansible-collection -安装和管理Ansible集合
• validate-playbook -验证剧本语法和最佳实践
• create-role-structure -生成标准Ansible角色目录

基础设施工具

• hardware-scan -全面的硬件发现和分析
• storage-analysis -存储设备发现和运行状况分析
• network-interfaces -网络适配器发现和配置
• discover-proxmox -发现Proxmox虚拟机和容器
• generate-inventory -从发现数据创建可靠的库存

安全工具

• security-quick-scan -快速安全评估
• security-scan-ports -网络端口扫描和分析
• security-check-passwords -密码策略审核和执行
• security-audit-accounts -用户帐户审核和管理
• security-check-ssh -SSH配置安全审计

服务管理工具

• browse-services -浏览可用服务目录
• deploy-service -从目录部署服务
• list-environments -列出可用的部署环境
• deploy-to-environment -环保部署

快速开始

先决条件

• Node.js 18+
• Docker和Docker Compose（用于容器化部署）
• Ansible Core 2.15+（用于本地开发）
• Git 2.30+

安装

使用Docker（推荐）

1. 克隆存储库：

git clone 
cd ansible-mcp-server

1. 复制环境变量：

cp .env.example .env
# Edit .env with your configuration

1. 从Docker Compose开始：

# Production deployment
docker-compose up -d

# Development with hot reload
docker-compose --profile dev up -d ansible-mcp-dev

# With PostgreSQL
docker-compose --profile postgres up -d

地方发展

1. 安装依赖项：

npm install

1. 复制环境变量：

cp .env.example .env

1. 构建和启动：

npm run build
npm start

# Or for development with hot reload
npm run dev

配置

服务器使用环境变量进行配置。看 .env.example 所有可用选项。

关键配置选项

• DB_TYPE：数据库类型(sqlite 或 postgresql)
• DB_CONNECTION：数据库连接字符串
• ANSIBLE_CONFIG：ansible.cfg文件的路径
• ANSIBLE_INVENTORY：默认库存文件或目录
• REPOSITORIES_PATH：克隆存储库的目录
• LOG_LEVEL：日志记录级别(error, warn, info, debug)

用法

MCP客户端集成

服务器实现了模型上下文协议，可以与任何兼容MCP的客户端一起使用：

{
  "mcpServers": {
    "ansible-mcp-server": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "LOG_LEVEL": "info",
        "DB_TYPE": "sqlite",
        "DB_CONNECTION": "./data/ansible-mcp.db"
      }
    }
  }
}

工具使用示例

克隆Ansible存储库

{
  "name": "clone-repository",
  "arguments": {
    "url": "https://github.com/example/ansible-repo.git",
    "name": "my-infrastructure",
    "branch": "main",
    "credentials": {
      "type": "token",
      "token": "ghp_xxxxxxxxxxxx"
    }
  }
}

创建和执行剧本

{
  "name": "create-playbook-flexible",
  "arguments": {
    "content": "---\n- name: Install nginx\n  hosts: webservers\n  tasks:\n    - name: Install nginx package\n      apt:\n        name: nginx\n        state: present",
    "path": "./playbooks/install-nginx.yml",
    "validate": true
  }
}

{
  "name": "ansible-playbook",
  "arguments": {
    "playbookPath": "./playbooks/install-nginx.yml",
    "inventory": "./inventory/production",
    "options": {
      "checkMode": true,
      "diff": true,
      "limit": "webservers"
    }
  }
}

执行硬件发现

{
  "name": "hardware-scan",
  "arguments": {
    "hosts": "all",
    "inventory": "./inventory/production",
    "includeStorage": true,
    "includeNetwork": true
  }
}

建筑

核心组件

1. MCP服务器核心：基于TypeScript的MCP服务器实现
2. Ansible发动机：基于Python的Ansible执行引擎
3. 存储库管理器：Git和Ansible存储库管理
4. Discovery发动机：硬件和基础设施发现
5. 安全扫描仪：安全审计和扫描工具
6. 服务目录：模板化服务部署系统

技术栈

• 主要语言：TypeScript（MCP服务器），Python（Ansible引擎）
• 数据库：SQLite（默认），PostgreSQL（企业）
• 容器化：具有多阶段构建的Docker
• 日志记录：Winston，结构化日志
• 验证：Joi用于模式验证

发展

项目结构

src/
├── core/           # Core MCP server and tool registry
├── services/       # Business logic services
├── tools/          # MCP tool implementations
├── types/          # TypeScript type definitions
├── utils/          # Utility functions
└── test/           # Test files

建筑

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

Docker开发

# Build Docker image
npm run docker:build

# Run in container
npm run docker:run

# Development with hot reload
docker-compose --profile dev up

安全

安全功能

• 安全的凭证存储和管理
• 基于角色的访问控制（RBAC）
• 所有操作的审核日志记录
• 网络安全最佳实践
• 集装箱安全扫描

安全最佳实践

1. 使用SSH密钥而不是密码进行Git身份验证
2. 在生产中启用审核日志记录
3. 以非root用户身份运行容器
4. 对敏感数据使用机密管理
5. 定期更新依赖关系和基础映像

演出

性能要求

• 基本操作的响应时间低于秒
• 同时执行多个剧本
• 可扩展到1000多个受管节点
• 容器化环境中的高效内存使用

优化提示

1. 使用SQLite进行单实例部署
2. 使用PostgreSQL进行多实例部署
3. 配置适当 ANSIBLE_FORKS 为了您的环境
4. 将库存缓存用于大型基础架构
5. 监控资源使用情况并调整容器限制

故障排除

常见问题

服务器无法启动

• 检查中的环境变量 .env 文件
• 确保数据库可访问
• 验证Node.js版本（需要18+）
• 检查日志文件以获取详细的错误消息

可解析命令失败

• 验证Ansible是否已安装且可访问
• 检查库存文件权限
• 验证与目标主机的SSH连接
• 查看Ansible配置(ansible.cfg)

存储库克隆失败

• 验证Git凭据是否正确
• 检查网络连接
• 确保有足够的磁盘空间
• 查看存储库URL格式

调试模式

启用调试日志记录以进行详细的故障排除：

export LOG_LEVEL=debug
npm start

或者在Docker中：

environment:
  - LOG_LEVEL=debug

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 运行linting和测试
6. 提交拉取请求

开发指南

• 遵循TypeScript的最佳实践
• 为公共API添加JSDoc注释
• 为新功能编写单元测试
• 更新面向用户的更改文档
• 使用常规提交消息

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

未来的增强功能

第二阶段：企业特性

• AWX/Ansible自动化平台集成
• 企业身份验证（LDAP、SAML）
• 高级工作流编排
• 自定义仪表板和报告

第三阶段：高级智能

• AI驱动的剧本优化
• 预测性基础设施监控
• 自动化补救工作流程
• 成本优化建议

支持

对于问题和疑问：

1. 检查 故障排除部分
2. 搜索现有
3. 创建包含详细信息的新问题
4. 加入我们 不和谐社区

致谢

• 安塞波 强大的自动化平台
• 模型上下文协议 对于MCP规范
• TypeScript 用于类型安全开发
• 码头工人 用于集装箱化支持