@handle-ai/mcp/README.md

Handle AI MCP Server - Direct API integration for Claude Desktop

# Handle AI MCP Server

A downloadable MCP (Model Context Protocol) server that provides direct integration between Claude Desktop and Handle AI's compliance analysis platform.

## Features

✅ **No WebSocket complexity** - Direct HTTP API calls  
✅ **No timeouts** - Reliable HTTP connections  
✅ **Easy installation** - Single npm command  
✅ **All 7 tools** - Complete Handle AI compliance toolkit  
✅ **Works offline** - No cloud dependencies except API calls  

## Installation

### Option 1: Global Installation (Recommended)
```bash
npm install -g @handle-ai/mcp
```

### Option 2: NPX (No installation needed)
```bash
# Will be used automatically by Claude Desktop
npx @handle-ai/mcp
```

## Configuration

Add this to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "handle-ai": {
      "command": "handle-ai-mcp",
      "env": {
        "HANDLE_AI_API_KEY": "hak_live_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

**Or with npx (no global install needed):**

```json
{
  "mcpServers": {
    "handle-ai": {
      "command": "npx",
      "args": ["-y", "@handle-ai/mcp"],
      "env": {
        "HANDLE_AI_API_KEY": "hak_live_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

## Get Your API Key

1. Go to [Handle AI API Access](https://handle-ai.com/tools/no-code-compliance/api)
2. Navigate to the **Platform Access Keys** section
3. Click **"🚀 Quick Start: Generate Production API Key"**
4. Copy your key (starts with `hak_live_`)

## Available Tools

### 1. professional-gdpr-analysis
Comprehensive GDPR compliance analysis using 5 specialized AI agents.

### 2. analyze-url-compliance  
Analyze any website URL for compliance issues with automatic framework detection.

### 3. multi-compliance-analysis
Check your application against GDPR, HIPAA, and Financial regulations simultaneously.

### 4. complete-compliance-assessment
Process follow-up responses after initial analysis to generate final compliance reports.

### 5. handle-ai-system-status
Check your API usage, remaining credits, and account status.

### 6. list-user-projects
View all your previous compliance analyses and their results.

### 7. get-project-details
Get detailed compliance reports for specific projects.

## Usage in Claude Desktop

After installation and configuration:

1. **Restart Claude Desktop** completely (⌘+Q then reopen)
2. Start a conversation and ask: *"Check my Handle AI system status"*
3. Claude will use the `handle-ai-system-status` tool to verify everything is working

### Example Conversations

**GDPR Analysis:**
```
User: "I need to check if my web app is GDPR compliant"
Claude: "To analyze your app for GDPR compliance, I need some details: 
What's your app name? What platform did you build it on? What features 
does it have? What types of data do you collect?"
```

**URL Analysis:**
```
User: "Analyze my website for compliance issues"
Claude: "What's the URL of your website or application that you'd like 
me to analyze for compliance?"
```

## Troubleshooting

### Tools don't appear in Claude Desktop
- Ensure Claude Desktop version 0.7.0+
- Check configuration file syntax is valid JSON
- Restart Claude Desktop after config changes

### "API key required" error
- Verify your API key starts with `hak_live_`
- Check the key hasn't expired in your Handle AI dashboard
- Ensure the key is correctly set in the configuration

### Test the server manually
```bash
# Set your API key
export HANDLE_AI_API_KEY=hak_live_YOUR_KEY_HERE

# Test the server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | handle-ai-mcp
```

## API Endpoints Used

This MCP server calls these Handle AI API endpoints:
- `POST /gdpr/analyze` - GDPR analysis
- `POST /url-check` - URL compliance scanning  
- `POST /project/multi-agent` - Multi-framework analysis
- `GET /usage/summary` - Usage and limits
- `GET /projects` - List projects
- `GET /projects/:id` - Project details

## System Requirements

- **Node.js**: 18.0.0 or higher
- **Claude Desktop**: 0.7.0 or higher  
- **Handle AI API Key**: Required for all operations

## Benefits vs WebSocket Approach

| Feature | WebSocket Proxy | Downloadable MCP |
|---------|----------------|------------------|
| **Reliability** | ❌ Timeout issues | ✅ HTTP reliability |
| **Setup** | ❌ Complex config | ✅ Simple npm install |
| **Performance** | ❌ Connection overhead | ✅ Direct API calls |
| **Debugging** | ❌ WebSocket complexity | ✅ Standard HTTP |
| **Offline** | ❌ Requires connection | ✅ Works offline |
| **Firewalls** | ❌ WebSocket blocking | ✅ HTTP works everywhere |

## Support

- **Documentation**: [Handle AI MCP Guide](https://handle-ai.com/docs/mcp)
- **API Access**: [Handle AI Dashboard](https://handle-ai.com/tools/no-code-compliance/api)
- **Email**: support@handle-ai.com

---

Built by [Handle AI](https://handle-ai.com) - Professional compliance analysis for modern applications.