cloud-finops-mcp 1.21.0__tar.gz

cloud_finops_mcp-1.21.0/.gitignore

@@ -0,0 +1,53 @@
+# Internal
+INTERNAL_NOTES.md
+
+# Environment
+.env
+.env.*
+
+# OS files
+.DS_Store
+Thumbs.db
+NUL
+
+# Claude Code local settings (any depth - root, cloud-finops/, etc.)
+.claude/settings.local.json
+**/.claude/settings.local.json
+
+# Claude Code local hooks config
+claude-hooks-settings.json
+
+# Claude Code worktrees (embedded git repos)
+.claude/worktrees/
+
+# Local-only nested .claude/ directories (e.g. cloud-finops/.claude/)
+cloud-finops/.claude/
+
+# Local working notes / plan drafts
+plan-*.md
+plan-remediation-*.md
+
+# Pipeline (private until public release)
+pipeline/
+
+# Reference file backups
+cloud-finops/references/.backups/
+
+# Distribution archive
+cloud-finops.zip
+
+# Python build artefacts (mcp_server/)
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+mcp_server/build/
+mcp_server/dist/
+mcp_server/.venv/
+
+# LinkedIn post drafts
+linkedin-post-*.md
+
+# Review adjudication
+review-adjudication.md

cloud_finops_mcp-1.21.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: cloud-finops-mcp
+Version: 1.21.0
+Summary: MCP server exposing the OptimNow Cloud FinOps skill (28 references) as queryable tools.
+Project-URL: Homepage, https://github.com/OptimNow/cloud-finops-skills
+Project-URL: Repository, https://github.com/OptimNow/cloud-finops-skills
+Project-URL: Issues, https://github.com/OptimNow/cloud-finops-skills/issues
+Project-URL: Documentation, https://github.com/OptimNow/cloud-finops-skills/tree/main/mcp_server
+Author-email: OptimNow <contact@optimnow.io>
+Maintainer-email: Jean Latière <j.latiere@gmail.com>
+License: CC-BY-SA-4.0
+Keywords: aws,azure,claude,cloud,cost,finops,gcp,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cloud-finops-mcp
+
+MCP server exposing the [OptimNow Cloud FinOps skill](https://github.com/OptimNow/cloud-finops-skills)
+(28 reference files + 15 named-pattern playbooks) as queryable tools for any
+MCP-aware client (Claude Code, Cursor, Codex CLI, Windsurf, Aider, Cline, etc.).
+
+The skill itself ships in canonical Claude Agent-Skills format and is also installable
+via the cross-tool installer (`./install.sh`) for direct context injection. This MCP
+server is the **enrichment path**: instead of loading the full skill into the
+prompt, the agent calls tools to discover, filter, and fetch only what it needs.
+
+## What the server exposes
+
+Six tools, all read-only, split across two surfaces.
+
+**References** — long-form provider and discipline files (~300-500 lines each):
+
+| Tool | Purpose |
+|---|---|
+| `list_references()` | List all 28 references with their FCP metadata. |
+| `get_reference(name)` | Fetch the full markdown body of one reference. |
+| `find_references(domain?, capability?, phase?, persona?, maturity?)` | Faceted query over the FinOps Capability/Phase frontmatter. |
+
+The reference faceted query supports any combination of:
+
+- `domain` - FinOps Framework domain (e.g. `Optimize Usage & Cost`, `Quantify Business Value`)
+- `capability` - FinOps capability (matches both primary and secondary)
+- `phase` - `Inform`, `Optimize`, `Operate`
+- `persona` - matches both primary and collaborating personas
+- `maturity` - `Crawl`, `Walk`, `Run`
+
+**Playbooks** — small named-pattern runbooks (~80-130 lines each):
+
+| Tool | Purpose |
+|---|---|
+| `list_playbooks()` | List all 15 named-pattern playbooks with their metadata. |
+| `get_playbook(name)` | Fetch the full markdown body of one playbook. |
+| `find_playbooks(scope?, service?, waste_category?, confidence?)` | Faceted query over the playbook frontmatter. |
+
+The playbook faceted query supports:
+
+- `scope` - `aws`, `azure`, `gcp`, or `cross-cloud`
+- `service` - provider service (e.g. `AWS NAT Gateway`); exact-match
+- `waste_category` - `orphaned`, `idle`, `overprovisioned`, `commitment-mismatch`,
+  `schedule-blindness`, `modernization`, `ai-ml-inefficiency`, `egress`
+- `confidence` - `obvious`, `likely`, `possible` (OptimNow three-tier model)
+
+All filters across both surfaces AND together. String matches are case-insensitive
+and exact (no substring matching).
+
+**When to use which surface:**
+
+- A **playbook** answers *"how do I detect/fix this specific pattern?"* (zombie NAT,
+  snapshot sprawl, idle ELB). It includes problem statement, symptoms, a detection
+  query (CUR / KQL / BigQuery SQL / CLI), fix steps, and the anti-pattern.
+- A **reference** answers anything broader: billing mechanics, commitment strategy,
+  allocation methodology, persona-specific framings, or cross-pattern reasoning.
+
+## Install
+
+```bash
+pip install cloud-finops-mcp
+```
+
+Or run without installing via [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+uvx cloud-finops-mcp
+```
+
+## Configure your MCP client
+
+After install, point your client at the `cloud-finops-mcp` console script.
+
+### Claude Code
+
+Project-level (`.mcp.json` at the repo root) or user-level (`~/.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "cloud-finops": {
+      "command": "cloud-finops-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Code, then run `/mcp` to confirm the server is connected.
+
+### Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cloud-finops": {
+      "command": "cloud-finops-mcp"
+    }
+  }
+}
+```
+
+### Codex CLI
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.cloud-finops]
+command = "cloud-finops-mcp"
+```
+
+### Windsurf
+
+`~/.windsurf/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cloud-finops": {
+      "command": "cloud-finops-mcp"
+    }
+  }
+}
+```
+
+### Any other MCP client
+
+The server speaks MCP over stdio. Point any compatible client at `cloud-finops-mcp`
+(or `python -m cloud_finops_mcp`).
+
+## Example tool calls
+
+Agent prompt: *"Use the cloud-finops MCP to find references for the Optimize phase
+aimed at Engineering."*
+
+Calls `find_references(phase="Optimize", persona="Engineering")` and gets back the
+filtered subset (AWS, Azure, GCP, Bedrock, Databricks, etc.) without loading the full
+skill into the prompt.
+
+Agent prompt: *"Pull the AWS reference."*
+
+Calls `get_reference(name="finops-aws")` and gets back the full markdown body
+(~300 lines) instead of the entire 28-file knowledge base.
+
+Agent prompt: *"Show me the obvious-confidence AWS waste playbooks."*
+
+Calls `find_playbooks(scope="aws", confidence="obvious")` and gets back the list
+of high-signal AWS patterns (zombie NAT gateway, orphaned EBS volumes, etc.).
+
+Agent prompt: *"Walk me through the zombie NAT gateway pattern."*
+
+Calls `get_playbook(name="aws-zombie-nat-gateway")` and gets back the ~90-line
+runbook (problem, symptoms, detection query, fix, anti-pattern, see-also).
+
+## When to use this vs the installer
+
+| If you... | Use |
+|---|---|
+| Want the skill loaded as static context for every chat | The cross-tool installer (`./install.sh`) |
+| Have a big-codebase session with limited context budget | The MCP server (fetch on demand) |
+| Want to filter references by FinOps domain/capability/phase/persona/maturity | The MCP server (`find_references`) |
+| Use a client that doesn't support MCP | The cross-tool installer |
+
+The two paths are complementary. You can install both.
+
+## Development
+
+```bash
+git clone https://github.com/OptimNow/cloud-finops-skills.git
+cd cloud-finops-skills/mcp_server
+python scripts/sync_references.py        # populate src/cloud_finops_mcp/data/
+pip install -e ".[dev]"
+pytest
+```
+
+## Versioning
+
+The PyPI package version tracks the skill release tag. Tagging `v1.13` on the
+parent repo triggers both the skill release zip and a new `cloud-finops-mcp` PyPI
+publish so the bundled references match what the rest of the repo ships.
+
+## License
+
+[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) - same as the parent
+skill. Credit OptimNow.

