@yawlabs/ansible-mcp 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +239 -2
- package/bin/ansible-mcp.mjs +702 -0
- package/dist/ansibleDoc.d.ts +98 -0
- package/dist/checkArgs.d.ts +35 -0
- package/dist/collections.d.ts +66 -0
- package/dist/config.d.ts +46 -0
- package/dist/constraints.d.ts +35 -0
- package/dist/context.d.ts +115 -0
- package/dist/exec.d.ts +177 -0
- package/dist/handlers.d.ts +64 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +5170 -0
- package/dist/inventory.d.ts +54 -0
- package/dist/lint.d.ts +25 -0
- package/dist/paths.d.ts +34 -0
- package/dist/playbook.d.ts +61 -0
- package/dist/project.d.ts +159 -0
- package/dist/redact.d.ts +90 -0
- package/dist/role.d.ts +50 -0
- package/dist/server.d.ts +22 -0
- package/dist/server.js +5328 -0
- package/dist/tools.d.ts +5 -0
- package/dist/upgrade.d.ts +111 -0
- package/dist/yaml.d.ts +56 -0
- package/package.json +93 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Yaw Labs
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,240 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @yawlabs/ansible-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://yaw.sh/mcp/install?name=Ansible&command=npx&args=-y%2C%40yawlabs%2Fansible-mcp&description=Ansible%20checkout%20truth%3A%20module%20specs%2C%20task%20args%2C%20roles%2C%20inventory%2C%20plays%2C%20upgrade%20impact&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fansible-mcp)
|
|
4
|
+
|
|
5
|
+
One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.
|
|
6
|
+
|
|
7
|
+
**What is actually true in THIS Ansible checkout on THIS control node: the exact option specs of the modules you have INSTALLED (so coding agents stop writing options that do not exist in your collection version), task-argument checks, role interfaces, inventory structure and vars (redacted), play structure, effective config, requirements drift, and what a collection upgrade would break in your tasks.** It is read-only: it never runs a play, never runs `--check`, never connects to a managed host and never supplies a vault secret. It complements Red Hat's servers rather than replacing them: AAP MCP answers what is true in the controller, ADT MCP takes actions (lint `--fix`, navigator runs, scaffolding, EE builds). Run them together.
|
|
8
|
+
|
|
9
|
+
[](https://www.npmjs.com/package/@yawlabs/ansible-mcp)
|
|
10
|
+
[](https://opensource.org/licenses/MIT)
|
|
11
|
+
|
|
12
|
+
Built and maintained by [Yaw Labs](https://yaw.sh).
|
|
13
|
+
|
|
14
|
+
## Why this one?
|
|
15
|
+
|
|
16
|
+
Your checkout has `community.general 9.5.2`; the model's training data has whatever version it saw most. Agents then write `git_config: list_all: true` (removed in 11.0.0), forget `name` (required since 12.0.0), or set `state: present` on `rhsm_repository` (no longer accepted). The VS Code language server knows the exact specs, but only a person in the editor sees them. This server lets the agent check *before* it writes, against what is installed.
|
|
17
|
+
|
|
18
|
+
- **Installed, not latest** -- the source of truth is `ansible-doc --json` run against your collections paths, with redirects (`ufw` -> `community.general.ufw`) and tombstones resolved.
|
|
19
|
+
- **Checks what lint skips** -- `ansible-lint`'s `args` rule skips modules with action plugins (`copy`, `template`); `ansible_check_task_args` catches their unknown options and bad values, and says plainly which cross-option rules ansible-doc cannot express.
|
|
20
|
+
- **YAML 1.1 aware** -- Ansible parses YAML 1.1, so unquoted `off` is `false` and `0755` is the integer 493. The server reads YAML the same way and says when that is probably a bug.
|
|
21
|
+
- **Read-only by construction** -- configured vault password scripts never run (a server-owned dummy password file replaces them), script and plugin inventory sources are off by default, and play-level lookups are refused before Ansible parses a playbook.
|
|
22
|
+
- **Collection upgrade impact** -- downloads only the target version into its own cache and diffs the arg specs of the modules your tasks actually use, tied to file:line.
|
|
23
|
+
- **macOS, Linux, and Windows through WSL** -- Ansible has no Windows control node; on Windows the server spawns it through `wsl.exe --exec` (no shell anywhere).
|
|
24
|
+
|
|
25
|
+
## Tools
|
|
26
|
+
|
|
27
|
+
| Tool | What it does |
|
|
28
|
+
|---|---|
|
|
29
|
+
| `ansible_project_info` | ansible-core version, effective config file, collections and roles paths, installed `ansible-*` binaries, detected playbooks, inventories (with whole-file vault count), roles and requirements files. Call this first. |
|
|
30
|
+
| `ansible_module_doc` | Every option of one module or plugin as installed: type, required, default, choices, aliases, suboptions, deprecations, `no_log`, the providing collection version, `[has action plugin]`, returns and (optionally) examples. |
|
|
31
|
+
| `ansible_module_search` | Find installed modules/plugins by name or description, ranked exact, prefix, token, then description. |
|
|
32
|
+
| `ansible_check_task_args` | Check inline task YAML or a tasks file / playbook against the installed docs: unknown options, missing required ones (aliases count), bad choices and types, suboptions, `mode: 0755`, deprecated options, duplicate keys. Never claims "valid": it names what ansible-doc cannot check. |
|
|
33
|
+
| `ansible_role_interface` | A role's argument_specs entry points and options, defaults (redacted, `no_log` honoured), undocumented defaults, dependencies, vars names, galaxy_info. Local roles and `ns.collection.role`. |
|
|
34
|
+
| `ansible_inventory` | Groups, hosts, and inventory-level vars (names or values), always redacted. Whole-file vaults degrade to a per-file view instead of failing. |
|
|
35
|
+
| `ansible_playbook_structure` | `--syntax-check`, then plays, matched hosts, tasks with module and file:line, tags, and the deprecation warnings Ansible printed while parsing. |
|
|
36
|
+
| `ansible_config` | Effective config with origins (ansible.cfg, env, default); galaxy credentials always redacted; settings the server overrides for safety are flagged. |
|
|
37
|
+
| `ansible_collections` | requirements.yml vs installed: ok / VIOLATES / MISSING with file:line, galaxy constraint semantics, and shadowed copies across collections paths. |
|
|
38
|
+
| `ansible_lint_summary` | `ansible-lint --offline` grouped by rule with counts, severities and locations. Never fixes. |
|
|
39
|
+
| `ansible_upgrade_impact` | What breaks in this project's tasks if a collection moves to an exact version: removed/moved modules (runtime.yml redirects and tombstones), removed options and aliases, newly required options, dropped choices, type and default changes, requirements constraints, `requires_ansible`, an optional syntax-check against the target, and a verdict. |
|
|
40
|
+
|
|
41
|
+
Every tool takes an optional `dir` (the project). Tool names carry an `ansible_` prefix and never reuse ADT MCP's names (`ansible_lint`, `ansible_navigator`, ...), so both can sit behind one aggregator.
|
|
42
|
+
|
|
43
|
+
### Division of authority
|
|
44
|
+
|
|
45
|
+
| Question | Authority |
|
|
46
|
+
|---|---|
|
|
47
|
+
| Controller jobs, job templates, controller inventories, RBAC | AAP MCP |
|
|
48
|
+
| Scaffold content, `ansible-lint --fix`, run via ansible-navigator, set up a venv or EE | ADT MCP |
|
|
49
|
+
| Interactive editing for a person | VS Code Ansible extension (language server) |
|
|
50
|
+
| Generate new content from intent | Ansible Lightspeed |
|
|
51
|
+
| Execute modules against hosts | not this server |
|
|
52
|
+
| Installed specs, task-argument validity, role interfaces, local inventory, play structure, effective config, dependency drift, collection upgrade impact | **ansible-mcp** (read-only) |
|
|
53
|
+
|
|
54
|
+
### What is read-only, and what touches the network
|
|
55
|
+
|
|
56
|
+
- **Never run:** plays, modules, `--check`, `--diff`, fact gathering. The only Ansible commands are `ansible --version`, `ansible-config dump`, `ansible-doc`, `ansible-inventory --list/--host/--graph`, `ansible-playbook --syntax-check/--list-*`, `ansible-galaxy collection list` / `role list`, `ansible-lint --offline`, and (only in `ansible_upgrade_impact`) `ansible-galaxy collection install --no-deps -p <server cache>`.
|
|
57
|
+
- **Never written:** your project, your collections and roles paths, requirements files, and anything inside an existing `~/.ansible`. Ansible's local temp, galaxy cache and (when you have none) galaxy token file are redirected to the server's cache. The one residue: Ansible creates an empty `~/.ansible` when it does not exist, and ansible-lint creates empty `~/.ansible/roles` / `~/.ansible/collections` when they are missing.
|
|
58
|
+
- **Vault:** no secret is ever supplied, and a `vault_password_file` / `vault_identity_list` script named in ansible.cfg never runs (it is replaced by a server-owned file holding a random password). Inline `!vault` values print as `<vaulted>`; whole-file vaults are listed, not read.
|
|
59
|
+
- **Dynamic inventory** (script, constructed, cloud plugins) runs code and calls APIs, so it is off unless `ANSIBLE_MCP_ALLOW_DYNAMIC_INVENTORY=1`; skipped sources are named in the answer.
|
|
60
|
+
- **Residual risk, stated:** `ansible-playbook --syntax-check` (and ansible-lint, which runs it) evaluates Jinja in play-level `name`, `hosts` and `vars_files` and imports playbook-adjacent `vars_plugins/`. Treat `dir` as code you would run `--syntax-check` on. Lookups in those fields are refused before Ansible sees them unless `ANSIBLE_MCP_ALLOW_PLAY_LOOKUPS=1`, and local plugin files are listed in the answer.
|
|
61
|
+
- **Redaction** (`ansible_inventory`, `ansible_role_interface`, `ansible_config`, lint messages): vault markers, plus any string equal to a hidden one, plus values under secret-like names (`ansible_become_password`, `api_token`, `vault_db_password`, ... but not `vault_addr` or `private_key_file`), plus secret-shaped strings (private keys, JWTs, GitHub/GitLab/Slack/npm tokens; URL passwords masked in place). Galaxy server tokens and passwords are always redacted. There is no "show secrets" switch.
|
|
62
|
+
- **Network:** only `ansible_upgrade_impact`, on a cache miss, to Galaxy or the servers in your ansible.cfg (`openWorldHint: true`). The cache is never evicted automatically; deleting it is safe.
|
|
63
|
+
|
|
64
|
+
Example `ansible_check_task_args` output (real docs, community.general 9.5.2):
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
playbooks/tasks/bad_args.yml: 7 tasks checked against installed docs (ansible-core 2.21.5): 5 problems in 3 tasks
|
|
68
|
+
:3 ansible.builtin.copy [has action plugin; ansible-lint skips its arguments]
|
|
69
|
+
unknown option owner_name (line 7)
|
|
70
|
+
unknown option state (line 9)
|
|
71
|
+
backup (line 8): expected bool, got a string that is not a boolean ('maybe')
|
|
72
|
+
:12 ansible.posix.mount
|
|
73
|
+
missing required option path (aliases: name)
|
|
74
|
+
:18 ansible.builtin.file (key=value form): ok (dest is an alias of path)
|
|
75
|
+
:21 ansible.builtin.copy: ok by docs [not checked: src and content are mutually exclusive in the module's argument_spec, which ansible-doc does not expose]
|
|
76
|
+
:32 ansible.builtin.apt: ok; 2 templated values not checked (state, update_cache)
|
|
77
|
+
:38 community.general.ufw (from short name ufw)
|
|
78
|
+
proto (line 41): 'tcpx' is not one of any|tcp|udp|ipv6|esp|ah|gre|igmp
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Example `ansible_upgrade_impact` output (real 9.5.2 -> 12.0.0 docs):
|
|
82
|
+
|
|
83
|
+
```
|
|
84
|
+
upgrade community.general 9.5.2 -> 12.0.0 (major) for /work/site
|
|
85
|
+
target: requires_ansible '>=2.17.0' ok (ansible-core 2.21.5); dependencies: none; downloaded (cache: ...)
|
|
86
|
+
constraints: requirements.yml:3 pins '>=9.0.0,<10.0.0' (change it to allow 12.0.0)
|
|
87
|
+
used modules (7): git_config, proxmox_kvm, consul_acl, slack, rhsm_repository (playbooks/site.yml); timezone (roles/common/tasks/main.yml); ufw (roles/webapp/tasks/main.yml, via short name ufw)
|
|
88
|
+
BREAKING (5):
|
|
89
|
+
playbooks/site.yml:17 community.general.git_config: option list_all removed (line 19)
|
|
90
|
+
playbooks/site.yml:17 community.general.git_config: name is newly required, not set
|
|
91
|
+
playbooks/site.yml:23 community.general.proxmox_kvm: moved to community.proxmox.proxmox_kvm; community.proxmox is not installed (add it to requirements.yml)
|
|
92
|
+
playbooks/site.yml:31 community.general.consul_acl: removed in 10.0.0 (tombstone): Use community.general.consul_token and/or community.general.consul_policy instead.
|
|
93
|
+
playbooks/site.yml:43 community.general.rhsm_repository: state=present no longer accepted (choices: enabled, disabled) (line 45)
|
|
94
|
+
BEHAVIOR CHANGES (1):
|
|
95
|
+
playbooks/site.yml:37 community.general.slack: prepend_hash not set; default 'auto' -> 'never'
|
|
96
|
+
syntax-check with 12.0.0 (playbooks/site.yml): first error playbooks/site.yml:22: couldn't resolve module/action 'community.general.proxmox_kvm' (syntax-check stops at the first error and does not check options)
|
|
97
|
+
verdict: BREAKING (5)
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Quick start
|
|
101
|
+
|
|
102
|
+
**1. Have ansible-core where the server can run it.** On macOS / Linux, `ansible-core` (and optionally `ansible-lint`) on `PATH`, or in a venv you point `ANSIBLE_MCP_BIN_DIR` at. On Windows, inside WSL:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
# inside WSL (any distro); a venv under $HOME survives WSL restarts, /tmp does not
|
|
106
|
+
python3 -m venv ~/.venvs/ansible && ~/.venvs/ansible/bin/pip install ansible-core ansible-lint
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**2. Add the server.** Claude Code, from the project:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
# macOS / Linux
|
|
113
|
+
claude mcp add ansible -- npx -y @yawlabs/ansible-mcp@latest
|
|
114
|
+
|
|
115
|
+
# Windows (Ansible inside WSL)
|
|
116
|
+
claude mcp add ansible -e ANSIBLE_MCP_COMMAND_PREFIX='["wsl.exe","-d","Ubuntu","--exec"]' -e ANSIBLE_MCP_BIN_DIR=/home/me/.venvs/ansible/bin -- cmd /c npx -y @yawlabs/ansible-mcp@latest
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Or add it to `.mcp.json` in the project (or anywhere, and set `ANSIBLE_MCP_DIR`):
|
|
120
|
+
|
|
121
|
+
macOS / Linux:
|
|
122
|
+
|
|
123
|
+
```json
|
|
124
|
+
{
|
|
125
|
+
"mcpServers": {
|
|
126
|
+
"ansible": {
|
|
127
|
+
"command": "npx",
|
|
128
|
+
"args": ["-y", "@yawlabs/ansible-mcp@latest"]
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Windows (Ansible inside WSL):
|
|
135
|
+
|
|
136
|
+
```json
|
|
137
|
+
{
|
|
138
|
+
"mcpServers": {
|
|
139
|
+
"ansible": {
|
|
140
|
+
"command": "cmd",
|
|
141
|
+
"args": ["/c", "npx", "-y", "@yawlabs/ansible-mcp@latest"],
|
|
142
|
+
"env": {
|
|
143
|
+
"ANSIBLE_MCP_COMMAND_PREFIX": "[\"wsl.exe\",\"-d\",\"Ubuntu\",\"--exec\"]",
|
|
144
|
+
"ANSIBLE_MCP_BIN_DIR": "/home/me/.venvs/ansible/bin"
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
> **Why the extra step on Windows?** Since Node 20, `child_process.spawn` cannot directly execute `.cmd` files (that's what `npx` is on Windows). Wrapping with `cmd /c` is the standard workaround.
|
|
152
|
+
|
|
153
|
+
**3. Restart your MCP client** and ask, for example: *"Add a task that opens port 8443 with ufw -- check the arguments against our installed collections first."*
|
|
154
|
+
|
|
155
|
+
### Windows and WSL, in detail
|
|
156
|
+
|
|
157
|
+
- The prefix must use `wsl.exe --exec` (or `-e`), never `--`: with `--`, WSL re-parses the arguments with bash and a value like `it's` breaks the command. The server refuses a prefix without `--exec`.
|
|
158
|
+
- Nothing from the Windows environment crosses into WSL. Variables the Ansible side needs (proxies, `ANSIBLE_COLLECTIONS_PATH`) are forwarded by name with `ANSIBLE_MCP_PASS_ENV`.
|
|
159
|
+
- Windows paths are translated with the mount root `wslpath` reports (`C:\work\site` -> `/mnt/c/work/site`). A project inside WSL works too: pass `dir` as `\\wsl.localhost\Ubuntu\home\me\site` (the distro must match the prefix's `-d`).
|
|
160
|
+
- On a Windows drive every folder looks world-writable to WSL, and Ansible then ignores `ansible.cfg`. When the project has one, the server sets `ANSIBLE_CONFIG` to it explicitly and says so.
|
|
161
|
+
- The server's Ansible-side cache lives under the WSL user's `~/.cache/ansible-mcp` (never `/tmp`, which WSL empties on restart).
|
|
162
|
+
|
|
163
|
+
## Tell your agent to use it
|
|
164
|
+
|
|
165
|
+
Paste this into the project's `CLAUDE.md` (or `AGENTS.md`):
|
|
166
|
+
|
|
167
|
+
```markdown
|
|
168
|
+
## Ansible
|
|
169
|
+
|
|
170
|
+
Module options drift between collection versions. Use the ansible MCP server:
|
|
171
|
+
|
|
172
|
+
- Call `ansible_project_info` once per session.
|
|
173
|
+
- Before writing or editing a task, call `ansible_module_doc` for its module, then
|
|
174
|
+
run `ansible_check_task_args` on the task (or the file). Fix every problem it
|
|
175
|
+
reports; quote values it flags as YAML 1.1 traps.
|
|
176
|
+
- Before using a role, read `ansible_role_interface`.
|
|
177
|
+
- Before bumping a collection in requirements.yml, run `ansible_upgrade_impact`.
|
|
178
|
+
- Never run plays, `--check` or `ansible-lint --fix` on your own; ask first.
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## Configuration
|
|
182
|
+
|
|
183
|
+
All optional.
|
|
184
|
+
|
|
185
|
+
| Env var | Default | Purpose |
|
|
186
|
+
|---|---|---|
|
|
187
|
+
| `ANSIBLE_MCP_DIR` | the server's working directory | Project used when a tool call passes no `dir`. |
|
|
188
|
+
| `ANSIBLE_MCP_COMMAND_PREFIX` | (unset: native) | JSON array prepended to every Ansible command, e.g. `["wsl.exe","-d","Ubuntu","--exec"]`. A value not starting with `[` is split on whitespace. Required on Windows. |
|
|
189
|
+
| `ANSIBLE_MCP_BIN_DIR` | (unset: `PATH`) | Ansible-side directory holding `ansible-*` (a venv's `bin`). Also put first on the child's `PATH` (ansible-lint needs `ansible-playbook` next to it). |
|
|
190
|
+
| `ANSIBLE_MCP_PATH_STYLE` | `auto` | `wsl` or `native`. `auto` is `wsl` when the prefix starts with `wsl`/`wsl.exe`. Other prefixes (`ssh`, `docker exec`) get `env -C <dir> ...` and are best effort. |
|
|
191
|
+
| `ANSIBLE_MCP_PASS_ENV` | (unset) | Comma-separated names of server env vars to forward to the Ansible side in prefix mode. |
|
|
192
|
+
| `ANSIBLE_MCP_TIMEOUT_MS` | `120000` | Kill any Ansible command after this long (the upgrade download gets 3x). |
|
|
193
|
+
| `ANSIBLE_MCP_CACHE` | `~/.cache/ansible-mcp` | Server-side cache (and the Ansible-side one in native mode): the dummy vault file, local temp, upgrade targets. Safe to delete. |
|
|
194
|
+
| `ANSIBLE_MCP_REMOTE_CACHE` | `$HOME/.cache/ansible-mcp` on the Ansible side | The Ansible-side cache in prefix mode. |
|
|
195
|
+
| `ANSIBLE_MCP_ALLOW_DYNAMIC_INVENTORY` | (unset) | `1` re-enables script, constructed and plugin inventory sources (they run code and may call cloud APIs). |
|
|
196
|
+
| `ANSIBLE_MCP_ALLOW_PLAY_LOOKUPS` | (unset) | `1` lets playbooks with lookups in play-level `name` / `hosts` / `vars_files` be parsed (Ansible runs those lookups on this machine). |
|
|
197
|
+
|
|
198
|
+
**Runtime (oam or Node):**
|
|
199
|
+
|
|
200
|
+
The `ansible-mcp` command prefers [oam](https://oamjs.org) when it finds a
|
|
201
|
+
usable one and otherwise runs on Node. It never serves on an oam older than 0.19.0.
|
|
202
|
+
|
|
203
|
+
| Env var | Default | Purpose |
|
|
204
|
+
|---|---|---|
|
|
205
|
+
| `ANSIBLE_MCP_RUNTIME` | `auto` | `auto`: the newest oam at 0.19.0 or newer, else Node. `oam`: oam or exit with an error. `node`: always Node -- the escape hatch when a problem only shows up under oam. |
|
|
206
|
+
| `OAM_BIN` | (unset) | Path to the oam binary to use. Otherwise the launcher checks `OAM_INSTALL_DIR`, the installed locations (`~/.oam/bin`, and `%LOCALAPPDATA%\oam\bin` on Windows) and `PATH`, and takes the newest. |
|
|
207
|
+
|
|
208
|
+
An outdated oam is fixed with `oam self-update`. Under Yaw MCP, which runs servers
|
|
209
|
+
on oam by default, `yaw-mcp set <namespace> runtime=node` switches this server to
|
|
210
|
+
Node. There is no `--permission` sandbox option: the server spawns Ansible and
|
|
211
|
+
reads whatever directory a call names, so there is nothing narrow to grant.
|
|
212
|
+
|
|
213
|
+
## Requirements
|
|
214
|
+
|
|
215
|
+
- Node.js 20+
|
|
216
|
+
- ansible-core on the control node (verified with 2.21.5); ansible-lint for `ansible_lint_summary` (verified with 26.10.1)
|
|
217
|
+
- Windows: WSL with ansible-core installed in a distro, and `ANSIBLE_MCP_COMMAND_PREFIX` set. Without it, only `ansible_project_info` (static half) and `ansible_role_interface` (local files) answer; the rest say what to set.
|
|
218
|
+
- `ansible_upgrade_impact`: Galaxy (or your configured servers) reachable the first time a target version is requested; later runs for that version are offline
|
|
219
|
+
|
|
220
|
+
## Contributing
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
git clone https://github.com/YawLabs/ansible-mcp.git
|
|
224
|
+
cd ansible-mcp
|
|
225
|
+
npm install
|
|
226
|
+
npm run lint # Biome check
|
|
227
|
+
npm run lint:fix # Auto-fix
|
|
228
|
+
npm run build # tsup bundle + declarations
|
|
229
|
+
npm test # Vitest (integration tests run only when Ansible is reachable)
|
|
230
|
+
npm run typecheck # oam check . when oam is installed, else tsc --noEmit
|
|
231
|
+
npm run check:oam-floor # the oam floor agrees across the repo and matches the latest oam release
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow, including release process.
|
|
235
|
+
|
|
236
|
+
## License
|
|
237
|
+
|
|
238
|
+
MIT
|
|
239
|
+
|
|
240
|
+
[](https://x.com/YawLabs)
|