内容
# Ansible 知识引擎 MCP 服务器
Ansible 知识引擎，用于 AI 代理 — 发现集合，了解模块，并通过 MCP 生成可重用的技能。
社区概念验证，使用规范驱动的 AI 辅助开发构建。
```
┌──────────────────────────────────────────────────────────────────────┐
│ >_ ansible-know-mcp [x] │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ > 我需要使用 Ansible 创建一个 AWS EC2 实例 │
│ │
│ 让我找到合适的集合和模块。 │
│ │
│ * search_collections("aws ec2") │
│ amazon.aws 12.3M downloads │
│ │
│ * get_module_doc("amazon.aws.ec2_instance") │
│ 名称，image_id，instance_type，状态，key_name，标签... │
│ │
│ → generate_skill("amazon.aws.ec2_instance") │
│ 已加载技能：ec2_instance (12 参数，3 示例) │
│ │
│ 我已经拥有我需要的一切。实例类型，AMI 和名称？ │
│ │
├──────────────────────────────────────────────────────────────────────┤
│ > t3.micro, Fedora Linux 44, web-server █ │
└──────────────────────────────────────────────────────────────────────┘
发现 ──→ 学习 ──→ 技能 ──→ 构建
```
## 它能做什么
Ansible 知识引擎是用于 Ansible AI 代理的学习层：
- **Galaxy 集合发现** — 按关键词搜索 2000+ 集合，按下载次数排名
- **多服务器 Galaxy 支持** — 并行查询公共 Galaxy、私有 Automation Hub 和 AAP Gateway
- **模块、角色和插件文档** — 结构化参数规格、示例和元数据，带有 Galaxy 备用方案
- **文档搜索** — 从 Ansible 的 AI 友好文档中查找概念指南，获取完整的 Markdown 页面
- **集合管理** — 自动安装集合并获取集合级概览
- **技能生成** — 创建可用的技能包，教导代理如何使用特定的模块、角色和插件
- **资源和提示** — 浏览技能、文档来源和 Galaxy 服务器；用于剧本审查、模块解释和角色生成的预建模板
与 [Ansible Devtools MCP](https://github.com/ansible/ansible-dev-tools) （创建 + 测试）和 [AAP MCP](https://github.com/ansible/aap-mcp-server) （部署）一起，这使得完整的自主循环成为可能：**学习 -> 创建 -> 测试 -> 部署**。
```
代理的 MCP 服务器：
+----------------------------+ +--------------------------+ +--------------+
| Ansible 知识引擎 | | Ansible Devtools | | AAP MCP |
| （此项目） | | | | |
| | | 创建 | | |
| search_collections | | ansible_create_* | | controller.* |
| search_modules | | build_ee | | eda.* |
| search_plugins | | setup_environment | | gateway.* |
| get_module_doc | | environment_info | | galaxy.* |
| get_plugin_doc | | | | |
| get_role_doc | | 测试 | | |
| get_collection_docs | | ansible_lint | | |
| get_collection_manifest | | ansible_navigator | | |
| search_docs | | | | |
| fetch_doc | | 参考 | | |
| ensure_collection | | zen_of_ansible | | |
| generate_skill | | | | |
| generate_role_skill | | | | |
| generate_plugin_skill | | | | |
| generate_collection_skills | | | | |
| list_skills / get_skill | | | | |
| clear_cache | | | | |
| | | | | |
| 学习 | | 创建 + 测试 | | 部署 |
+----------------------------+ +--------------------------+ +--------------+
```
## 安装
使用 `uvx`（推荐）：
```bash
uvx ansible-know-mcp
```
使用 `pip`:
```bash
pip install ansible-know-mcp
```
**要求：** `ansible-core` 必须在同一个 Python 环境中安装（提供 `ansible-doc`）。
## 用法
### Claude 代码
```bash
# 项目范围
claude mcp add ansible-know -- uvx ansible-know-mcp
# 所有项目都可用
claude mcp add --scope user ansible-know -- uvx ansible-know-mcp
```
### VS Code / Cursor
将以下内容添加到工作区中的 `.vscode/mcp.json`:
```json
{
"servers": {
"ansible-know": {
"command": "uvx",
"args": ["ansible-know-mcp"],
"type": "stdio"
}
}
}
```
### 任意 MCP 客户端
服务器默认通过 stdio 通信：
```bash
uvx ansible-know-mcp
```
### HTTP 传输
作为共享/远程访问的独立 HTTP 服务器运行：
```bash
# 默认端口的 HTTP（8080）
ansible-know-mcp --transport http
# 自定义主机和端口
ansible-know-mcp --transport http --host 10.0.0.1 --port 9090
# 通过环境变量（适用于容器）
export ANSIBLE_KNOW_TRANSPORT=http
export ANSIBLE_KNOW_PORT=8080
ansible-know-mcp
```
从任何 MCP 客户端使用可流式的 HTTP URL 连接：
`http://<host>:8080/mcp`
> **安全：** HTTP 模式没有内置身份验证。部署在身份验证/授权的反向代理后面，或仅在受信任的网络中使用。
### Docker
从源代码构建并运行：
```bash
docker build -t ansible-know-mcp .
docker run -p 7860:7860 ansible-know-mcp
```
从任何 MCP 客户端使用可流式的 HTTP URL 连接：
`http://localhost:7860/mcp`
### 远程 MCP（Hugging Face Spaces）
作为远程 MCP 服务器，提供公共实例：
**Claude 代码：**
```bash
claude mcp add ansible-know --transport http https://know.ansible.ar/mcp
```
**VS Code / Cursor** （`.vscode/mcp.json`）：
```json
{
"servers": {
"ansible-know": {
"type": "http",
"url": "https://know.ansible.ar/mcp"
}
}
}
```
### 完整堆栈
```json
{
"mcpServers": {
"ansible-know": { "command": "uvx", "args": ["ansible-know-mcp"] },
"ansible-devtools": { "command": "ade", "args": ["mcp"] },
"aap": { "command": "aap-mcp-server" }
}
}
```
## 工具
### 发现
| 工具 | 描述 |
|------|-------------|
| `search_collections(query, tags?)` | 按关键词搜索 Ansible Galaxy 中的集合，按下载次数排名 |
| `search_modules(keyword, namespace?)` | 按关键词查找模块，支持名称或描述（最多 50 个匹配） |
| `search_plugins(keyword, namespace?, plugin_type?)` | 按关键词查找插件（查找、过滤、库存、回调等） |
| `get_module_doc(module_name)` | 完整的结构化文档：参数、示例、API 检测。如果本地未安装，则从 Galaxy 备用 |
| `get_plugin_doc(plugin_name, plugin_type)` | 完整的结构化插件文档，带有 Galaxy 备用 |
| `get_role_doc(role_name)` | 角色文档，支持三级解析：本地 ansible-doc、Galaxy README 或优雅降级 |
| `get_collection_docs(collection_namespace, version?)` | 从 Galaxy 获取一个集合的所有模块文档，单次调用 |
| `get_collection_manifest(collection_namespace)` | 集合级清单，包含每个模块和每个角色的摘要 |
| `search_docs(query, source?, topic?, audience?, core_only?)` | 搜索文档清单中的概念指南（最多 20 个匹配） |
| `fetch_doc(url, max_tokens?)` | 获取 docs.ansible.com 页面作为干净的 Markdown |
### 集合管理
| 工具 | 描述 |
|------|-------------|
| `ensure_collection(collection_namespace, version?)` | 将集合安装到此会话的临时目录中 |
### 技能
| 工具 | 描述 |
|------|-------------|
| `list_skills()` | 列出所有生成的技能 |
| `get_skill(skill_name)` | 读取技能的 SKILL.md 内容 |
| `generate_skill(module_name, install_to?)` | 为一个模块生成技能包 |
| `generate_role_skill(role_name, install_to?)` | 为一个角色生成技能包 |
| `generate_plugin_skill(plugin_name, plugin_type, install_to?)` | 为一个插件生成技能包 |
| `generate_collection_skills(collection_namespace, install_to?)` | 为整个集合批量生成技能 |
### 维护
| 工具 | 描述 |
|------|-------------|
| `clear_cache(scope?)` | 清除 Galaxy 和/或文档清单缓存 |
## 资源
| URI | 描述 |
|-----|-------------|
| `skills://list` | 列出所有生成的技能包 |
| `skills://{skill_name}` | 通过 FQCN 读取技能的 SKILL.md 内容 |
| `galaxy://installed` | 列出此会话中安装的集合 |
| `galaxy://servers` | 列出配置的 Galaxy 服务器（名称、URL、身份验证类型 - 永远不会是凭证） |
| `server://version` | 安装和最新版本信息，带有升级状态 |
| `docs://sources` | 列出配置的文档清单来源 |
## 提示
| 提示 | 描述 |
|--------|-------------|
| `review_playbook(playbook_yaml)` | 审查剧本以对抗模块文档和最佳实践 |
| `explain_module(module_name)` | 详细的模块解释，包含使用示例 |
| `explain_plugin(plugin_name, plugin_type)` | 详细的插件解释，包含使用示例 |
| `generate_role(role_purpose, modules)` | 使用指定的模块生成角色骨架 |
| `find_collection(platform_or_use_case)` | 通过搜索、安装和探索工作流进行指导 |
## 多服务器 Galaxy 支持
Ansible 知识引擎从 `ansible.cfg` 读取 `[galaxy_server.*]` 部分（按标准顺序解析：`ANSIBLE_CONFIG` 环境变量、`./ansible.cfg`、`~/.ansible.cfg`、`/etc/ansible/ansible.cfg`）：
```ini
# ansible.cfg
[galaxy_server.automation_hub]
url = https://hub.example.com/api/galaxy/
token = my-token
[galaxy_server.public_galaxy]
url = https://galaxy.ansible.com/api/
```
- 令牌身份验证、基本身份验证和每个服务器的 TLS 验证
- `search_collections` 并行查询所有配置的服务器，合并结果并提供来源归属
- `get_module_doc` / `get_role_doc` Galaxy 备用按优先级顺序尝试服务器
- 公共 Galaxy 作为最终备用；选择退出 `ANSIBLE_KNOW_NO_PUBLIC_GALAXY=1`
- 每个服务器的环境变量覆盖：`ANSIBLE_GALAXY_SERVER_{NAME}_{KEY}`（与 ansible-core 行为匹配）
- 通过 `galaxy://servers` 资源查看配置的服务器
## 配置
| 环境变量 | 描述 | 默认值 |
|---------------------|-------------|---------|
| `ANSIBLE_KNOW_SKILLS_DIR` | 生成技能的位置 | `./skills/` |
| `ANSIBLE_KNOW_DOC_SOURCES` | 文档清单来源的 JSON 字典 | 内置 ansible-core 来源 |
| `ANSIBLE_KNOW_GALAXY_URL` | Galaxy API 基本 URL | `https://galaxy.ansible.com` |
| `ANSIBLE_KNOW_SKIP_UPDATE_CHECK` | 设置为 `1` 以禁用启动时的 PyPI 版本检查 | *(未设置)* |
| `ANSIBLE_KNOW_NO_PUBLIC_GALAXY` | 设置为 `1` 以禁止自动追加公共 Galaxy | *(未设置)* |
## 升级
| 方法 | 命令 |
|--------|---------|
| `uvx` | `uvx --upgrade ansible-know-mcp` |
| `pip` | `pip install --upgrade ansible-know-mcp` |
| Claude 代码 | `uvx --upgrade ansible-know-mcp` 然后重启 Claude 代码 |
| VS Code / Cursor | `uvx --upgrade ansible-know-mcp` 然后重新加载窗口 |
| 本地开发 | `git pull && uv sync` |
> **注意：** `uvx` 缓存已安装的版本，不会自动升级到新版本。
> 要始终运行最新版本（以较慢的启动时间为代价）：
> `claude mcp add ansible-know -- uvx --upgrade ansible-know-mcp`
## 部署
### Hugging Face Spaces
在 [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces) 上部署为远程 MCP 服务器：
1. 使用 **SDK: Docker** 创建一个新的 Space
2. Space 的 `README.md` 必须包含 YAML 前置信息：
```yaml
---
title: Ansible 知识引擎 MCP
emoji: "\U0001F4DA"
sdk: docker
app_port: 7860
---
```
3. 推送此仓库（或将其设置为 Space 的链接仓库）
4. 包含的 `Dockerfile` 会自动构建并启动服务器
> **注意：** 免费层级的 Space 在不活动后会休眠。MCP 客户端在 Space 唤醒之前（~30-60s 冷启动）将看到连接错误。使用付费 Space 或保持活动 ping 进行生产使用。
**自定义域名**（可选）：
1. 在 Space 设置中，转到 **自定义域名**
2. 添加您的域名（例如 `know.ansible.ar`）
3. 创建一个指向 `<owner>-<space-name>.hf.space` 的 CNAME 记录
4. HF 自动提供 TLS 证书
**环境变量**（在 Space 设置中设置）：
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `ANSIBLE_KNOW_SKILLS_DIR` | 否 | 默认值为 `./skills/`（容器中为临时文件） |
| `ANSIBLE_KNOW_NO_PUBLIC_GALAXY` | 否 | 设置为 `1` 以禁用公共 Galaxy 备用 |
### 通用 Docker
`Dockerfile` 适用于任何容器平台（Fly.io、Railway、Cloud Run 等）：
```bash
docker build -t ansible-know-mcp .
docker run -p 8080:7860 ansible-know-mcp
```
使用环境变量覆盖默认值：
```bash
docker run -p 9090:9090 \
-e ANSIBLE_KNOW_PORT=9090 \
ansible-know-mcp
```
## 开发
```bash
git clone https://github.com/leogallego/ansible-know-mcp.git
cd ansible-know-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest
```
## 致谢
本项目中的技能生成方法启发自 [AnsibleClaw](https://github.com/micytao/AnsibleClaw) by Michael Tao — 一个将 Ansible 模块转换为可移植 AI 代理技能包的技能生成框架。
## 许可证
GPL-3.0-or-later
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器