base2-mcp 0.1.0__tar.gz

base2_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GH_PAT || github.token }}
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt -r requirements-dev.txt
+
+      - name: Run tests
+        run: pytest tests/ -v

base2_mcp-0.1.0/.github/workflows/publish-test.yml

@@ -0,0 +1,51 @@
+name: Publish to Test PyPI
+
+on:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GH_PAT }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt -r requirements-dev.txt
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GH_PAT }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/simple/

base2_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GH_PAT }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt -r requirements-dev.txt
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GH_PAT }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

base2_mcp-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.env

base2_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: base2-mcp
+Version: 0.1.0
+Summary: MCP server for Base2 open-source AWS tools — documentation, guidance, and CLI execution
+Author: Base2 Services
+License-Expression: MIT
+Keywords: aws,backup,bastion,cloudformation,mcp,monitoring,vpn
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.9.0
+Description-Content-Type: text/markdown
+
+# base2-mcp
+
+MCP server for Base2 open-source AWS tools — documentation, guidance, and CLI execution.
+
+## Supported Tools
+
+| Tool | Description | Install |
+|------|-------------|---------|
+| [cfhighlander](https://github.com/theonestack/cfhighlander) | CloudFormation DSL and component library | `gem install cfhighlander` |
+| [shelvery](https://github.com/base2Services/shelvery-aws-backups) | Automated AWS backups (EBS, RDS, EC2, Redshift, DocumentDB) | `pip install shelvery` |
+| [cfn-guardian](https://github.com/base2Services/cfn-guardian) | CloudWatch alarm management via CloudFormation | `gem install cfn-guardian` |
+| [monitorable](https://github.com/base2Services/monitorable) | CloudWatch alarm coverage auditing | Clone repo |
+| [cfn-vpn](https://github.com/base2Services/cfn-vpn) | AWS Client VPN management via CloudFormation | `gem install cfn-vpn` |
+| [bastion-cli](https://github.com/base2Services/bastion-cli) | Temporary bastion EC2 instances via Session Manager | [GitHub releases](https://github.com/base2Services/bastion-cli/releases) |
+
+## Quick Start
+
+### Cursor IDE (Recommended)
+
+Add to your `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "base2": {
+      "command": "uvx",
+      "args": ["--upgrade", "base2-mcp"]
+    }
+  }
+}
+```
+
+No manual install needed — `uvx` fetches the package from PyPI automatically and `--upgrade` ensures you always get the latest version on server restart.
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "base2": {
+      "command": "uvx",
+      "args": ["--upgrade", "base2-mcp"]
+    }
+  }
+}
+```
+
+### Alternative: pin to a specific version
+
+If you need a stable version that won't change unexpectedly:
+
+```json
+{
+  "mcpServers": {
+    "base2": {
+      "command": "uvx",
+      "args": ["base2-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+### Prerequisite: uv
+
+`uvx` is part of [uv](https://docs.astral.sh/uv/), a fast Python package manager. Install it with:
+
+```bash
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# Or via pip
+pip install uv
+```
+
+## What It Does
+
+This MCP server gives AI agents two capabilities for each tool:
+
+1. **Documentation** — Embedded docs with CLI usage, configuration, examples, and best practices. The agent can read these to understand any tool without you explaining it.
+
+2. **CLI Execution** — Wrapper tools that run the actual CLI commands (`cfhighlander cfcompile`, `shelvery ebs create_backups`, `bastion launch`, etc.) and return structured output.
+
+### Available MCP Tools
+
+**Discovery:**
+- `list_base2_tools` — Overview of all 6 tools
+- `get_tool_docs` — Detailed documentation for a specific tool
+
+**cfhighlander:**
+- `cfhighlander_docs` / `cfhighlander_compile` / `cfhighlander_publish` / `cfhighlander_test` / `cfhighlander_validate`
+
+**shelvery:**
+- `shelvery_docs` / `shelvery_create_backups` / `shelvery_clean_backups` / `shelvery_pull_shared_backups`
+
+**cfn-guardian:**
+- `guardian_docs` / `guardian_compile` / `guardian_deploy` / `guardian_show_alarms` / `guardian_show_resources`
+
+**monitorable:**
+- `monitorable_docs` / `monitorable_audit`
+
+**cfn-vpn:**
+- `cfn_vpn_docs` / `cfn_vpn_init` / `cfn_vpn_modify` / `cfn_vpn_routes` / `cfn_vpn_sessions`
+
+**bastion-cli:**
+- `bastion_docs` / `bastion_launch` / `bastion_connect` / `bastion_terminate` / `bastion_port_forward`
+
+## Prerequisites
+
+The MCP server itself only needs Python 3.11+ and the `mcp` package. The CLI tools it wraps need to be installed separately — the server will tell the agent if a tool is missing and how to install it.
+
+## Development
+
+```bash
+# Install dependencies
+pip install -r requirements.txt -r requirements-dev.txt
+
+# Run tests
+pytest tests/ -v
+
+# Run the server locally (stdio mode)
+python src/app.py
+```
+
+## Architecture
+
+```
+base2-mcp/
+├── src/
+│   ├── app.py                    # FastMCP entry point (stdio transport)
+│   ├── docs/                     # Embedded markdown documentation
+│   │   ├── __init__.py           # Doc loader utility
+│   │   ├── cfhighlander.md
+│   │   ├── shelvery.md
+│   │   ├── guardian.md
+│   │   ├── monitorable.md
+│   │   ├── cfn_vpn.md
+│   │   └── bastion.md
+│   ├── executor/
+│   │   └── cli_runner.py         # Shared subprocess executor
+│   └── tools/                    # One module per tool
+│       ├── overview_tools.py     # list_base2_tools, get_tool_docs
+│       ├── cfhighlander_tools.py
+│       ├── shelvery_tools.py
+│       ├── guardian_tools.py
+│       ├── monitorable_tools.py
+│       ├── cfn_vpn_tools.py
+│       └── bastion_tools.py
+├── tests/                        # pytest suite (56 tests)
+├── pyproject.toml
+├── requirements.txt
+└── requirements-dev.txt
+```

base2_mcp-0.1.0/README.md

@@ -0,0 +1,157 @@
+# base2-mcp
+
+MCP server for Base2 open-source AWS tools — documentation, guidance, and CLI execution.
+
+## Supported Tools
+
+| Tool | Description | Install |
+|------|-------------|---------|
+| [cfhighlander](https://github.com/theonestack/cfhighlander) | CloudFormation DSL and component library | `gem install cfhighlander` |
+| [shelvery](https://github.com/base2Services/shelvery-aws-backups) | Automated AWS backups (EBS, RDS, EC2, Redshift, DocumentDB) | `pip install shelvery` |
+| [cfn-guardian](https://github.com/base2Services/cfn-guardian) | CloudWatch alarm management via CloudFormation | `gem install cfn-guardian` |
+| [monitorable](https://github.com/base2Services/monitorable) | CloudWatch alarm coverage auditing | Clone repo |
+| [cfn-vpn](https://github.com/base2Services/cfn-vpn) | AWS Client VPN management via CloudFormation | `gem install cfn-vpn` |
+| [bastion-cli](https://github.com/base2Services/bastion-cli) | Temporary bastion EC2 instances via Session Manager | [GitHub releases](https://github.com/base2Services/bastion-cli/releases) |
+
+## Quick Start
+
+### Cursor IDE (Recommended)
+
+Add to your `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "base2": {
+      "command": "uvx",
+      "args": ["--upgrade", "base2-mcp"]
+    }
+  }
+}
+```
+
+No manual install needed — `uvx` fetches the package from PyPI automatically and `--upgrade` ensures you always get the latest version on server restart.
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "base2": {
+      "command": "uvx",
+      "args": ["--upgrade", "base2-mcp"]
+    }
+  }
+}
+```
+
+### Alternative: pin to a specific version
+
+If you need a stable version that won't change unexpectedly:
+
+```json
+{
+  "mcpServers": {
+    "base2": {
+      "command": "uvx",
+      "args": ["base2-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+### Prerequisite: uv
+
+`uvx` is part of [uv](https://docs.astral.sh/uv/), a fast Python package manager. Install it with:
+
+```bash
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# Or via pip
+pip install uv
+```
+
+## What It Does
+
+This MCP server gives AI agents two capabilities for each tool:
+
+1. **Documentation** — Embedded docs with CLI usage, configuration, examples, and best practices. The agent can read these to understand any tool without you explaining it.
+
+2. **CLI Execution** — Wrapper tools that run the actual CLI commands (`cfhighlander cfcompile`, `shelvery ebs create_backups`, `bastion launch`, etc.) and return structured output.
+
+### Available MCP Tools
+
+**Discovery:**
+- `list_base2_tools` — Overview of all 6 tools
+- `get_tool_docs` — Detailed documentation for a specific tool
+
+**cfhighlander:**
+- `cfhighlander_docs` / `cfhighlander_compile` / `cfhighlander_publish` / `cfhighlander_test` / `cfhighlander_validate`
+
+**shelvery:**
+- `shelvery_docs` / `shelvery_create_backups` / `shelvery_clean_backups` / `shelvery_pull_shared_backups`
+
+**cfn-guardian:**
+- `guardian_docs` / `guardian_compile` / `guardian_deploy` / `guardian_show_alarms` / `guardian_show_resources`
+
+**monitorable:**
+- `monitorable_docs` / `monitorable_audit`
+
+**cfn-vpn:**
+- `cfn_vpn_docs` / `cfn_vpn_init` / `cfn_vpn_modify` / `cfn_vpn_routes` / `cfn_vpn_sessions`
+
+**bastion-cli:**
+- `bastion_docs` / `bastion_launch` / `bastion_connect` / `bastion_terminate` / `bastion_port_forward`
+
+## Prerequisites
+
+The MCP server itself only needs Python 3.11+ and the `mcp` package. The CLI tools it wraps need to be installed separately — the server will tell the agent if a tool is missing and how to install it.
+
+## Development
+
+```bash
+# Install dependencies
+pip install -r requirements.txt -r requirements-dev.txt
+
+# Run tests
+pytest tests/ -v
+
+# Run the server locally (stdio mode)
+python src/app.py
+```
+
+## Architecture
+
+```
+base2-mcp/
+├── src/
+│   ├── app.py                    # FastMCP entry point (stdio transport)
+│   ├── docs/                     # Embedded markdown documentation
+│   │   ├── __init__.py           # Doc loader utility
+│   │   ├── cfhighlander.md
+│   │   ├── shelvery.md
+│   │   ├── guardian.md
+│   │   ├── monitorable.md
+│   │   ├── cfn_vpn.md
+│   │   └── bastion.md
+│   ├── executor/
+│   │   └── cli_runner.py         # Shared subprocess executor
+│   └── tools/                    # One module per tool
+│       ├── overview_tools.py     # list_base2_tools, get_tool_docs
+│       ├── cfhighlander_tools.py
+│       ├── shelvery_tools.py
+│       ├── guardian_tools.py
+│       ├── monitorable_tools.py
+│       ├── cfn_vpn_tools.py
+│       └── bastion_tools.py
+├── tests/                        # pytest suite (56 tests)
+├── pyproject.toml
+├── requirements.txt
+└── requirements-dev.txt
+```

base2_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "base2-mcp"
+version = "0.1.0"
+description = "MCP server for Base2 open-source AWS tools — documentation, guidance, and CLI execution"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Base2 Services" }]
+keywords = ["mcp", "aws", "cloudformation", "backup", "monitoring", "vpn", "bastion"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "mcp[cli]>=1.9.0",
+]
+
+[project.scripts]
+base2-mcp = "app:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+sources = ["src"]
+artifacts = ["*.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

base2_mcp-0.1.0/requirements-dev.txt

@@ -0,0 +1,2 @@
+pytest>=8.0.0
+pytest-asyncio>=0.25.0

base2_mcp-0.1.0/requirements.txt

@@ -0,0 +1 @@
+mcp[cli]>=1.9.0

base2_mcp-0.1.0/src/app.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import logging
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+from tools.overview_tools import register_overview_tools
+from tools.cfhighlander_tools import register_cfhighlander_tools
+from tools.shelvery_tools import register_shelvery_tools
+from tools.guardian_tools import register_guardian_tools
+from tools.monitorable_tools import register_monitorable_tools
+from tools.cfn_vpn_tools import register_cfn_vpn_tools
+from tools.bastion_tools import register_bastion_tools
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(name)s %(levelname)s %(message)s",
+    stream=sys.stderr,
+)
+logger = logging.getLogger(__name__)
+
+mcp = FastMCP(
+    name="base2-mcp",
+    instructions=(
+        "Base2 MCP Server — documentation, guidance, and CLI execution for "
+        "Base2 open-source AWS tools.\n\n"
+        "Supported tools:\n"
+        "- **cfhighlander**: CloudFormation DSL and component library\n"
+        "- **shelvery**: Automated AWS backups (EBS, RDS, EC2, Redshift, DocumentDB)\n"
+        "- **cfn-guardian**: CloudWatch alarm management via CloudFormation\n"
+        "- **monitorable**: CloudWatch alarm coverage auditing\n"
+        "- **cfn-vpn**: AWS Client VPN management via CloudFormation\n"
+        "- **bastion-cli**: Temporary bastion EC2 instances via Session Manager\n\n"
+        "Start with 'list_base2_tools' for an overview of all tools, or "
+        "'get_tool_docs' to read detailed documentation for a specific tool."
+    ),
+)
+
+register_overview_tools(mcp)
+register_cfhighlander_tools(mcp)
+register_shelvery_tools(mcp)
+register_guardian_tools(mcp)
+register_monitorable_tools(mcp)
+register_cfn_vpn_tools(mcp)
+register_bastion_tools(mcp)
+
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

base2_mcp-0.1.0/src/docs/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+DOCS_DIR = Path(__file__).parent
+
+ToolName = Literal[
+    "cfhighlander",
+    "shelvery",
+    "guardian",
+    "monitorable",
+    "cfn_vpn",
+    "bastion",
+]
+
+TOOL_DOC_FILES: dict[ToolName, str] = {
+    "cfhighlander": "cfhighlander.md",
+    "shelvery": "shelvery.md",
+    "guardian": "guardian.md",
+    "monitorable": "monitorable.md",
+    "cfn_vpn": "cfn_vpn.md",
+    "bastion": "bastion.md",
+}
+
+
+def load_doc(tool: ToolName) -> str:
+    """Load the embedded markdown documentation for a tool."""
+    filename = TOOL_DOC_FILES[tool]
+    return (DOCS_DIR / filename).read_text()