Metadata-Version: 2.4
Name: ict-mcp-server
Version: 0.5.1
Summary: MCP server for generating, validating, and deploying AWS CDK — delegates to AWS MCP servers
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: boto3>=1.35.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: starlette>=0.38.0
Requires-Dist: uvicorn>=0.30.0
Description-Content-Type: text/markdown

# cdk-agent-mcp-server

MCP server that generates, validates, and deploys AWS CDK infrastructure from natural language.

Delegates to AWS MCP servers for validation, documentation, and pricing — no duplicate tooling.

## Architecture

```
cdk-agent-mcp-server (stdio)
  ├── clarify_requirements    → Bedrock (requirements gathering before design)
  ├── design_architecture     → AWS IaC MCP (search_cdk_documentation)
  ├── confirm_plan            → Bedrock (human/agent approval gate)
  ├── generate_cdk_stack      → AWS IaC MCP (search_cdk_documentation + search_cdk_samples_and_constructs)
  ├── validate_and_repair     → real cdk synth + AWS IaC MCP (validate_cloudformation_template + check_cloudformation_template_compliance)
  ├── estimate_cost           → AWS Pricing MCP (get_pricing + generate_cost_report)
  ├── lookup_cdk_construct    → AWS IaC MCP (search_cdk_documentation + search_cdk_samples_and_constructs + cdk_best_practices)
  ├── troubleshoot_deployment → AWS IaC MCP (troubleshoot_cloudformation_deployment)
  ├── deploy_stack            → real cdk deploy (requires approved=true)
  ├── destroy_stack           → CloudFormation DeleteStack (requires approved=true)
  ├── generate_diagram        → local Mermaid generation
  └── full_pipeline           → orchestrates all of the above
```

### HITL (Human-in-the-Loop) Flow

```
User/Agent describes intent
       │
       ▼
clarify_requirements  →  returns structured questions + defaults
       │
       ▼
User/Agent answers (or accepts defaults)
       │
       ▼
design_architecture   →  generates plan using enriched context
       │
       ▼
confirm_plan          →  summarizes plan for approval (services, cost tier, security)
       │
       ▼
User/Agent approves (or modifies)
       │
       ▼
generate_cdk_stack → validate_and_repair → estimate_cost → deploy_stack
```

## Prerequisites

- Python 3.10+, Node.js 18+ (for cdk synth/deploy), `uv` installed
- AWS CLI configured, Bedrock Claude Sonnet 4 enabled

## Install

```json
{
  "mcpServers": {
    "ict-mcp-server": {
      "command": "uvx",
      "args": ["ict-mcp-server"],
      "env": { "AWS_REGION": "us-east-1" }
    }
  }
}
```

Works with Kiro (`~/.kiro/settings/mcp.json`), Cursor (`.cursor/mcp.json`), Claude Code (`claude mcp add`), Amazon Quick Desktop (Settings → Capabilities → MCP).

## Agent

| Task | Delegates To | What It Does |
|------|-------------|-------------|
| `clarify_requirements` | Bedrock + Knowledge MCP | NL → structured clarifying questions with defaults |
| `full_pipeline` | All below | End-to-end: describe → clarify → plan → confirm → diagram → CDK → validate → costs |
| `design_architecture` | IaC MCP `search_cdk_documentation` | NL + requirements → architecture plan JSON |
| `confirm_plan` | Bedrock | Plan → human-readable summary for approval |
| `generate_cdk_stack` | IaC MCP `search_cdk_documentation` + `search_cdk_samples_and_constructs` | Plan → CDK TypeScript |
| `validate_and_repair` | `cdk synth` + IaC MCP `validate_cloudformation_template` + `check_cloudformation_template_compliance` | Validate + auto-repair loop |
| `estimate_cost` | Pricing MCP `get_pricing` + `generate_cost_report` | Real AWS pricing data |
| `lookup_cdk_construct` | IaC MCP `search_cdk_documentation` + `search_cdk_samples_and_constructs` + `cdk_best_practices` | CDK docs + samples + best practices |
| `deploy_stack` | `cdk deploy` | Real deployment (requires `approved=true`) |
| `destroy_stack` | CloudFormation `DeleteStack` | Delete stack (requires `approved=true`) |
| `troubleshoot_deployment` | IaC MCP `troubleshoot_cloudformation_deployment` | Root cause analysis for failed deploys |
| `generate_diagram` | Local | Architecture plan → Mermaid diagram |

## What We Don't Reimplement

| Capability | Provided By |
|-----------|-------------|
| cfn-lint (template validation) | AWS IaC MCP Server |
| cfn-guard (compliance checking) | AWS IaC MCP Server |
| CDK documentation search | AWS IaC MCP Server |
| CDK code samples | AWS IaC MCP Server |
| CDK best practices | AWS IaC MCP Server |
| Deployment troubleshooting | AWS IaC MCP Server |
| AWS service pricing | AWS Pricing MCP Server |
| Cost report generation | AWS Pricing MCP Server |

Our server only implements: architecture planning (Bedrock), CDK code generation (Bedrock), Mermaid diagrams (local), cdk synth/deploy (subprocess), and the orchestration glue.