cloud_finops_mcp-1.21.0/README.md

@@ -0,0 +1,187 @@
+# cloud-finops-mcp
+
+MCP server exposing the [OptimNow Cloud FinOps skill](https://github.com/OptimNow/cloud-finops-skills)
+(28 reference files + 15 named-pattern playbooks) as queryable tools for any
+MCP-aware client (Claude Code, Cursor, Codex CLI, Windsurf, Aider, Cline, etc.).
+
+The skill itself ships in canonical Claude Agent-Skills format and is also installable
+via the cross-tool installer (`./install.sh`) for direct context injection. This MCP
+server is the **enrichment path**: instead of loading the full skill into the
+prompt, the agent calls tools to discover, filter, and fetch only what it needs.
+
+## What the server exposes
+
+Six tools, all read-only, split across two surfaces.
+
+**References** — long-form provider and discipline files (~300-500 lines each):
+
+| Tool | Purpose |
+|---|---|
+| `list_references()` | List all 28 references with their FCP metadata. |
+| `get_reference(name)` | Fetch the full markdown body of one reference. |
+| `find_references(domain?, capability?, phase?, persona?, maturity?)` | Faceted query over the FinOps Capability/Phase frontmatter. |
+
+The reference faceted query supports any combination of:
+
+- `domain` - FinOps Framework domain (e.g. `Optimize Usage & Cost`, `Quantify Business Value`)
+- `capability` - FinOps capability (matches both primary and secondary)
+- `phase` - `Inform`, `Optimize`, `Operate`
+- `persona` - matches both primary and collaborating personas
+- `maturity` - `Crawl`, `Walk`, `Run`
+
+**Playbooks** — small named-pattern runbooks (~80-130 lines each):
+
+| Tool | Purpose |
+|---|---|
+| `list_playbooks()` | List all 15 named-pattern playbooks with their metadata. |
+| `get_playbook(name)` | Fetch the full markdown body of one playbook. |
+| `find_playbooks(scope?, service?, waste_category?, confidence?)` | Faceted query over the playbook frontmatter. |
+
+The playbook faceted query supports:
+
+- `scope` - `aws`, `azure`, `gcp`, or `cross-cloud`
+- `service` - provider service (e.g. `AWS NAT Gateway`); exact-match
+- `waste_category` - `orphaned`, `idle`, `overprovisioned`, `commitment-mismatch`,
+  `schedule-blindness`, `modernization`, `ai-ml-inefficiency`, `egress`
+- `confidence` - `obvious`, `likely`, `possible` (OptimNow three-tier model)
+
+All filters across both surfaces AND together. String matches are case-insensitive
+and exact (no substring matching).
+
+**When to use which surface:**
+
+- A **playbook** answers *"how do I detect/fix this specific pattern?"* (zombie NAT,
+  snapshot sprawl, idle ELB). It includes problem statement, symptoms, a detection
+  query (CUR / KQL / BigQuery SQL / CLI), fix steps, and the anti-pattern.
+- A **reference** answers anything broader: billing mechanics, commitment strategy,
+  allocation methodology, persona-specific framings, or cross-pattern reasoning.
+
+## Install
+
+```bash
+pip install cloud-finops-mcp
+```
+
+Or run without installing via [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+uvx cloud-finops-mcp
+```
+
+## Configure your MCP client
+
+After install, point your client at the `cloud-finops-mcp` console script.
+
+### Claude Code
+
+Project-level (`.mcp.json` at the repo root) or user-level (`~/.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "cloud-finops": {
+      "command": "cloud-finops-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Code, then run `/mcp` to confirm the server is connected.
+
+### Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cloud-finops": {
+      "command": "cloud-finops-mcp"
+    }
+  }
+}
+```
+
+### Codex CLI
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.cloud-finops]
+command = "cloud-finops-mcp"
+```
+
+### Windsurf
+
+`~/.windsurf/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cloud-finops": {
+      "command": "cloud-finops-mcp"
+    }
+  }
+}
+```
+
+### Any other MCP client
+
+The server speaks MCP over stdio. Point any compatible client at `cloud-finops-mcp`
+(or `python -m cloud_finops_mcp`).
+
+## Example tool calls
+
+Agent prompt: *"Use the cloud-finops MCP to find references for the Optimize phase
+aimed at Engineering."*
+
+Calls `find_references(phase="Optimize", persona="Engineering")` and gets back the
+filtered subset (AWS, Azure, GCP, Bedrock, Databricks, etc.) without loading the full
+skill into the prompt.
+
+Agent prompt: *"Pull the AWS reference."*
+
+Calls `get_reference(name="finops-aws")` and gets back the full markdown body
+(~300 lines) instead of the entire 28-file knowledge base.
+
+Agent prompt: *"Show me the obvious-confidence AWS waste playbooks."*
+
+Calls `find_playbooks(scope="aws", confidence="obvious")` and gets back the list
+of high-signal AWS patterns (zombie NAT gateway, orphaned EBS volumes, etc.).
+
+Agent prompt: *"Walk me through the zombie NAT gateway pattern."*
+
+Calls `get_playbook(name="aws-zombie-nat-gateway")` and gets back the ~90-line
+runbook (problem, symptoms, detection query, fix, anti-pattern, see-also).
+
+## When to use this vs the installer
+
+| If you... | Use |
+|---|---|
+| Want the skill loaded as static context for every chat | The cross-tool installer (`./install.sh`) |
+| Have a big-codebase session with limited context budget | The MCP server (fetch on demand) |
+| Want to filter references by FinOps domain/capability/phase/persona/maturity | The MCP server (`find_references`) |
+| Use a client that doesn't support MCP | The cross-tool installer |
+
+The two paths are complementary. You can install both.
+
+## Development
+
+```bash
+git clone https://github.com/OptimNow/cloud-finops-skills.git
+cd cloud-finops-skills/mcp_server
+python scripts/sync_references.py        # populate src/cloud_finops_mcp/data/
+pip install -e ".[dev]"
+pytest
+```
+
+## Versioning
+
+The PyPI package version tracks the skill release tag. Tagging `v1.13` on the
+parent repo triggers both the skill release zip and a new `cloud-finops-mcp` PyPI
+publish so the bundled references match what the rest of the repo ships.
+
+## License
+
+[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) - same as the parent
+skill. Credit OptimNow.

