rocannon 0.1.0__tar.gz

rocannon-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: rocannon
+Version: 0.1.0
+Summary: Every Ansible module as a typed MCP tool
+Keywords: ansible,mcp,model-context-protocol,automation,ibm-z,zos
+Author: Adam Munawar Rahman
+Author-email: Adam Munawar Rahman <msrahmanadam@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: prompt-toolkit>=3.0.52
+Requires-Dist: typer>=0.26.7
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: litellm>=1.89.0 ; extra == 'ai'
+Requires-Dist: ansible-core>=2.21.0 ; extra == 'all'
+Requires-Dist: ansible-runner>=2.4.3 ; extra == 'all'
+Requires-Dist: litellm>=1.89.0 ; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.42.1 ; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp>=1.42.1 ; extra == 'all'
+Requires-Dist: ansible-core>=2.21.0 ; extra == 'ansible'
+Requires-Dist: ansible-runner>=2.4.3 ; extra == 'ansible'
+Requires-Dist: opentelemetry-sdk>=1.42.1 ; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp>=1.42.1 ; extra == 'otel'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/msradam/rocannon
+Project-URL: Repository, https://github.com/msradam/rocannon
+Project-URL: Issues, https://github.com/msradam/rocannon/issues
+Provides-Extra: ai
+Provides-Extra: all
+Provides-Extra: ansible
+Provides-Extra: otel
+Description-Content-Type: text/markdown
+
+<h1 align="center">Rocannon</h1>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/msradam/rocannon/main/docs/assets/gryphon.svg" alt="" width="120">
+</p>
+
+Rocannon is an MCP server that registers every installed Ansible module as a
+typed tool. It reads `ansible-doc -j` for each module at startup and builds a
+Pydantic-validated function signature, then exposes the result over the MCP
+protocol (stdio or HTTP). Any MCP client (Claude Code, Cursor, mcphost,
+custom agents) calls the same tools an operator would call from a REPL.
+
+Each registered tool carries the module's own `ansible-doc` metadata: a JSON
+output schema for structured results, and MCP safety hints derived from the
+module's attributes (read-only for fact modules, destructive and open-world for
+`command`, `shell`, `script`, and `raw`).
+
+Every module is also a top-level CLI subcommand:
+
+```
+rocannon ansible.builtin.command --target h1 --cmd 'uptime'
+rocannon ansible.builtin.copy    --target h1 --src /etc/hosts --dest /tmp/h
+```
+
+Append `--record path/to/runbook.yml` to any invocation and Rocannon writes
+each call as a new play in a real Ansible playbook. The resulting file runs
+directly under `ansible-playbook -i <inv> path/to/runbook.yml`.
+
+Add `--check` to preview a change without applying it (Ansible check mode) and
+`--diff` to see what would change. Each is offered per module according to its
+declared check-mode support, both on the CLI and as a parameter on the matching
+MCP tool. `rocannon playbook run <name> --check` previews an entire saved runbook.
+
+Sessions driven via the MCP server save the same way: as Ansible playbooks
+under `.rocannon/playbooks/`. Rocannon also loads them back on next startup
+as MCP prompts.
+
+![demo](https://raw.githubusercontent.com/msradam/rocannon/main/docs/assets/demo.gif)
+
+## Install
+
+```bash
+pip install 'rocannon[ansible]'
+```
+
+`ansible-doc` and `ansible-runner` must be on PATH. `rocannon doctor` reports
+anything missing.
+
+## Quickstart
+
+The quickstart profile targets `localhost` with `ansible_connection=local`.
+
+```bash
+cd examples/quickstart
+rocannon mcp doctor --profile profile.yml   # list registered tools
+rocannon repl       --profile profile.yml   # operator shell
+```
+
+Inside the REPL:
+
+```
+rocannon> .target localhost
+rocannon> ping
+rocannon> command cmd="uptime"
+rocannon> .save my_session
+rocannon> .exit
+```
+
+`.save` writes `.rocannon/playbooks/my_session.yml` as a standard Ansible
+playbook. Run it directly with `ansible-playbook -i hosts my_session.yml`, or
+let Rocannon load it back as an MCP prompt next time the server starts.
+
+## CLI
+
+```
+rocannon <fqcn>        invoke a module: rocannon ansible.builtin.copy ...
+                       optional --record FILE appends each call to a playbook
+rocannon mcp serve     start the MCP server (stdio or http)
+rocannon mcp doctor    list registered tools, resources, prompts
+rocannon repl          interactive shell on the same MCP server
+rocannon run           legacy ad-hoc form (module FQCN + -a key=value)
+rocannon doctor        system health (binaries, env, inventory)
+rocannon doc <module>  print parsed schema for a module
+rocannon search <q>    find modules by name or description
+rocannon ls            list hosts/groups/modules from a profile
+rocannon playbook      list/show/run saved playbooks
+```
+
+Per-module help (typed flags, defaults, descriptions from `ansible-doc`):
+`rocannon ansible.builtin.copy --help`. Modules that support check mode also
+accept `--check` and `--diff`.
+
+## Profiles
+
+A profile is a YAML file declaring inventory + modules:
+
+```yaml
+inventories:
+  - ./hosts
+modules:
+  - ansible.builtin
+  - ibm.ibm_zos_core
+ansible_cfg: ./ansible.cfg          # optional
+vault_password_file: ~/.vault_pass  # optional
+extra_envvars:                      # optional
+  ZOAU_HOME: /usr/lpp/IBM/zoautil
+```
+
+`modules` accepts a specific module (`ansible.builtin.copy`), a collection
+(`ansible.builtin`), or a namespace (`community`).
+
+Multiple profiles can live under `.rocannon/profiles/`:
+
+```
+.rocannon/profiles/
+├── box1.yml
+├── box2.yml
+└── default.yml -> box1.yml
+```
+
+```bash
+rocannon mcp serve                     # uses default.yml
+rocannon mcp serve --profile box2
+```
+
+The active profile can be switched at runtime via three MCP tools:
+`rocannon_list_profiles`, `rocannon_current_profile`, `rocannon_use_profile`.
+The tool surface is the union of every profile's modules; a call to a module
+that isn't in the active profile returns a structured error pointing at
+`rocannon_use_profile`.
+
+## MCP clients
+
+A working `.mcp.json` ships at the repo root. Per-client snippets are in
+[`examples/clients/`](examples/clients/).
+
+| Client | Config location |
+|---|---|
+| Claude Code | `.mcp.json` at project root, or `claude mcp add` |
+| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Cursor | `.cursor/mcp.json` or `~/.cursor/mcp.json` |
+| mcphost | `~/.mcphost.yml` or `--config <path>` |
+| IBM Bob | `.bob/mcp.json` or `~/.bob/mcp_settings.json` |
+
+All share the standard `mcpServers` envelope pointing at
+`rocannon mcp serve --profile <your-profile.yml>`.
+
+## Development
+
+```bash
+git clone https://github.com/msradam/rocannon.git
+cd rocannon
+uv sync
+./tests/check.sh                # ruff format + lint + mypy + pytest
+uv run pytest -m integration    # opt-in: spins up a real UBI9 container
+```
+
+See [`ARCHITECTURE.md`](ARCHITECTURE.md) for how the pieces fit together.
+
+Rocannon is developed with AI assistance.
+
+## The name
+
+Ursula K. Le Guin coined the word "ansible" in her 1966 novel *Rocannon's
+World*. The gryphon is a nod to the Windsteeds that Rocannon and his
+companions ride.
+
+## Credits
+
+- Gryphon icon: [Gryphon by Aleksei Kovalenko from Noun Project](https://thenounproject.com/icon/gryphon-7096619/) (CC BY 3.0).

rocannon-0.1.0/README.md

@@ -0,0 +1,170 @@
+<h1 align="center">Rocannon</h1>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/msradam/rocannon/main/docs/assets/gryphon.svg" alt="" width="120">
+</p>
+
+Rocannon is an MCP server that registers every installed Ansible module as a
+typed tool. It reads `ansible-doc -j` for each module at startup and builds a
+Pydantic-validated function signature, then exposes the result over the MCP
+protocol (stdio or HTTP). Any MCP client (Claude Code, Cursor, mcphost,
+custom agents) calls the same tools an operator would call from a REPL.
+
+Each registered tool carries the module's own `ansible-doc` metadata: a JSON
+output schema for structured results, and MCP safety hints derived from the
+module's attributes (read-only for fact modules, destructive and open-world for
+`command`, `shell`, `script`, and `raw`).
+
+Every module is also a top-level CLI subcommand:
+
+```
+rocannon ansible.builtin.command --target h1 --cmd 'uptime'
+rocannon ansible.builtin.copy    --target h1 --src /etc/hosts --dest /tmp/h
+```
+
+Append `--record path/to/runbook.yml` to any invocation and Rocannon writes
+each call as a new play in a real Ansible playbook. The resulting file runs
+directly under `ansible-playbook -i <inv> path/to/runbook.yml`.
+
+Add `--check` to preview a change without applying it (Ansible check mode) and
+`--diff` to see what would change. Each is offered per module according to its
+declared check-mode support, both on the CLI and as a parameter on the matching
+MCP tool. `rocannon playbook run <name> --check` previews an entire saved runbook.
+
+Sessions driven via the MCP server save the same way: as Ansible playbooks
+under `.rocannon/playbooks/`. Rocannon also loads them back on next startup
+as MCP prompts.
+
+![demo](https://raw.githubusercontent.com/msradam/rocannon/main/docs/assets/demo.gif)
+
+## Install
+
+```bash
+pip install 'rocannon[ansible]'
+```
+
+`ansible-doc` and `ansible-runner` must be on PATH. `rocannon doctor` reports
+anything missing.
+
+## Quickstart
+
+The quickstart profile targets `localhost` with `ansible_connection=local`.
+
+```bash
+cd examples/quickstart
+rocannon mcp doctor --profile profile.yml   # list registered tools
+rocannon repl       --profile profile.yml   # operator shell
+```
+
+Inside the REPL:
+
+```
+rocannon> .target localhost
+rocannon> ping
+rocannon> command cmd="uptime"
+rocannon> .save my_session
+rocannon> .exit
+```
+
+`.save` writes `.rocannon/playbooks/my_session.yml` as a standard Ansible
+playbook. Run it directly with `ansible-playbook -i hosts my_session.yml`, or
+let Rocannon load it back as an MCP prompt next time the server starts.
+
+## CLI
+
+```
+rocannon <fqcn>        invoke a module: rocannon ansible.builtin.copy ...
+                       optional --record FILE appends each call to a playbook
+rocannon mcp serve     start the MCP server (stdio or http)
+rocannon mcp doctor    list registered tools, resources, prompts
+rocannon repl          interactive shell on the same MCP server
+rocannon run           legacy ad-hoc form (module FQCN + -a key=value)
+rocannon doctor        system health (binaries, env, inventory)
+rocannon doc <module>  print parsed schema for a module
+rocannon search <q>    find modules by name or description
+rocannon ls            list hosts/groups/modules from a profile
+rocannon playbook      list/show/run saved playbooks
+```
+
+Per-module help (typed flags, defaults, descriptions from `ansible-doc`):
+`rocannon ansible.builtin.copy --help`. Modules that support check mode also
+accept `--check` and `--diff`.
+
+## Profiles
+
+A profile is a YAML file declaring inventory + modules:
+
+```yaml
+inventories:
+  - ./hosts
+modules:
+  - ansible.builtin
+  - ibm.ibm_zos_core
+ansible_cfg: ./ansible.cfg          # optional
+vault_password_file: ~/.vault_pass  # optional
+extra_envvars:                      # optional
+  ZOAU_HOME: /usr/lpp/IBM/zoautil
+```
+
+`modules` accepts a specific module (`ansible.builtin.copy`), a collection
+(`ansible.builtin`), or a namespace (`community`).
+
+Multiple profiles can live under `.rocannon/profiles/`:
+
+```
+.rocannon/profiles/
+├── box1.yml
+├── box2.yml
+└── default.yml -> box1.yml
+```
+
+```bash
+rocannon mcp serve                     # uses default.yml
+rocannon mcp serve --profile box2
+```
+
+The active profile can be switched at runtime via three MCP tools:
+`rocannon_list_profiles`, `rocannon_current_profile`, `rocannon_use_profile`.
+The tool surface is the union of every profile's modules; a call to a module
+that isn't in the active profile returns a structured error pointing at
+`rocannon_use_profile`.
+
+## MCP clients
+
+A working `.mcp.json` ships at the repo root. Per-client snippets are in
+[`examples/clients/`](examples/clients/).
+
+| Client | Config location |
+|---|---|
+| Claude Code | `.mcp.json` at project root, or `claude mcp add` |
+| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Cursor | `.cursor/mcp.json` or `~/.cursor/mcp.json` |
+| mcphost | `~/.mcphost.yml` or `--config <path>` |
+| IBM Bob | `.bob/mcp.json` or `~/.bob/mcp_settings.json` |
+
+All share the standard `mcpServers` envelope pointing at
+`rocannon mcp serve --profile <your-profile.yml>`.
+
+## Development
+
+```bash
+git clone https://github.com/msradam/rocannon.git
+cd rocannon
+uv sync
+./tests/check.sh                # ruff format + lint + mypy + pytest
+uv run pytest -m integration    # opt-in: spins up a real UBI9 container
+```
+
+See [`ARCHITECTURE.md`](ARCHITECTURE.md) for how the pieces fit together.
+
+Rocannon is developed with AI assistance.
+
+## The name
+
+Ursula K. Le Guin coined the word "ansible" in her 1966 novel *Rocannon's
+World*. The gryphon is a nod to the Windsteeds that Rocannon and his
+companions ride.
+
+## Credits
+
+- Gryphon icon: [Gryphon by Aleksei Kovalenko from Noun Project](https://thenounproject.com/icon/gryphon-7096619/) (CC BY 3.0).

rocannon-0.1.0/pyproject.toml

@@ -0,0 +1,155 @@
+[project]
+name = "rocannon"
+version = "0.1.0"
+description = "Every Ansible module as a typed MCP tool"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Adam Munawar Rahman", email = "msrahmanadam@gmail.com" }
+]
+requires-python = ">=3.12"
+keywords = ["ansible", "mcp", "model-context-protocol", "automation", "ibm-z", "zos"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Systems Administration",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+
+# Core framework only; Ansible is opt-in via the `ansible` extra.
+dependencies = [
+    "fastmcp>=3.4.2",
+    "prompt_toolkit>=3.0.52",
+    "typer>=0.26.7",
+    "pydantic>=2.13.4",
+    "pyyaml>=6.0.3",
+]
+
+[project.optional-dependencies]
+# `pip install 'rocannon[ansible]'` pulls in ansible-core + ansible-runner.
+ansible = [
+    "ansible-core>=2.21.0",
+    "ansible-runner>=2.4.3",
+]
+
+# --- AI ---
+# `pip install 'rocannon[ai]'` enables `.ai` mode in the REPL. Backend is
+# picked per-call via ROCANNON_AI_MODEL (e.g. "anthropic/claude-sonnet-4-5",
+# "openai/gpt-4o", "ollama/llama3.1", "watsonx/<model>"). LiteLLM owns the
+# provider matrix; rocannon stays unopinionated about it.
+ai = [
+    "litellm>=1.89.0",
+]
+
+# --- Observability ---
+# `pip install 'rocannon[otel]'`; run under `opentelemetry-instrument rocannon mcp serve …`
+otel = [
+    "opentelemetry-sdk>=1.42.1",
+    "opentelemetry-exporter-otlp>=1.42.1",
+]
+
+# --- Meta ---
+# `pip install 'rocannon[all]'`, everything.
+all = [
+    "ansible-core>=2.21.0",
+    "ansible-runner>=2.4.3",
+    "litellm>=1.89.0",
+    "opentelemetry-sdk>=1.42.1",
+    "opentelemetry-exporter-otlp>=1.42.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/msradam/rocannon"
+Repository = "https://github.com/msradam/rocannon"
+Issues = "https://github.com/msradam/rocannon/issues"
+
+[project.scripts]
+rocannon = "rocannon.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.14,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+# `uv sync` installs these alongside the project. Includes the `ansible` extra's
+# Python deps so the test suite + lint can run against the full codebase.
+dev = [
+    "ansible-core>=2.21.0",
+    "ansible-runner>=2.4.3",
+    "litellm>=1.89.0",
+    "mypy>=2.1.0",
+    "opentelemetry-sdk>=1.42.1",
+    "ollama>=0.6.2",
+    "pre-commit>=4.6.0",
+    "pytest>=9.1.0",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.17",
+    "types-pyyaml>=6.0.12.20260518",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+# Collect only the tracked suite by default. dev/tests/ holds local LLM evals
+# that hit a real model; running them is opt-in via an explicit path.
+testpaths = ["tests"]
+markers = [
+    "integration: end-to-end tests that touch real docker/ansible. Opt-in via `pytest -m integration`.",
+]
+# Default: run unit tests, skip integration. Override with `pytest -m integration`.
+addopts = "-m 'not integration'"
+
+[tool.coverage.run]
+branch = true
+source = ["src/rocannon"]
+omit = ["src/rocannon/__main__.py"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+]
+
+# --- Ruff ---
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "N", "UP", "B", "C4", "SIM", "S", "FURB"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S105", "S108", "S110", "S310", "S603", "S607"]
+"src/rocannon/schema.py" = ["S603", "S607"]
+"src/rocannon/inventory.py" = ["S603"]
+"src/rocannon/cli.py" = ["S603", "S607"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+# --- Mypy ---
+[tool.mypy]
+python_version = "3.12"
+strict = true
+disallow_untyped_defs = true
+warn_return_any = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+no_implicit_reexport = true
+mypy_path = "src"
+
+# Third-party libs without bundled type stubs. ansible_runner ships
+# partial stubs only.
+[[tool.mypy.overrides]]
+module = ["ansible_runner.*"]
+ignore_missing_imports = true