Metadata-Version: 2.4
Name: ansible-know-mcp
Version: 0.7.0
Summary: Ansible Knowledge MCP Server — module and role discovery, documentation, and skill generation for AI agents
Project-URL: Homepage, https://github.com/leogallego/ansible-know-mcp
Project-URL: Repository, https://github.com/leogallego/ansible-know-mcp
Project-URL: Issues, https://github.com/leogallego/ansible-know-mcp/issues
Author-email: Leonardo Gallego <leo.pypi@gallego.red>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: agent,ai,ansible,mcp,module-discovery,skills
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: fastmcp<4,>=3.2
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: typing-extensions>=4.0; python_version < '3.12'
Provides-Extra: build
Requires-Dist: defusedxml>=0.7; extra == 'build'
Requires-Dist: sphobjinv>=2.3; extra == 'build'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Ansible Know MCP Server

The Ansible knowledge engine for AI agents — discover collections, understand modules, and generate reusable skills via MCP.

A community proof of concept built with spec-driven AI-assisted development.

```
┌──────────────────────────────────────────────────────────────────────┐
│  >_  ansible-know-mcp                                          [x]  │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  > I need to create an AWS EC2 instance with Ansible                 │
│                                                                      │
│    Let me find the right collection and module.                      │
│                                                                      │
│      * search_collections("aws ec2")                                 │
│        amazon.aws                          12.3M downloads           │
│                                                                      │
│      * get_module_doc("amazon.aws.ec2_instance")                     │
│        name, image_id, instance_type, state, key_name, tags...       │
│                                                                      │
│      → generate_skill("amazon.aws.ec2_instance")                     │
│        Loaded skill: ec2_instance (12 params, 3 examples)            │
│                                                                      │
│    I have everything I need. Instance type, AMI, and name?           │
│                                                                      │
├──────────────────────────────────────────────────────────────────────┤
│  > t3.micro, Fedora Linux 44, web-server █                           │
└──────────────────────────────────────────────────────────────────────┘

              DISCOVER ──→ LEARN ──→ SKILL ──→ BUILD
```

## What It Does

Ansible Know is the **learn** layer for AI agents working with Ansible:

- **Galaxy collection discovery** — search 2000+ collections by keyword, ranked by download count
- **Multi-server Galaxy support** — query public Galaxy, private Automation Hub, and AAP Gateway in parallel
- **Module, role, and plugin documentation** — structured parameter specs, examples, and metadata with Galaxy fallback
- **Documentation search** — find conceptual guides from Ansible's AI-friendly docs, fetch full pages as Markdown
- **Collection management** — auto-install collections and get collection-level overviews
- **Skill generation** — create ready-to-use skill packages that teach agents how to use specific modules, roles, and plugins
- **Resources and prompts** — browse skills, doc sources, and Galaxy servers; pre-built templates for playbook review, module explanation, and role generation

