企业级MCP服务器

Name: 企业级MCP服务器
Author: sibilleb

作者：sibilleb21 星标更新：2025-07-19

安装使用来源：spider==github.com

项目介绍

AAP企业MCP服务器

适用于Red Hat自动化和基础设施生态系统的全面模型上下文协议（MCP）服务器套件，使AI助手能够与Ansible自动化平台（AAP）、事件驱动Ansible（EDA）、ansible-lint代码质量工具以及Red Hat官方文档进行交互，并通过安全域验证。

功能

Ansible自动化平台（AAP）集成

清单管理：列出、创建、更新清单并管理主机/组
作业管理：运行作业模板，监控作业状态，检索日志
项目管理：创建和管理基于SCM的项目
模板管理：创建和管理作业模板
主机操作：添加/移除主机，管理主机变量和事实
临时命令：在清单主机上直接执行ansible命令

事件驱动Ansible（EDA）集成

激活管理：列出、创建、启用/禁用EDA激活
规则手册管理：管理和查询规则手册
决策环境管理：管理决策环境
事件流监控：监控事件流

Ansible Galaxy集成

集合搜索：按名称、命名空间或关键词搜索和发现Ansible集合
角色搜索：按关键词、作者或特定条件查找社区角色
内容详情：获取关于集合和角色的综合信息，包括版本、依赖项和安装说明
智能建议：基于用例描述的AI驱动的内容推荐
AAP集成：考虑现有AAP基础设施和清单的智能建议

Ansible Lint集成

剧本验证：实时验证Ansible剧本内容，具有可配置的质量配置文件
文件分析：对Ansible文件、角色和整个项目结构进行全面分析
最佳实践强制执行：自动检查Ansible社区标准和最佳实践
语法验证：快速语法检查以提供即时反馈
多配置文件支持：从基础到生产就绪的逐步质量改进
规则管理：列出、过滤并理解带有详细解释的ansible-lint规则

Red Hat文档集成（简化）

高效发现：使用官方Red Hat域名进行基于网络搜索的内容发现
智能内容抓取：优先处理PDF以解决Red Hat的JavaScript渲染问题
域安全：验证访问50多个官方Red Hat域名的安全文档访问
最小化MCP开销：精简的双工具方法减少API调用75%
搜索查询生成：为外部WebSearch MCP工具生成优化的搜索查询
身份验证处理：智能检测需要订阅的内容与公共内容

安装

先决条件

Python 3.11或更高版本
UV包管理器（推荐）或pip
访问Ansible自动化平台实例
有效的AAP API令牌

设置

克隆仓库：

git clone https://github.com/sibilleb/AAP-Enterprise-MCP-Server.git
cd AAP-Enterprise-MCP-Server

安装依赖项：

# 使用UV（推荐）
uv sync

# 或使用pip
pip install -e .

设置环境变量：

# 对于AAP/EDA服务器是必需的
export AAP_TOKEN="your-aap-api-token"
export AAP_URL="https://your-aap-server.com/api/controller/v2"
export EDA_TOKEN="your-eda-api-token"  # 可以与AAP_TOKEN相同
export EDA_URL="https://your-aap-server.com/api/eda/v1"

# 可选的Red Hat客户门户访问
export REDHAT_USERNAME="your-redhat-username"
export REDHAT_PASSWORD="your-redhat-password"

获取您的API令牌

方法1：AAP Web界面

登录您的AAP Web界面
单击右上角的用户名
选择“用户设置”或“我的个人资料”
导航到“令牌”部分
点击“添加”或“创建令牌”
将范围设置为“写入”以实现全部功能
立即复制生成的令牌（它不会再次显示）

方法2：命令行

curl -k -X POST \
  "https://your-aap-server.com/api/v2/tokens/" \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "description": "MCP Server Token",
    "application": null,
    "scope": "write"
  }'

配置

MCP客户端配置

将以下内容添加到您的MCP客户端配置中（例如，Claude Desktop，Cursor）：

{
  "mcpServers": {
    "ansible": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/AAP-Enterprise-MCP-Server",
        "run",
        "ansible.py"
      ],
      "env": {
        "AAP_TOKEN": "your-aap-api-token",
        "AAP_URL": "https://your-aap-server.com/api/controller/v2"
      }
    },
    "eda": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/AAP-Enterprise-MCP-Server",
        "run",
        "eda.py"
      ],
      "env": {
        "EDA_TOKEN": "your-eda-api-token",
        "EDA_URL": "https://your-aap-server.com/api/eda/v1"
      }
    },
    "ansible-lint": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/AAP-Enterprise-MCP-Server",
        "run",
        "ansible-lint.py"
      ]
    },
    "redhat-docs": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/AAP-Enterprise-MCP-Server",
        "run",
        "redhat_docs.py"
      ],
      "env": {
        "REDHAT_USERNAME": "your-username",
        "REDHAT_PASSWORD": "your-password"
      }
    }
  }
}