cloud_finops_mcp-1.21.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["hatchling>=1.18", "hatch-build-scripts>=0.0.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cloud-finops-mcp"
+version = "1.21.0"
+description = "MCP server exposing the OptimNow Cloud FinOps skill (28 references) as queryable tools."
+readme = "README.md"
+license = { text = "CC-BY-SA-4.0" }
+authors = [
+  { name = "OptimNow", email = "contact@optimnow.io" }
+]
+maintainers = [
+  { name = "Jean Latière", email = "j.latiere@gmail.com" }
+]
+requires-python = ">=3.10"
+keywords = ["finops", "cloud", "cost", "mcp", "claude", "aws", "azure", "gcp"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Information Technology",
+  "License :: OSI Approved",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "mcp>=1.0.0",
+  "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.4",
+  "pytest-asyncio>=0.23",
+  "ruff>=0.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/OptimNow/cloud-finops-skills"
+Repository = "https://github.com/OptimNow/cloud-finops-skills"
+Issues = "https://github.com/OptimNow/cloud-finops-skills/issues"
+Documentation = "https://github.com/OptimNow/cloud-finops-skills/tree/main/mcp_server"
+
+[project.scripts]
+cloud-finops-mcp = "cloud_finops_mcp.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cloud_finops_mcp"]
+# .md files in src/cloud_finops_mcp/data/ are gitignored but live in the
+# package directory; hatch picks them up via the package walk, no
+# force-include needed.
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/cloud_finops_mcp",
+  "scripts",
+  "tests",
+  "README.md",
+  "pyproject.toml",
+]
+# Force-include the synced reference bundle so the sdist is self-contained -
+# without this, hatch respects ../../.gitignore and drops src/.../data/*.md.
+[tool.hatch.build.targets.sdist.force-include]
+"src/cloud_finops_mcp/data" = "src/cloud_finops_mcp/data"
+
+[[tool.hatch.build.hooks.build-scripts.scripts]]
+out_dir = "src/cloud_finops_mcp/data"
+commands = ["python scripts/sync_references.py"]
+artifacts = []
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]
+ignore = ["E501"]

