# MCP Guardian - Real-World Examples

This directory contains practical examples of how to use MCP Guardian in real AI Agent scenarios.

## 🤖 AI Agent Tools API

The `real_world_example.py` demonstrates a complete AI Agent tools API with:

### Available Tools:
- **Calculator**: Mathematical operations (`tools:calculator:execute`)
- **Weather**: Weather information (`tools:weather:read`)
- **Files**: File system access (`tools:files:read`)
- **Admin**: System administration (`tools:admin:system`)
- **User Info**: User information (`user:info:read`)
- **Rate Limit**: Rate limit status (`user:rate-limit:read`)

### Security Features:
- JWT authentication for all protected endpoints
- Scope-based authorization (different tools require different permissions)
- Rate limiting per user
- Secure error handling

## 🚀 Running the Example

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

# Copy config file
cp ../config.example.yaml config.yaml

# Generate test tokens
python ../test_tokens.py
```

### 2. Start the API
```bash
python real_world_example.py
```

### 3. Test with Different Agents

#### Free Tier Agent (Limited Access)
```bash
# Get token for free tier agent
TOKEN="your-free-tier-token"

# Can access basic tools
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/tools/weather?city=London

# Cannot access admin tools (will get 403)
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/tools/admin/system
```

#### Pro Tier Agent (Full Access)
```bash
# Get token for pro tier agent
TOKEN="your-pro-tier-token"

# Can access all tools
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/tools/calculator -d '{"expression": "10 * 5"}'
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/tools/admin/system
```

## 🎯 Use Cases Demonstrated

### 1. Multi-Tier SaaS Model
- **Free Tier**: Limited to basic tools (weather, calculator)
- **Pro Tier**: Access to all tools including admin functions
- **Enterprise**: Custom scopes and higher rate limits

### 2. Corporate Security
- **Read-Only Agents**: Can only read data (weather, files)
- **Admin Agents**: Can perform system operations
- **Audit Trail**: All requests logged with user information

### 3. Rate Limiting Protection
- **Fair Usage**: Each user limited to reasonable request rates
- **Abuse Prevention**: Protects against runaway agents
- **Scalability**: Ensures service stability for all users

## 🔧 Customization

### Adding New Tools
```python
@app.post("/tools/new-tool")
@guardian.protect(scope="tools:new-tool:execute")
async def new_tool(request: Request):
    user_info = request.state.token
    # Your tool logic here
    return {"tool": "new-tool", "user": user_info.get("sub")}
```

### Custom Scopes
```python
# In your JWT token
{
  "scopes": [
    "tools:calculator:execute",
    "tools:weather:read",
    "tools:new-tool:execute",
    "user:info:read"
  ]
}
```

### Rate Limiting Configuration
```yaml
# In config.example.yaml
rate_limit:
  requests: 1000  # Higher limit for production
  period_minutes: 60
```

## 🧪 Testing Scenarios

### 1. Authentication Tests
```bash
# Missing token
curl http://localhost:8000/tools/calculator

# Invalid token
curl -H "Authorization: Bearer invalid-token" http://localhost:8000/tools/calculator

# Expired token
curl -H "Authorization: Bearer expired-token" http://localhost:8000/tools/calculator
```

### 2. Authorization Tests
```bash
# Insufficient scope
curl -H "Authorization: Bearer token-with-limited-scopes" http://localhost:8000/tools/admin/system

# Correct scope
curl -H "Authorization: Bearer token-with-admin-scope" http://localhost:8000/tools/admin/system
```

### 3. Rate Limiting Tests
```bash
# Test rate limiting
for i in {1..150}; do
  curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/tools/weather
done
```

## 📊 Monitoring

### Health Check
```bash
curl http://localhost:8000/health
```

### User Information
```bash
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/user/info
```

### Rate Limit Status
```bash
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/user/rate-limit
```

## 🔒 Security Best Practices

1. **Use Strong Keys**: Generate 2048+ bit RSA keys
2. **Rotate Keys**: Regularly update your JWT keys
3. **Monitor Usage**: Track rate limiting and access patterns
4. **Audit Logs**: Log all security events
5. **HTTPS Only**: Use HTTPS in production
6. **Scope Design**: Follow principle of least privilege

## 🚀 Production Deployment

See the main [DEPLOYMENT.md](../DEPLOYMENT.md) for production deployment instructions.

---

**This example shows how MCP Guardian enables secure, scalable AI Agent tool APIs with minimal code!** 🎉