SSL/TLS配置

对于实验室环境中自签名证书，服务器会自动：

禁用SSL警告
跳过证书验证
平稳处理不安全连接

对于生产环境，请确保在您的AAP实例上正确配置了SSL证书。

服务器架构

此项目实现了四服务器MCP架构，以覆盖全面的Red Hat生态系统：

服务器	文件	目的	关键特性
Ansible自动化平台	`ansible.py`	AAP集成与Galaxy搜索	作业管理，清单控制，Galaxy发现（855行）
事件驱动Ansible	`eda.py`	EDA集成	激活管理，规则手册处理（96行）
Ansible Lint	`ansible-lint.py`	代码质量和最佳实践	进阶质量配置文件，项目分析（502行）
Red Hat文档	`redhat_docs.py`	官方Red Hat文档访问	域验证，混合搜索，PDF访问

组合能力

完整的自动化生命周期：从文档发现到实施，包括质量保证
安全性：域验证访问确保仅使用官方Red Hat来源
智能：AI驱动的推荐和专门的电信/边缘指导
可扩展性：独立服务器允许专注于功能和扩展

可用工具

Ansible自动化平台工具

工具	描述
`list_inventories`	列出所有清单
`get_inventory`	根据ID获取清单详情
`create_inventory`	创建新的清单
`list_hosts`	列出清单中的主机
`add_host_to_inventory`	将主机添加到清单
`run_job`	执行作业模板
`job_status`	检查作业执行状态
`job_logs`	检索作业执行日志
`list_job_templates`	列出可用的作业模板
`create_job_template`	创建新的作业模板
`create_project`	创建新的项目
`run_adhoc_command`	执行临时ansible命令
`list_projects`	列出所有项目
`get_project`	根据ID获取项目详情
`list_project_updates`	列出项目更新作业（SCM同步）
`get_project_update`	获取项目更新作业状态
`get_project_update_logs`	获取项目更新作业日志
`update_project`	触发项目更新（SCM同步）

Ansible Galaxy搜索工具

工具	描述
`search_galaxy_collections`	按查询、标签或命名空间搜索Ansible Galaxy集合
`search_galaxy_roles`	按关键词、名称或作者搜索Ansible Galaxy角色
`get_collection_details`	获取特定集合的详细信息
`get_role_details`	获取特定角色的详细信息
`suggest_ansible_content`	根据用例描述智能建议集合和角色

Ansible Lint工具

工具	描述
`lint_playbook`	使用可配置的配置文件和规则验证Ansible剧本内容
`lint_file`	验证磁盘上的特定Ansible文件
`lint_role`	对Ansible角色目录进行全面验证
`validate_syntax`	快速语法验证以提供即时反馈
`check_best_practices`	根据上下文感知的最佳实践检查（开发/测试/生产）
`analyze_project`	分析整个Ansible项目结构并提供全面报告
`list_rules`	列出可用的ansible-lint规则，可选地按标签过滤
`list_tags`	列出所有可用的ansible-lint规则标签
`get_ansible_lint_version`	获取已安装的ansible-lint版本信息

事件驱动Ansible工具

工具	描述
`list_activations`	列出EDA激活
`get_activation`	获取激活详情
`create_activation`	创建新的激活
`enable_activation`	启用激活
`disable_activation`	禁用激活
`restart_activation`	重启激活
`list_rulebooks`	列出可用的规则手册
`get_rulebook`	获取规则手册详情
`list_decision_environments`	列出决策环境

Red Hat文档工具

工具	描述
`read_documentation`	使用域验证和PDF优先访问Red Hat文档
`list_products`	列出所有可用的Red Hat产品和版本
`search_documentation`	按版本优先级搜索Red Hat文档
`search_documentation_enhanced`	新：结合站点地图+网络搜索发现的混合搜索
`search_with_web_guidance`	新：获取直接结果+优化的Red Hat域限制网络搜索查询
`smart_documentation_finder`	新：智能多源文档发现
`get_product_guides`	获取具有语义版本排序的产品指南（OpenShift 4.18有13个指南）
`recommend_content`	具有电信/边缘/CNF专业化的智能推荐

使用示例

运行作业模板

# 列出可用的作业模板
templates = await list_job_templates()

# 运行特定作业模板并带变量
result = await run_job(
    template_id=5,
    extra_vars={"target_env": "production", "app_version": "1.2.3"}
)

# 检查作业状态
status = await job_status(result["job"])

管理清单

# 列出所有清单
inventories = await list_inventories()

