# Cost Explorer MCP Server - Agentcore Runtime Deployment

This directory contains the Cost Explorer MCP Server configured for deployment to Amazon Bedrock Agentcore Runtime with streamable HTTP support on port 8000.

## 🏗️ Architecture

- **Original**: STDIO-based MCP server for local development
- **Converted**: Streamable HTTP server for Agentcore Runtime deployment
- **Protocol**: MCP (Model Context Protocol)
- **Transport**: Streamable HTTP on port 8000
- **Deployment**: Agentcore Runtime (no Agentcore memory)

## 📁 Project Structure

```
cost-explorer-agentcore-deployment/
├── mcp_server.py              # Main MCP server with streamable HTTP
├── requirements.txt           # Python dependencies
├── __init__.py               # Python package marker
├── awslabs/                  # Cost Explorer implementation
│   └── cost_explorer_mcp_server/
├── deploy.py                 # Deployment automation script
├── test_mcp_client.py        # Local testing client
├── test_remote_client.py     # Remote testing client
└── README.md                 # This file
```

## 🚀 Quick Start

### 1. Prerequisites

```bash
# Install required tools
pip install bedrock-agentcore-starter-toolkit
pip install mcp[cli]

# Configure AWS credentials
aws configure
```

### 2. Test Locally First

```bash
# Install dependencies
pip install -r requirements.txt

# Start the MCP server locally
python mcp_server.py
```

In another terminal:
```bash
# Test the local server
python test_mcp_client.py
```

### 3. Deploy to Agentcore Runtime

```bash
# Run the deployment script
python deploy.py
```

The script will:
- Check prerequisites
- Configure the deployment
- Deploy to Agentcore Runtime
- Save the Agent ARN to `agent_arn.txt`

### 4. Test Remote Deployment

```bash
# Set environment variables
export AGENT_ARN="your-agent-arn-from-deployment"
export BEARER_TOKEN="your-oauth-token"

# Test the deployed server
python test_remote_client.py
```

## 🔧 Manual Deployment Steps

If you prefer manual deployment:

### 1. Configure Deployment

```bash
agentcore configure -e mcp_server.py --protocol MCP
```

Follow the prompts:
- **Protocol**: MCP
- **Entry point**: mcp_server.py
- **Authentication**: Choose OAuth or Cognito based on your needs

### 2. Deploy

```bash
agentcore launch
```

## 🔐 Authentication Setup

### Option 1: Cognito User Pool (Recommended)

1. Create a Cognito User Pool in AWS Console
2. Configure the user pool for your application
3. Use the provided credentials during deployment configuration

### Option 2: OAuth with Auth0

1. Set up Auth0 application with Dynamic Client Registration
2. Configure OAuth settings during deployment
3. Use Auth0 tokens for authentication

## 🧪 Testing

### Local Testing

```bash
# Start server
python mcp_server.py

# Test in another terminal
python test_mcp_client.py
```

### Remote Testing

```bash
# Set environment variables
export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/cost-explorer-xyz123"
export BEARER_TOKEN="your-oauth-token"

# Test deployed server
python test_remote_client.py
```

## 🛠️ Available Tools

The Cost Explorer MCP Server provides these tools:

1. **get_today_date** - Get current date for relative queries
2. **get_dimension_values** - Get available values for dimensions (SERVICE, REGION, etc.)
3. **get_tag_values** - Get available tag values
4. **get_cost_and_usage** - Retrieve cost and usage data with filtering
5. **get_cost_and_usage_comparisons** - Compare costs between periods
6. **get_cost_comparison_drivers** - Analyze cost change drivers
7. **get_cost_forecast** - Generate cost forecasts

## 💰 Cost Considerations

**Important**: Each AWS Cost Explorer API call costs $0.01. The server includes optimizations to minimize API calls, but be aware of potential charges when using the tools extensively.

## 🔍 Troubleshooting

### Local Server Issues

```bash
# Check if port 8000 is available
lsof -i :8000

# Check server logs
python mcp_server.py
```

### Deployment Issues

```bash
# Check AWS credentials
aws sts get-caller-identity

# Verify agentcore CLI
agentcore --version

# Check deployment status
agentcore status
```

### Remote Connection Issues

1. Verify BEARER_TOKEN is valid and not expired
2. Check AGENT_ARN format and encoding
3. Ensure OAuth/Cognito is properly configured
4. Verify server deployment status

## 📚 References

- [Agentcore Runtime MCP Documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html)
- [Converting STDIO to Streamable HTTP](https://portkey.ai/docs/guides/converting-stdio-to-streamable-http)
- [MCP Protocol Documentation](https://modelcontextprotocol.io/)
- [AWS Cost Explorer API](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-api.html)

## 🆘 Support

For issues with:
- **MCP Server**: Check the original cost-explorer-mcp-server documentation
- **Agentcore Runtime**: Refer to AWS Bedrock Agentcore documentation
- **Authentication**: Check your OAuth/Cognito configuration
- **AWS Costs**: Review AWS Cost Explorer API pricing and usage