# cfn-lint MCP Server (POC)

Validate AWS CloudFormation templates via cfn-lint exposed as MCP tools.

## Installation

```bash
# Clone repository
git clone <repository-url>
cd cfn-lint-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .
```

## Claude Desktop Configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cfn-lint": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "--directory",
        "[YOUR DIRECTORY TO THE MPC SERVER]",
        "run",
        "-m",
        "cfnlintmcp.server"
      ],
      "env": {
        "GITHUB_TOKEN": "optional_token_here"
      }
    }
  }
}
```

## Run Standalone

```bash
# Using uv (recommended)
uv --directory /Users/brianterry/Documents/repos/guard-mcp run -m cfnlintmcp.server

# Using python directly
python -m cfnlintmcp.server
```

## Testing

```bash
pytest -q
```

## How it works

- The server implements the MCP protocol over stdio and is launched by your MCP host (e.g., Claude Desktop).
- On startup, it performs a one-time GitHub check for the latest `cfn-lint` release and caches the result in memory.
- It exposes MCP tools to validate CloudFormation templates and inspect version info. A dedicated upgrade tool lets the host (LLM) ask users for consent and then update `cfn-lint` automatically.
- Validation uses `cfnlint.api.lint` against in-memory template content; results are returned as structured JSON including rule metadata and locations.

### Available tools

- validate_cloudformation_template
  - Input: { "template_content": string, "regions"?: string[], "ignore_checks"?: string[] }
  - Output: { "valid": boolean, "cfn_lint_version": string, "matches": Match[] }

- validate_with_guard
  - Input: { "template_content": string, "rules"?: string }
  - Output: Guard result dict (success, matches, guard_version, etc.)
  - Notes: Uses the `guardpycfn` package when installed; otherwise returns a helpful error. Install via:
    ```bash
    pip install guardpycfn
    ```
    PyPI: [guardpycfn](https://pypi.org/project/guardpycfn/)

- get_server_info
  - Input: {}
  - Output: { "server_version", "cfn_lint_version", "mcp_protocol_version", "latest_cfn_lint_version", "upgrade_available", "last_version_check" }

- upgrade_cfn_lint
  - Input: { "prefer_uv"?: boolean }
  - Output: { "status": "SUCCESS"|"NOOP"|"FAILED", "before_version", "after_version", "used_command", "message", "restart_required", "logs" }

## Example: validate a template

Request (JSON-RPC sent by MCP host):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "validate_cloudformation_template",
    "arguments": {
      "template_content": "AWSTemplateFormatVersion: '2010-09-09'\nResources:\n  MyBucket:\n    Type: AWS::S3::Bucket\n",
      "regions": ["us-east-1"],
      "ignore_checks": []
    }
  }
}
```

Response (text content contains JSON):

```json
{
  "valid": true,
  "cfn_lint_version": "1.40.1",
  "matches": []
}
```

Example invalid response (truncated):

```json
{
  "valid": false,
  "cfn_lint_version": "1.40.1",
  "matches": [
    {
      "rule": {
        "id": "E3030",
        "shortdesc": "Check if properties have a valid value",
        "description": "Check if properties have a valid value in case of an enumator"
      },
      "message": "'invalid.type' is not one of [...]",
      "location": {
        "path": ["Resources", "MyInstance", "Properties", "InstanceType"],
        "start": { "line": 7, "column": 7 },
        "end": { "line": 7, "column": 19 }
      },
      "level": "error"
    }
  ]
}
```

## Example: get server info

```json
{
  "server_version": "0.1.0",
  "cfn_lint_version": "1.40.1",
  "mcp_protocol_version": "2024-11-05",
  "latest_cfn_lint_version": "1.40.1",
  "upgrade_available": false,
  "last_version_check": "2025-10-10T14:30:00Z"
}
```

## Example: upgrade cfn-lint via MCP

1) Host (LLM) prompts the user: "A new version of cfn-lint is available (1.41.0). Update now?"
2) On consent, host calls the tool:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "upgrade_cfn_lint",
    "arguments": { "prefer_uv": true }
  }
}
```

Possible result:

```json
{
  "status": "SUCCESS",
  "before_version": "1.40.1",
  "after_version": "1.41.0",
  "used_command": ["/opt/homebrew/bin/uv", "pip", "install", "-U", "cfn-lint"],
  "message": "cfn-lint upgraded",
  "restart_required": true,
  "logs": ["..."]
}
```

Note: The server does not restart itself; your MCP host should restart or relaunch the server to load the new version.

## Using with an LLM (Claude Desktop example)

Once configured in Claude Desktop (see configuration above), you can just talk to the LLM naturally. The LLM will decide when to call the MCP tools.

### Validate a template inline

You: "Validate this CloudFormation template in us-east-1" and paste your template.

The LLM will call `validate_cloudformation_template` with your pasted content and return structured findings (rule IDs, messages, and line/column ranges). If there are no matches, the template is valid for the given rules and region.

### Check server and cfn-lint versions

You: "What version of cfn-lint is the server using?"

The LLM will call `get_server_info` and summarize `cfn_lint_version`, `latest_cfn_lint_version`, and whether an upgrade is available.

### Offer and perform an upgrade (opt-in)

If a newer cfn-lint version is detected, the LLM can ask: "A new cfn-lint version is available (X.Y.Z). Would you like me to upgrade now?"

- If you say "Yes": the LLM calls `upgrade_cfn_lint` (optionally with `prefer_uv=true`). The tool upgrades cfn-lint in the running environment and returns the before/after versions and logs.
- After a successful upgrade, the LLM will instruct you (or your host) to restart the MCP server so the new version is loaded.

### Example prompts

- "Validate this CloudFormation template for us-west-2 and ignore W2001"
- "Show me the cfn-lint version and whether an upgrade is available"
- "Upgrade cfn-lint and then re-validate my template"

## Environment Variables

- `GITHUB_TOKEN` (optional): Raise GitHub API limits for version checks.
- `CFN_LINT_MCP_LOG_LEVEL` (optional): Logging level (default: `INFO`).