# 向清单添加新主机
await add_host_to_inventory(
    inventory_id=1,
    hostname="web-server-01.example.com",
    variables={"ansible_host": "192.168.1.100", "role": "webserver"}
)

# 在清单上执行临时命令
await run_adhoc_command(
    inventory_id=1,
    module_name="setup",
    limit="web-server-01.example.com"
)

Galaxy内容发现

# 获取特定用例的智能建议
suggestions = await suggest_ansible_content(
    use_case="我正在开发一个剧本，该剧本在AWS上使用ansible启动和关闭EC2服务器",
    check_aap_inventory=True
)

# 搜索与AWS相关的集合
collections = await search_galaxy_collections(query="aws", limit=10)

# 搜索特定于EC2的角色
roles = await search_galaxy_roles(keyword="ec2", limit=5)

# 获取特定集合的详细信息
details = await get_collection_details(namespace="amazon", name="aws")

# 获取特定角色的详细信息
role_info = await get_role_details(role_id=12345)

Ansible Lint质量保证

# 使用不同的质量配置文件验证剧本内容
playbook_content = """
---
- hosts: all
  tasks:
    - name: 安装软件包
      yum: name=nginx state=present
"""

# 开发的基本验证
basic_results = await lint_playbook(
    content=playbook_content,
    profile="basic",
    format_type="json"
)

# 生产就绪验证
production_results = await lint_playbook(
    content=playbook_content,
    profile="production",
    format_type="json"
)

# 快速语法验证
syntax_check = await validate_syntax(content=playbook_content)

# 上下文感知的最佳实践检查
best_practices = await check_best_practices(
    content=playbook_content,
    context="production"
)

# 分析整个项目结构
project_analysis = await analyze_project(
    project_path="/path/to/ansible/project",
    profile="moderate"
)

# 列出可用规则和标签
rules = await list_rules(tags="idempotency,syntax")
tags = await list_tags()

EDA激活管理

# 列出所有激活
activations = await list_activations()

# 启用特定激活
await enable_activation(activation_id=3)

# 检查激活详情
details = await get_activation(activation_id=3)

Red Hat文档访问

# 以PDF优先访问OpenShift文档
content = await read_documentation(
    "https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html/updating_clusters/index",
    format_preference="pdf"  # 确保可靠的内容提取
)

# 使用混合方法搜索电信边缘内容
guidance = await search_with_web_guidance(
    "openshift telco edge cluster upgrade", 
    product="openshift_container_platform"
)
# 返回直接结果+5个Red Hat域限制的网络搜索查询

# 获取全面的电信/边缘推荐
recommendations = await recommend_content(
    "telco edge CNF cluster upgrade", 
    role="administrator"
)
# 返回专门的边缘计算和集群更新推荐

# 获取最新的OpenShift指南（自动检测4.18，而不是3.x）
guides = await get_product_guides("openshift_container_platform", version="latest")
# 返回13个专门指南，包括更新集群、边缘计算等。

# 域验证网络搜索工作流程
guidance = await search_with_web_guidance("kubernetes edge computing")
# 使用生成的查询如："site:docs.redhat.com openshift 4.18 kubernetes edge computing"
# 然后将发现的URL反馈回来：
content = await read_documentation(discovered_url, format_preference="pdf")

开发

运行测试

# 安装开发依赖项
uv sync --group dev

# 运行测试
pytest

# 运行覆盖率测试
pytest --cov=.

代码格式化

# 格式化代码
black .

# 验证代码
ruff check .

# 类型检查
mypy .

故障排除

常见问题

SSL证书错误：服务器会自动处理自签名证书。如果遇到SSL问题，请验证您的AAP服务器配置。
认证失败：确保您的API令牌具有足够的权限（建议使用写入范围）。
连接超时：检查到您的AAP服务器的网络连接并验证URL格式。
工具未找到：在配置更改后重新启动您的MCP客户端。

调试模式

设置环境变量以启用详细日志记录：

export MCP_DEBUG=1

贡献

分叉仓库
创建功能分支
进行更改
为新功能添加测试
确保所有测试通过
提交拉取请求

许可

本项目根据MIT许可发布 - 请参阅LICENSE文件了解详细信息。

关键成就

🎯 Red Hat文档成功指标

✅ 版本检测：OpenShift 4.18正确识别为最新版本（非3.x）
✅ PDF访问：成功访问1.4MB+的PDF文件
✅ 搜索相关性：电信边缘查询返回专门文档
✅ 域安全：100% Red Hat域验证（测试了50多个域名）
✅ 网络搜索整合：结合官方来源限制的混合方法

📊 性能改进

指标	之前	现在	状态
最新版本检测	❌ 3.x版本	✅ 4.18+版本	修复
PDF访问成功率	❌ 301/404错误	✅ 200 OK响应	100%
域验证	❌ 无过滤