# RegGuard MCP Server 🛡️

> **AI-Enhanced Financial Marketing Compliance Server using Model Context Protocol (MCP)**

RegGuard is a sophisticated MCP (Model Context Protocol) server that provides AI-powered regulatory compliance checking for financial marketing content. It leverages OpenAI's GPT-4o-mini model combined with jurisdiction-specific regulatory knowledge to detect violations across multiple financial markets.

[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://python.org)
[![OpenAI](https://img.shields.io/badge/AI-GPT--4o--mini-green.svg)](https://openai.com)
[![MCP](https://img.shields.io/badge/Protocol-MCP-purple.svg)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 🎯 What Does RegGuard Do?

RegGuard acts as an intelligent compliance assistant that:

- **🔍 Analyzes Marketing Content**: Uses AI to scan financial marketing materials for regulatory violations
- **🌍 Multi-Jurisdiction Support**: Covers Singapore (SG), Hong Kong (HK), UAE (AE), and India (IN) regulations
- **⚡ Real-time Compliance Checking**: Integrates seamlessly with AI assistants like Claude and Cursor
- **📋 Automatic Disclaimer Insertion**: Intelligently places required regulatory disclaimers
- **📊 Audit Trail Generation**: Maintains tamper-proof logs of all compliance checks
- **🎯 Contextual AI Analysis**: Goes beyond pattern matching to understand regulatory nuances

## 🧠 Key Concepts & Educational Resources

### Understanding MCP (Model Context Protocol)
- **[MCP Official Documentation](https://modelcontextprotocol.io/)** - Learn about the open standard for connecting AI assistants to external systems
- **[MCP GitHub Repository](https://github.com/modelcontextprotocol/specification)** - Technical specification and examples
- **[Building MCP Servers - Anthropic Guide](https://docs.anthropic.com/en/docs/build-with-claude/mcp)** - Step-by-step guide to creating MCP servers

### Financial Regulatory Compliance Basics
- **[MAS Guidelines on Fair Dealing (Singapore)](https://www.mas.gov.sg/regulation/guidelines/guidelines-on-fair-dealing)** - Singapore's financial marketing regulations
- **[SFC Investment Advertisement Guidelines (Hong Kong)](https://www.sfc.hk/web/EN/regulatory-functions/intermediaries/supervision/investment-advertisements.html)** - Hong Kong securities marketing rules
- **[DFSA Conduct Rules (UAE)](https://www.dfsa.ae/rulebooks/conduct-of-business-rulebook)** - Dubai financial services regulations
- **[SEBI Guidelines (India)](https://www.sebi.gov.in/)** - Securities and Exchange Board of India regulations

### AI-Powered Compliance Technology
- **[OpenAI API Documentation](https://platform.openai.com/docs)** - Understanding GPT-4o-mini integration
- **[Financial AI Compliance Overview](https://www.mckinsey.com/industries/financial-services/our-insights/ai-powered-decision-making-for-the-future)** - Industry insights on AI in finance
- **[RegTech Explained](https://www.investopedia.com/terms/r/regtech.asp)** - Introduction to regulatory technology

## 🚀 Quick Start Guide

### Prerequisites

- **Python 3.8+** ([Download Python](https://python.org/downloads/))
- **OpenAI API Key** ([Get API Key](https://platform.openai.com/api-keys))
- **Git** ([Install Git](https://git-scm.com/downloads))

### 1. Clone and Setup

```bash
# Clone the repository
git clone https://github.com/your-username/regguard-mcp.git
cd regguard-mcp

# Create virtual environment (recommended)
python -m venv regguard-env
source regguard-env/bin/activate  # On Windows: regguard-env\Scripts\activate

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

### 2. Configure API Key

Create a `.env` file in the project root:

```bash
# Create .env file
echo 'OPENAI_API_KEY="your-openai-api-key-here"' > .env
```

**Important**: Never commit your actual API key to GitHub!

### 3. Test the Server

```bash
# Test server functionality
python test_server.py

# Test AI integration
python test_ai_client.py

# Run example usage
python example_usage.py
```

## 🔌 How to Use RegGuard MCP Server

### Option 1: Claude Desktop Integration (Recommended)

1. **Install Claude Desktop** ([Download here](https://claude.ai/download))

2. **Configure MCP Settings**:
   - Open Claude Desktop settings
   - Navigate to "Developer" > "MCP Servers"
   - Add the following configuration:

```json
{
  "mcpServers": {
    "regguard": {
      "command": "python",
      "args": ["-m", "src.regguard.server"],
      "cwd": "/full/path/to/regguard-mcp",
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}
```

3. **Start Using**:
   ```
   @regguard Please check this marketing copy for Singapore compliance:
   "Our investment product guarantees 15% annual returns with zero risk!"
   ```

### Option 2: Cursor IDE Integration

1. **Install Cursor** ([Download here](https://cursor.sh/))

2. **Configure MCP in Workspace**:
   Add to your Cursor workspace settings:

```json
{
  "mcp.servers": [
    {
      "name": "regguard",
      "command": ["python", "-m", "src.regguard.server"],
      "cwd": "./regguard-mcp"
    }
  ]
}
```

3. **Use in Cursor**:
   ```
   @regguard Analyze this financial ad for Hong Kong compliance violations
   ```

### Option 3: Direct Python Integration

```python
from regguard_client import RegGuardClient

# Initialize client
client = RegGuardClient()
client.start_server()

# Check compliance
result = client.check_compliance(
    html_content="<p>Guaranteed 20% returns!</p>",
    jurisdiction="sg"
)

print(f"Violations found: {len(result['violations'])}")
```

## 🛠️ Available Tools & Features

### 1. `check_rule_violation` - AI Compliance Analysis
Analyzes marketing content for regulatory violations across multiple jurisdictions.

**Example Usage**:
```
@regguard Check this content for Singapore violations:
"Join our exclusive investment club! Guaranteed profits of 25% annually with zero risk to your capital. Limited time offer - only 48 hours remaining!"
```

**Response Includes**:
- Detailed violation descriptions
- Severity levels (Critical, High, Medium, Low)
- Matched content highlights
- Regulatory references
- Actionable recommendations

### 2. `auto_insert_disclaimer` - Smart Disclaimer Placement
Automatically inserts jurisdiction-appropriate disclaimers in optimal locations.

**Example**:
```
@regguard Add appropriate disclaimers for this Singapore investment ad:
<div>
  <h2>Investment Opportunity</h2>
  <p>High potential returns available.</p>
  <button>Invest Now</button>
</div>
```

### 3. `export_audit_trail` - Compliance Audit Logs
Generates comprehensive audit reports for compliance teams.

### 4. `health` - System Status
Checks server health and AI capability status.

### 5. `list_supported_markets` - Available Jurisdictions
Returns: `["sg", "hk", "ae", "in"]`

## 📁 Project Structure

```
regguard-mcp/
├── src/regguard/           # Core server code
│   ├── server.py          # Main MCP server
│   ├── rules_engine.py    # AI compliance engine
│   └── audit_writer.py    # Audit trail management
├── rules/                 # Jurisdiction-specific rules
│   ├── sg.yml            # Singapore (MAS)
│   ├── hk.yml            # Hong Kong (SFC)
│   ├── ae.yml            # UAE (DFSA)
│   └── in.yml            # India (SEBI)
├── audits/               # Compliance audit logs
├── tests/                # Test files
├── example_usage.py      # Usage examples
├── requirements.txt      # Python dependencies
└── README.md            # This file
```

## 🌍 Supported Jurisdictions

| Market | Regulator | Key Features | Special Requirements |
|--------|-----------|--------------|---------------------|
| **Singapore (SG)** | MAS | Guaranteed returns detection, Risk disclosure checks | English language, Clear risk warnings |
| **Hong Kong (HK)** | SFC | SFC authorization checks, Complex product warnings | Traditional/Simplified Chinese support |
| **UAE (AE)** | DFSA/SCA | DFSA licensing validation, Risk rating requirements | Arabic/English bilingual compliance |
| **India (IN)** | SEBI | Risk-o-meter requirements, Celebrity endorsement rules | Local language disclosures |

## 🔧 Implementation Steps for Your Project

### Step 1: Environment Setup
```bash
# 1. Clone this repository
git clone https://github.com/your-username/regguard-mcp.git

# 2. Navigate to project directory
cd regguard-mcp

# 3. Create Python virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

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

### Step 2: Configuration
```bash
# 1. Get OpenAI API key from https://platform.openai.com/api-keys
# 2. Create .env file
echo 'OPENAI_API_KEY="your-actual-api-key"' > .env

# 3. Test configuration
python test_server.py
```

### Step 3: Integration
Choose your preferred integration method:

**For Claude Desktop Users**:
- Configure MCP settings as shown above
- Restart Claude Desktop
- Use `@regguard` commands

**For Cursor IDE Users**:
- Add MCP configuration to workspace
- Restart Cursor
- Use `@regguard` in your code

**For Custom Integration**:
- Use the provided example scripts
- Implement JSON-RPC communication
- Follow MCP protocol specification

### Step 4: Customization
```bash
# 1. Modify jurisdiction rules in rules/ directory
# 2. Add custom compliance patterns
# 3. Extend supported markets if needed
# 4. Customize disclaimer templates
```

## 🧪 Testing Your Setup

### Basic Functionality Test
```bash
python test_server.py
```

### AI Integration Test
```bash
python test_ai_client.py
```

### Full Feature Demo
```bash
python example_usage.py
```

### Manual Testing Examples

1. **Critical Violation Test**:
   ```
   Content: "Guaranteed 25% returns with zero risk!"
   Expected: Multiple critical violations detected
   ```

2. **Compliant Content Test**:
   ```
   Content: "Investment involves risk. Past performance is not indicative of future results."
   Expected: No violations, compliance status PASS
   ```

## 📊 Understanding Results

### Violation Severity Levels
- **CRITICAL**: Serious regulatory breaches requiring immediate attention
- **HIGH**: Important compliance issues that should be addressed
- **MEDIUM**: Moderate concerns that may need review
- **LOW**: Minor issues or best practice recommendations

### AI Analysis Features
- **Contextual Understanding**: Goes beyond keyword matching
- **Regulatory Knowledge**: Trained on jurisdiction-specific rules
- **Confidence Scoring**: AI confidence in each violation detection
- **Actionable Recommendations**: Specific suggestions for fixes

## 🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support & Troubleshooting

### Common Issues

**"OpenAI API key not found"**
- Ensure `.env` file exists with correct `OPENAI_API_KEY`
- Check that your API key is valid and has credits

**"Server not responding"**
- Verify Python dependencies are installed
- Check that port is not in use by another process
- Review error logs in terminal

**"AI analysis failed"**
- Confirm OpenAI API key has sufficient credits
- Check internet connection
- Verify OpenAI service status

### Getting Help

- 📚 **Documentation**: Review the detailed guides in `/docs`
- 🐛 **Issues**: Report bugs via GitHub Issues
- 💬 **Discussions**: Join our GitHub Discussions for questions
- 📧 **Contact**: Reach out for enterprise support

## 🚀 What's Next?

- [ ] Additional jurisdiction support (EU, US, Canada)
- [ ] Real-time compliance monitoring dashboard
- [ ] Integration with more AI assistants
- [ ] Enhanced multilingual support
- [ ] Advanced analytics and reporting

---

**Built with ❤️ for the financial compliance community**

*RegGuard helps ensure your financial marketing content meets regulatory standards across global markets. Stay compliant, stay confident.*