Metadata-Version: 2.4
Name: base2-mcp
Version: 0.2.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
Requires-Dist: pyyaml>=6.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
```