Together with [Ansible Devtools MCP](https://github.com/ansible/ansible-dev-tools) (create + test) and [AAP MCP](https://github.com/ansible/aap-mcp-server) (deploy), this enables the full autonomous cycle: **learn -> create -> test -> deploy**.

```
 Agent's MCP servers:

 +----------------------------+  +--------------------------+  +--------------+
 | Ansible Know               |  | Ansible Devtools         |  | AAP MCP      |
 | (this project)             |  |                          |  |              |
 |                            |  | CREATE                   |  |              |
 | 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               |  | TEST                     |  |              |
 | get_collection_docs        |  | ansible_lint             |  |              |
 | get_collection_manifest    |  | ansible_navigator        |  |              |
 | search_docs                |  |                          |  |              |
 | fetch_doc                  |  | REFERENCE                |  |              |
 | ensure_collection          |  | zen_of_ansible           |  |              |
 | generate_skill             |  |                          |  |              |
 | generate_role_skill        |  |                          |  |              |
 | generate_plugin_skill      |  |                          |  |              |
 | generate_collection_skills |  |                          |  |              |
 | list_skills / get_skill    |  |                          |  |              |
 | clear_cache                |  |                          |  |              |
 |                            |  |                          |  |              |
 | LEARN                      |  | CREATE + TEST            |  | DEPLOY       |
 +----------------------------+  +--------------------------+  +--------------+
```

## Installation

Using `uvx` (recommended):

```bash
uvx ansible-know-mcp
```

Using `pip`:

```bash
pip install ansible-know-mcp
```

**Requirement:** `ansible-core` must be installed in the same Python environment (provides `ansible-doc`).

## Usage

### Claude Code

```bash
# Project-scoped
claude mcp add ansible-know -- uvx ansible-know-mcp

# Available in all projects
claude mcp add --scope user ansible-know -- uvx ansible-know-mcp
```

### VS Code / Cursor

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

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

### Any MCP client

The server communicates over stdio by default:

```bash
uvx ansible-know-mcp
```

### HTTP Transport

Run as a standalone HTTP server for shared/remote access:

```bash
# HTTP on default port (8080)
ansible-know-mcp --transport http

# Custom host and port
ansible-know-mcp --transport http --host 10.0.0.1 --port 9090

# Via environment variables (useful for containers)
export ANSIBLE_KNOW_TRANSPORT=http
export ANSIBLE_KNOW_PORT=8080
ansible-know-mcp
```

Connect from any MCP client using the streamable HTTP URL:
`http://<host>:8080/mcp`

> **Security**: HTTP mode has no built-in authentication. Deploy behind a
> reverse proxy with authentication/authorization, or use only on trusted
> networks.

### Docker

Build and run from source:

```bash
docker build -t ansible-know-mcp .
docker run -p 7860:7860 ansible-know-mcp
```

Connect from any MCP client using the streamable HTTP URL:
`http://localhost:7860/mcp`

### Remote MCP (Hugging Face Spaces)

A public instance is available as a remote MCP server:

**Claude Code:**
```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"
    }
  }
}
```

### Full stack

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

## Tools

### Discovery

| Tool | Description |
|------|-------------|
| `search_collections(query, tags?)` | Search Ansible Galaxy for collections by keyword, ranked by download count |
| `search_modules(keyword, namespace?)` | Find modules by keyword in name or description (up to 50 matches) |
| `search_plugins(keyword, namespace?, plugin_type?)` | Find plugins by keyword (lookup, filter, inventory, callback, etc.) |
| `get_module_doc(module_name)` | Full structured docs: params, examples, API detection. Falls back to Galaxy if not installed locally |
| `get_plugin_doc(plugin_name, plugin_type)` | Full structured plugin documentation with Galaxy fallback |
| `get_role_doc(role_name)` | Role documentation with three-tier resolution: local ansible-doc, Galaxy README, or graceful degradation |
| `get_collection_docs(collection_namespace, version?)` | Get all module docs for a collection from Galaxy in a single call |
| `get_collection_manifest(collection_namespace)` | Collection-level manifest with per-module and per-role summaries |
| `search_docs(query, source?, topic?, audience?, core_only?)` | Search documentation manifests for conceptual guides (up to 20 matches) |
| `fetch_doc(url, max_tokens?)` | Fetch a docs.ansible.com page as clean Markdown |

### Collection management

| Tool | Description |
|------|-------------|
| `ensure_collection(collection_namespace, version?)` | Install a collection to a temporary directory for this session |

### Skills

| Tool | Description |
|------|-------------|
| `list_skills()` | List all generated skills |
| `get_skill(skill_name)` | Read a skill's SKILL.md content |
| `generate_skill(module_name, install_to?)` | Generate a skill package for one module |
| `generate_role_skill(role_name, install_to?)` | Generate a skill package for one role |
| `generate_plugin_skill(plugin_name, plugin_type, install_to?)` | Generate a skill package for one plugin |
| `generate_collection_skills(collection_namespace, install_to?)` | Batch generate skills for an entire collection |

### Maintenance

| Tool | Description |
|------|-------------|
| `clear_cache(scope?)` | Clear Galaxy and/or doc manifest caches |

## Resources

| URI | Description |
|-----|-------------|
| `skills://list` | List all generated skill packages |
| `skills://{skill_name}` | Read a skill's SKILL.md content by FQCN |
| `galaxy://installed` | List collections installed in this session |
| `galaxy://servers` | List configured Galaxy servers (names, URLs, auth types — never credentials) |
| `server://version` | Installed and latest version info with upgrade status |
| `docs://sources` | List configured documentation manifest sources |

## Prompts

| Prompt | Description |
|--------|-------------|
| `review_playbook(playbook_yaml)` | Review a playbook against module docs and best practices |
| `explain_module(module_name)` | Detailed module explanation with usage examples |
| `explain_plugin(plugin_name, plugin_type)` | Detailed plugin 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 |

## Multi-server Galaxy Support

Ansible Know reads `[galaxy_server.*]` sections from `ansible.cfg` (resolved in standard order: `ANSIBLE_CONFIG` env, `./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/
```

- Token auth, basic auth, and per-server TLS verification
- `search_collections` queries all configured servers in parallel, merging 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 Variable | Description | Default |
|---------------------|-------------|---------|
| `ANSIBLE_KNOW_SKILLS_DIR` | Where to write generated skills | `./skills/` |
| `ANSIBLE_KNOW_DOC_SOURCES` | JSON dict of doc manifest sources | Built-in ansible-core source |
| `ANSIBLE_KNOW_GALAXY_URL` | Galaxy API base URL | `https://galaxy.ansible.com` |
| `ANSIBLE_KNOW_SKIP_UPDATE_CHECK` | Set to `1` to disable PyPI version check at startup | *(not set)* |
| `ANSIBLE_KNOW_NO_PUBLIC_GALAXY` | Set to `1` to suppress auto-appending public Galaxy | *(not set)* |

## Upgrading

| Method | Command |
|--------|---------|
| `uvx` | `uvx --upgrade ansible-know-mcp` |
| `pip` | `pip install --upgrade ansible-know-mcp` |
| Claude Code | `uvx --upgrade ansible-know-mcp` then restart Claude Code |
| VS Code / Cursor | `uvx --upgrade ansible-know-mcp` then reload window |
| Local dev | `git pull && uv sync` |

> **Note:** `uvx` caches the installed version and does not auto-upgrade on new releases.
> To always run the latest version (at the cost of slower startup):
> `claude mcp add ansible-know -- uvx --upgrade ansible-know-mcp`

## Deployment

### Hugging Face Spaces

Deploy as a remote MCP server on [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces):

1. Create a new Space with **SDK: Docker**
2. The Space's `README.md` must include YAML frontmatter:
   ```yaml
   ---
   title: Ansible Know MCP
   emoji: "\U0001F4DA"
   sdk: docker
   app_port: 7860
   ---
   ```
3. Push this repository (or set it as the Space's linked repo)
4. The included `Dockerfile` builds and starts the server automatically

> **Note:** Free-tier Spaces sleep after inactivity. MCP clients will see
> connection errors until the Space wakes up (~30-60s cold start). Use
> a paid Space or a keep-alive ping for production use.

**Custom domain** (optional):

1. In the Space settings, go to **Custom domains**
2. Add your domain (e.g., `know.ansible.ar`)
3. Create a CNAME record pointing to `<owner>-<space-name>.hf.space`
4. HF provisions a TLS certificate automatically

**Environment variables** (set in Space settings):

| Variable | Required | Description |
|----------|----------|-------------|
| `ANSIBLE_KNOW_SKILLS_DIR` | No | Defaults to `./skills/` (ephemeral in container) |
| `ANSIBLE_KNOW_NO_PUBLIC_GALAXY` | No | Set to `1` to disable public Galaxy fallback |

### Generic Docker

The `Dockerfile` works with any container platform (Fly.io, Railway, Cloud Run, etc.):

```bash
docker build -t ansible-know-mcp .
docker run -p 8080:7860 ansible-know-mcp
```

Override defaults with environment variables:

```bash
docker run -p 9090:9090 \
  -e ANSIBLE_KNOW_PORT=9090 \
  ansible-know-mcp
```

## Development

```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
```

## Acknowledgments

The skill generation approach in this project was inspired by [AnsibleClaw](https://github.com/micytao/AnsibleClaw) by Michael Tao — a skill generation framework that converts Ansible modules into portable AI agent skill packages.

## License

GPL-3.0-or-later
