Metadata-Version: 2.4
Name: ansible-know-mcp
Version: 0.1.0
Summary: Ansible Knowledge MCP Server — module 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>=3.0
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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:

- **Module discovery** — search and explore Ansible modules across all installed collections
- **Module documentation** — get structured parameter specs, examples, and metadata
- **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 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](https://github.com/ansible/ansible-dev-tools) (build) and [AAP MCP](https://github.com/ansible/aap-mcp-server) (deploy), this enables the full autonomous cycle: **learn -> build -> deploy**.

```
 Agent's MCP servers:

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

## Installation

Using `uvx` (recommended):

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

Using `pip`:

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

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

## Usage

### With Claude Code

```bash
claude mcp add ansible-know -- uvx ansible-know-mcp
```

To make it available in all projects:

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

### With VS Code / Cursor

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

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

### With any MCP client

The server runs over stdio by default:

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

### Full stack configuration

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

## Tools

### Discovery (read-only)

| Tool | Description |
|------|-------------|
| `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. |
| `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 summaries. |

### Skill management

| Tool | Description |
|------|-------------|
| `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_collection_skills(collection_namespace, install_to?)` | Batch generate skills for an entire collection. |

## Resources

| URI | Description |
|-----|-------------|
| `skills://list` | List all generated skill packages |
| `skills://{skill_name}` | Read a skill's SKILL.md content by FQCN |
| `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)` | Get a detailed module explanation with usage examples |
| `generate_role(role_purpose, modules)` | Generate a role skeleton using specified modules |

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

## Configuration

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `ANSIBLE_KNOWLEDGE_SKILLS_DIR` | Where to write generated skills | `./skills/` |
| `ANSIBLE_KNOWLEDGE_DOC_SOURCES` | JSON dict of doc manifest sources | Built-in ansible-core source |

## License

GPL-3.0-or-later
