convez.ai
MCP ServerDevOps & InfraestruturaAvançado
leogallego

Ansible Know MCP Server

leogallego/ansible-know-mcp

Descoberta e documentação de módulos Ansible para agentes de IA via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que fornece descoberta de módulos Ansible, busca de documentação e geração de skills para agentes de IA. Integra-se com Ansible Galaxy e Automation Hub para recuperar documentação estruturada e criar pacotes de habilidades prontos para uso.

Instalação

$npx convez-ai leogallego/ansible-know-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 3 dias
Versão
v0.11.0
Issues abertas
33
Contribuidores
2

Casos de uso

  • Agentes de IA consultarem documentação de módulos Ansible em tempo real
  • Gerar skills e templates de playbooks automaticamente
  • Pesquisar coleções no Galaxy e fazer bootstrap de dependências
  • Integrar com pipelines de automação (learn -> build -> deploy)

Veredito

Ferramenta especializada e bem arquitetada para agentes de IA operarem Ansible autonomamente. Excelente para equipes que já usam Ansible e querem automação baseada em IA com contexto técnico profundo.

README

A tradução para o português deste README ainda está na fila.

Ansible Know MCP Server

Module discovery, documentation search, and skill generation for AI agents via the Model Context Protocol.

What It Does

Ansible Know is the foundational "learn" layer for AI agents working with Ansible. It provides:

  • Multi-server Galaxy support — query public Galaxy, private Automation Hub, and AAP Gateway in parallel, configured via ansible.cfg with per-server authentication
  • Galaxy collection discovery — search 2000+ collections on Ansible Galaxy by keyword, ranked by download count
  • Module discovery — search and explore Ansible modules across installed collections
  • Module documentation — get structured parameter specs, examples, and metadata (falls back to Galaxy if not installed locally)
  • Documentation search — find conceptual guides from Ansible's AI-friendly docs
  • Skill generation — create ready-to-use skill packages that teach agents how to use specific modules
  • Collection bootstrapping — auto-install collections from Galaxy for the current session
  • Collection manifests — get collection-level overviews with per-module summaries
  • Resources — browse skills and doc sources as MCP resources
  • Prompts — pre-built templates for playbook review, module explanation, and role generation

Together with Ansible Devtools MCP (build) and AAP MCP (deploy), this enables the full autonomous cycle: learn -> build -> deploy.

 Agent's MCP servers:

 +-----------------------+  +-------------------+  +---------------+
 | Ansible Know          |  | Ansible Devtools  |  |   AAP MCP     |
 | (this project)        |  |                   |  |               |
 |                       |  |                   |  |               |
 | search_collections    |  | ansible_lint      |  | controller.*  |
 | search_modules        |  | ansible_navigator |  | eda.*         |
 | get_module_doc        |  | ansible_create_*  |  | gateway.*     |
 | get_role_doc          |  | build_ee          |  | galaxy.*      |
 | get_collection_       |  | zen_of_ansible    |  |               |
 |   manifest            |  | setup_environment |  |               |
 | search_docs           |  | environment_info  |  |               |
 | ensure_collection     |  |                   |  |               |
 | generate_skill        |  |                   |  |               |
 | generate_role_skill   |  |                   |  |               |
 | generate_collection   |  |                   |  |               |
 | list_skills           |  |                   |  |               |
 | get_skill             |  |                   |  |               |
 |                       |  |                   |  |               |
 | LEARN                 |  | BUILD             |  | DEPLOY        |
 +-----------------------+  +-------------------+  +---------------+

Installation

Using uvx (recommended):

uvx ansible-know-mcp

Using pip:

pip install ansible-know-mcp

Runtime requirement: ansible-core must be installed in the same environment (for ansible-doc).

Usage

With Claude Code

claude mcp add ansible-know -- uvx ansible-know-mcp

To make it available in all projects:

claude mcp add --scope user ansible-know -- uvx ansible-know-mcp

With VS Code / Cursor

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "ansible-know": {
      "command": "uvx",
      "args": ["ansible-know-mcp"],
      "type": "stdio"
    }
  }
}

With any MCP client

The server runs over stdio by default:

uvx ansible-know-mcp

Full stack configuration

{
  "mcpServers": {
    "ansible-know":     { "command": "uvx", "args": ["ansible-know-mcp"] },
    "ansible-devtools": { "command": "ade", "args": ["mcp"] },
    "aap":              { "command": "aap-mcp-server" }
  }
}

