# Ship CLI - MCP (Model Context Protocol) Server

Ship CLI provides an MCP server that exposes 7 powerful Terraform analysis tools for AI assistants like Claude Code, Cursor, and other MCP-compatible clients.

## Quick Start

1. **Start the MCP Server**:
   ```bash
   ship mcp
   ```

2. **Configure in Claude Code** (add to `~/.config/claude-code/claude_desktop_config.json`):
   ```json
   {
     "mcpServers": {
       "ship-cli": {
         "command": "/path/to/ship",
         "args": ["mcp"]
       }
     }
   }
   ```

3. **Use the tools** in your AI assistant conversations

## Available MCP Tools

### 1. terraform_lint
**Description**: Run TFLint on Terraform code to check for syntax errors and best practices
**Parameters**:
- `directory` (optional): Directory containing Terraform files (default: current directory)  
- `format` (optional): Output format: default, json, compact
- `output` (optional): Output file to save lint results

**Example Usage**:
```javascript
terraform_lint({
  directory: "./examples/aws-web-app",
  format: "json"
})
```

### 2. terraform_checkov_scan
**Description**: Run Checkov security scan on Terraform code for policy compliance
**Parameters**:
- `directory` (optional): Directory containing Terraform files (default: current directory)
- `format` (optional): Output format: cli, json, junit, sarif
- `output` (optional): Output file to save scan results

**Example Usage**:
```javascript
terraform_checkov_scan({
  directory: "./examples/security-hardened",
  format: "json"
})
```

### 3. terraform_security_scan
**Description**: Run alternative security scan on Terraform code using Trivy
**Parameters**:
- `directory` (optional): Directory containing Terraform files (default: current directory)

**Example Usage**:
```javascript
terraform_security_scan({
  directory: "./examples/aws-web-app"
})
```

### 4. terraform_cost_analysis
**Description**: Analyze infrastructure costs using OpenInfraQuote
**Parameters**:
- `directory` (optional): Directory containing Terraform files (default: current directory)
- `region` (optional): AWS region for pricing (e.g., us-east-1, us-west-2)
- `format` (optional): Output format: json, table
- `output` (optional): Output file to save cost analysis

**Example Usage**:
```javascript
terraform_cost_analysis({
  directory: "./examples/cost-optimized",
  region: "us-east-1",
  format: "json"
})
```

### 5. terraform_generate_docs
**Description**: Generate documentation for Terraform modules using terraform-docs
**Parameters**:
- `directory` (optional): Directory containing Terraform files (default: current directory)
- `filename` (optional): Filename to save documentation as (default README.md)
- `output` (optional): Output file to save documentation

**Example Usage**:
```javascript
terraform_generate_docs({
  directory: "./examples/serverless-api",
  filename: "TERRAFORM.md"
})
```

### 6. terraform_generate_diagram
**Description**: Generate infrastructure diagrams from Terraform state or HCL files
**Parameters**:
- `input` (optional): Input directory or file containing Terraform files (default: current directory)
- `format` (optional): Output format: png, svg, pdf, dot
- `output` (optional): Output file to save diagram
- `hcl` (optional): Generate from HCL files instead of state file (boolean)
- `provider` (optional): Filter by specific provider (aws, google, azurerm)

**Example Usage**:
```javascript
// For Terraform directories (HCL files)
terraform_generate_diagram({
  input: "./examples/aws-web-app",
  format: "png",
  hcl: true,
  output: "infrastructure.png"
})

// For Terraform state files  
terraform_generate_diagram({
  input: "terraform.tfstate",
  format: "svg"
})
```

### 7. cloudship_push
**Description**: Upload and analyze infrastructure artifacts with Cloudship AI
**Parameters**:
- `file` (required): Path to the file to upload (Terraform plan, SBOM, etc.)
- `type` (optional): Type of artifact being uploaded (terraform-plan, sbom, dockerfile, kubernetes-manifest)

**Example Usage**:
```javascript
cloudship_push({
  file: "./terraform.tfplan",
  type: "terraform-plan"
})
```

## Best Practices

### 1. Working with Terraform Directories
Most tools work with Terraform directories. Ensure your directory contains valid `.tf` files:
```javascript
terraform_lint({ directory: "./my-terraform-project" })
```

### 2. Cost Analysis
For accurate cost analysis, specify the correct AWS region:
```javascript
terraform_cost_analysis({
  directory: "./infrastructure",
  region: "us-west-2",
  format: "json"
})
```