cloud_finops_mcp-1.21.0/scripts/sync_references.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Copy ``cloud-finops/references/*.md`` and ``cloud-finops/playbooks/*.md`` into
+the bundled ``data/`` folder.
+
+Runs automatically before each wheel build (declared in ``pyproject.toml`` as a
+``hatch-build-scripts`` hook). Also intended to be run manually after
+``pip install -e .`` so the editable install picks up the latest reference
+content::
+
+    python scripts/sync_references.py
+
+The script is idempotent and clears the destination folders first to drop
+files that have been removed upstream. The ``playbooks/README.md`` file is
+intentionally skipped: it documents the format for human contributors and is
+not a runbook the agent should retrieve.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+REFERENCES_SRC = REPO_ROOT / "cloud-finops" / "references"
+PLAYBOOKS_SRC = REPO_ROOT / "cloud-finops" / "playbooks"
+
+DATA_ROOT = Path(__file__).resolve().parents[1] / "src" / "cloud_finops_mcp" / "data"
+REFERENCES_DEST = DATA_ROOT
+PLAYBOOKS_DEST = DATA_ROOT / "playbooks"
+
+
+def _sync(label: str, src_dir: Path, dest_dir: Path, *, skip: set[str]) -> int:
+    """Mirror ``*.md`` from ``src_dir`` into ``dest_dir``.
+
+    Returns the number of files copied. Falls back gracefully when ``src_dir`` is
+    missing (sdist-build case) but ``dest_dir`` is already populated.
+    """
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    existing = [p for p in dest_dir.glob("*.md")]
+
+    if not src_dir.is_dir():
+        if existing:
+            print(
+                f"[sync_references] {label}: source missing; using "
+                f"{len(existing)} pre-bundled file(s) at {dest_dir}"
+            )
+            return len(existing)
+        print(
+            f"[sync_references] {label}: source directory not found and no "
+            f"pre-bundled files present: {src_dir}",
+            file=sys.stderr,
+        )
+        return -1
+
+    # Wipe stale .md files so deletions upstream propagate to the bundle.
+    for stale in existing:
+        stale.unlink()
+
+    copied = 0
+    for src in sorted(src_dir.glob("*.md")):
+        if src.name in skip:
+            continue
+        shutil.copy2(src, dest_dir / src.name)
+        copied += 1
+
+    print(f"[sync_references] {label}: copied {copied} file(s) to {dest_dir}")
+    return copied
+
+
+def main() -> int:
+    refs = _sync("references", REFERENCES_SRC, REFERENCES_DEST, skip=set())
+    playbooks = _sync(
+        "playbooks", PLAYBOOKS_SRC, PLAYBOOKS_DEST, skip={"README.md"}
+    )
+
+    if refs < 0:
+        return 1
+    if playbooks < 0:
+        # Playbooks are optional - older skill versions may not have shipped
+        # them. Warn but do not fail the build.
+        print(
+            "[sync_references] WARNING: playbooks unavailable; the MCP "
+            "server will still expose references but list_playbooks() will "
+            "be empty.",
+            file=sys.stderr,
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cloud_finops_mcp-1.21.0/src/cloud_finops_mcp/__init__.py

@@ -0,0 +1,14 @@
+"""Cloud FinOps MCP server.
+
+Exposes the OptimNow Cloud FinOps skill (28 references) as queryable tools
+via the Model Context Protocol.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("cloud-finops-mcp")
+except PackageNotFoundError:  # pragma: no cover - editable / not installed
+    __version__ = "0.0.0+dev"
+
+__all__ = ["__version__"]

cloud_finops_mcp-1.21.0/src/cloud_finops_mcp/__main__.py

@@ -0,0 +1,16 @@
+"""Entry point: ``python -m cloud_finops_mcp`` and ``cloud-finops-mcp`` console script."""
+
+from __future__ import annotations
+
+import asyncio
+
+from .server import run
+
+
+def main() -> None:
+    """Synchronous wrapper used by the console-script entry point."""
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    main()

cloud_finops_mcp-1.21.0/src/cloud_finops_mcp/data/.gitignore

@@ -0,0 +1,3 @@
+# Bundled reference content is generated by scripts/sync_references.py.
+# Source of truth lives at ../../../cloud-finops/references/.
+*.md