Tools

Discovery (read-only)

ToolDescription
search_collections(query, tags?)Search Ansible Galaxy for collections by keyword. Returns results ranked by download count.
search_modules(keyword, namespace?)Find modules by keyword in name or description. Returns up to 50 matches.
get_module_doc(module_name)Get full structured docs: params, examples, API detection. Falls back to Galaxy if not installed locally.
get_role_doc(role_name)Get role documentation with three-tier resolution: local ansible-doc, Galaxy README, or graceful degradation.
search_docs(query, source?, topic?, audience?, core_only?)Search documentation manifests for conceptual guides. Returns up to 20 matches.
get_collection_manifest(collection_namespace)Get collection-level manifest with per-module and per-role summaries.

Collection management

ToolDescription
ensure_collection(collection_namespace, version?)Install a collection to a temporary directory for this session.

Skill management

ToolDescription
list_skills()List all generated skills (read-only).
get_skill(skill_name)Read a skill's SKILL.md content (read-only).
generate_skill(module_name, install_to?)Generate a skill package for one module. Returns SKILL.md inline.
generate_role_skill(role_name, install_to?)Generate a skill package for one role. Returns SKILL.md inline.
generate_collection_skills(collection_namespace, install_to?)Batch generate skills for an entire collection.

Resources

URIDescription
skills://listList all generated skill packages
skills://{skill_name}Read a skill's SKILL.md content by FQCN
galaxy://installedList collections installed in this session
server://versionInstalled and latest version info with upgrade status
galaxy://serversList configured Galaxy servers (names, URLs, auth types — never credentials)
docs://sourcesList configured documentation manifest sources

Prompts

PromptDescription
review_playbook(playbook_yaml)Review a playbook against module docs and best practices
explain_module(module_name)Get a detailed module explanation with usage examples
generate_role(role_purpose, modules)Generate a role skeleton using specified modules
find_collection(platform_or_use_case)Guide through search, install, and explore workflow

Upgrading

The server exposes its version via the MCP protocol. To upgrade to the latest release:

Installation methodUpgrade command
uvxuvx --upgrade ansible-know-mcp
pippip install --upgrade ansible-know-mcp
Claude Code (claude mcp add)uvx --upgrade ansible-know-mcp then restart Claude Code
VS Code / Cursoruvx --upgrade ansible-know-mcp then reload window
Local devgit pull && uv sync

Note: uvx caches the installed version. It does not auto-upgrade on new releases. To always run the latest version at the cost of slower startup, register with: claude mcp add ansible-know -- uvx --upgrade ansible-know-mcp

Development

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

Multi-server Galaxy Support

Ansible Know reads [galaxy_server.*] sections from ansible.cfg (using the standard 4-step resolution: ANSIBLE_CONFIG env → ./ansible.cfg → ~/.ansible.cfg → /etc/ansible/ansible.cfg) to support multiple Galaxy-compatible endpoints:

# 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/
  • Supports token auth, basic auth, and per-server TLS verification
  • search_collections queries all configured servers in parallel, merges results with source attribution
  • get_module_doc / get_role_doc Galaxy fallback tries servers in priority order
  • Public Galaxy is appended as a final fallback; opt out with ANSIBLE_KNOW_NO_PUBLIC_GALAXY=1
  • Per-server env var overrides: ANSIBLE_GALAXY_SERVER_{NAME}_{KEY} (matches ansible-core behavior)
  • View configured servers via the galaxy://servers resource

Configuration

Environment VariableDescriptionDefault
ANSIBLE_KNOW_SKILLS_DIRWhere to write generated skills./skills/
ANSIBLE_KNOW_DOC_SOURCESJSON dict of doc manifest sourcesBuilt-in ansible-core source
ANSIBLE_KNOW_GALAXY_URLGalaxy API base URLhttps://galaxy.ansible.com
ANSIBLE_KNOW_SKIP_UPDATE_CHECKSet to 1 to disable PyPI version check at startup(not set)
ANSIBLE_KNOW_NO_PUBLIC_GALAXYSet to 1 to suppress auto-appending public Galaxy (for air-gapped deployments)(not set)

License

GPL-3.0-or-later

Ver o original no GitHub

Bom para

Relacionados