### 3. Diagram Generation
- Use `hcl: true` for Terraform directories with `.tf` files
- Use `hcl: false` (default) for Terraform state files
- PNG/SVG formats are best for viewing, DOT format for programmatic processing

### 4. Security Scanning
Combine multiple security tools for comprehensive coverage:
```javascript
// Run both Checkov and Trivy scans
terraform_checkov_scan({ directory: "./project" })
terraform_security_scan({ directory: "./project" })
```

### 5. Documentation Generation
Generate documentation before deploying infrastructure:
```javascript
terraform_generate_docs({
  directory: "./modules/vpc",
  output: "./docs/vpc-module.md"
})
```

## Output Handling

### Large Output Management
The MCP server automatically handles large outputs (>25000 tokens) by:
- Providing summaries of extensive scan results
- Chunking large outputs for better handling
- Suggesting focused queries for detailed analysis

### File Output
All tools support optional `output` parameter to save results to files:
```javascript
terraform_lint({
  directory: "./project",
  format: "json",
  output: "./reports/lint-results.json"
})
```

## Example Workflows

### 1. Complete Infrastructure Analysis
```javascript
// 1. Lint the code
terraform_lint({ directory: "./infrastructure" })

// 2. Run security scans
terraform_checkov_scan({ directory: "./infrastructure" })
terraform_security_scan({ directory: "./infrastructure" })

// 3. Analyze costs
terraform_cost_analysis({ 
  directory: "./infrastructure",
  region: "us-east-1" 
})

// 4. Generate documentation
terraform_generate_docs({ directory: "./infrastructure" })

// 5. Create infrastructure diagram
terraform_generate_diagram({
  input: "./infrastructure",
  hcl: true,
  format: "png"
})
```

### 2. Security-Focused Review
```javascript
// Run comprehensive security analysis
terraform_checkov_scan({
  directory: "./security-critical-app",
  format: "sarif",
  output: "./security-reports/checkov.sarif"
})

terraform_security_scan({
  directory: "./security-critical-app"
})

terraform_lint({
  directory: "./security-critical-app",
  format: "json"
})
```

### 3. Cost Optimization Analysis
```javascript
// Analyze costs across multiple regions
terraform_cost_analysis({
  directory: "./multi-region-app",
  region: "us-east-1",
  format: "json"
})

terraform_cost_analysis({
  directory: "./multi-region-app", 
  region: "us-west-2",
  format: "json"
})
```

## Troubleshooting

### Tool Not Found
If tools fail, ensure:
1. Ship CLI is properly installed and in PATH
2. MCP server is running (`ship mcp`)
3. Your AI assistant is configured to connect to the MCP server

### Large Outputs
If outputs are truncated:
1. Use more specific directory scopes
2. Use filtering options where available
3. Save to files and read them separately

### Terraform Initialization
Some tools require Terraform initialization. Run in your project directory:
```bash
terraform init
```

### Authentication
For CloudShip features, authenticate first:
```bash
ship auth --api-key YOUR_API_KEY
```

## Example Project Structure

Ship CLI includes comprehensive example projects:
- `examples/aws-web-app/` - Full-stack web application
- `examples/serverless-api/` - Serverless API with Lambda
- `examples/security-hardened/` - Security-focused configuration
- `examples/cost-optimized/` - Cost-efficient infrastructure

Test the tools on these examples:
```javascript
terraform_lint({ directory: "./examples/aws-web-app" })
terraform_generate_diagram({ 
  input: "./examples/aws-web-app",
  hcl: true,
  format: "png"
})
```

## Advanced Usage

### Custom Output Formats
Different tools support different output formats:
- **terraform_lint**: default, json, compact
- **terraform_checkov_scan**: cli, json, junit, sarif
- **terraform_cost_analysis**: json, table
- **terraform_generate_diagram**: png, svg, pdf, dot

### Provider-Specific Analysis
Filter infrastructure diagrams by cloud provider:
```javascript
terraform_generate_diagram({
  input: "./multi-cloud-setup",
  hcl: true,
  provider: "aws",
  format: "svg"
})
```

## Resources Available

The MCP server also provides resources:
- `ship://help` - Complete help and usage information
- `ship://tools` - List of all available tools and capabilities

Access these through your AI assistant's resource system.

---

For more information, visit: https://github.com/cloudshipai/ship