# Shutter MCP

A Model Context Protocol (MCP) server that provides timelock encryption capabilities using the Shutter Network. This server allows users to encrypt messages that can only be decrypted after a specified future time, enabling trustless time-delayed communications.

## Features

- Timelock Encryption: Encrypt messages that unlock at future timestamps
- Natural Language Time Parsing: Use expressions like "3 months from now"
- Unix Timestamp Support: Direct timestamp input for precise timing
- Claude Web, VS Code MCP Support
- Comprehensive Error Handling: User-friendly error messages and guidance
- Production Ready: Docker support, health checks, and monitoring

## Important Notice

**ALPHA SOFTWARE**: This is experimental software using the Shutter Network testnet deployment (Gnosis Chiado). Do not use for production or sensitive data. The encryption implementation is for demonstration purposes only.

**Current Limitations:**
- Demo encryption algorithm (not production-grade Shutter encryption)
- Testnet deployment (Chiado testnet only)
- No data persistence guarantees
- API may change without notice

## Live Deployment

**Server URL**: https://shutter-mcp-b76e270d48c5.herokuapp.com/
**Health Check**: https://shutter-mcp-b76e270d48c5.herokuapp.com/health
**MCP Endpoint**: https://shutter-mcp-b76e270d48c5.herokuapp.com/mcp

## Quick Start

### Claude Web Integration

1. Open Claude Web Settings
   - Visit [claude.ai/settings](https://claude.ai/settings)
   - Navigate to "Integrations" section

2. Add Custom Integration
   - Click "Add custom integration"
   - Enter URL: `https://shutter-mcp-b76e270d48c5.herokuapp.com/mcp`
   - Click "Add"

3. Test the Integration
   - Start a new conversation
   - Try: "Encrypt this message to unlock in 3 months: Hello future!"
   - Or: "Explain how timelock encryption works"

### VS Code MCP Integration

1. Install MCP Extension
   - Open VS Code
   - Install the "Model Context Protocol" extension
   - Or install from marketplace: `ms-vscode.vscode-mcp`

2. Configure MCP Server
   - Open VS Code settings (Ctrl+,)
   - Search for "MCP"
   - Add server configuration:
     ```json
     {
       "mcp.servers": {
         "shutter-timelock": {
           "url": "https://shutter-mcp-b76e270d48c5.herokuapp.com/mcp",
           "name": "Shutter Timelock Encryption"
         }
       }
     }
     ```

3. Test the Integration
   - Open command palette (Ctrl+Shift+P)
   - Type "MCP: Call Tool"
   - Select "timelock_encrypt" and provide parameters

## Local Development Setup

If you want to run the server locally for development:

### Prerequisites

- Python 3.11 or higher
- pip (Python package manager)

### Installation

1. **Clone or download this repository**
   ```bash
   git clone <your-repo-url>
   cd shutter-mcp-server
   ```

2. **Run the deployment script**
   ```bash
   ./scripts/deploy.sh
   ```

3. **Start the server**
   ```bash
   ./scripts/start.sh
   ```

The server will be available at `http://localhost:5002` with the MCP endpoint at `http://localhost:5002/mcp`.

### Local Integration Setup

For local development, update your configurations to use:
- Claude Web: `http://localhost:5002/mcp`
- VS Code: `http://localhost:5002/mcp`

### Docker Deployment

```bash
# Build and run with Docker Compose
docker-compose up -d

# Or build and run manually
docker build -t shutter-mcp-server .
docker run -p 5002:5002 shutter-mcp-server
```

## Testing Examples

**Claude Web Test Commands:**
```
Encrypt this message to unlock in 1 hour: Secret meeting at 3pm
Check decryption status for identity: 0x1234...
Explain how timelock encryption works
```

**VS Code Test Commands:**
- Use MCP tools through the command palette
- Test timelock encryption with future timestamps
- Verify health endpoint responses

## Available Tools

### timelock_encrypt(message, unlock_time)
Encrypt a message with timelock encryption using Shutter Network.

**Parameters:**
- `message` (string): The text message to encrypt
- `unlock_time` (string): When the message can be decrypted
  - Natural language: "3 months from now", "1 year from now"
  - Unix timestamp: "1721905313"
  - Absolute date: "2024-12-25", "January 15, 2025"

**Example:**
```
timelock_encrypt("Secret auction bid: $50,000", "2024-12-31 23:59:59")
```

### check_decryption_status(identity)
Check if a timelock encrypted message is ready for decryption.

**Parameters:**
- `identity` (string): The identity returned from `timelock_encrypt`

### decrypt_timelock_message(identity, encrypted_data)
Decrypt a timelock encrypted message if the timelock has expired.

**Parameters:**
- `identity` (string): The identity returned from `timelock_encrypt`
- `encrypted_data` (string): The encrypted data returned from `timelock_encrypt`

### get_unix_timestamp(time_expression)
Convert time expressions to Unix timestamps.

**Parameters:**
- `time_expression` (string): Time to convert (default: "now")

### explain_timelock_encryption()
Get comprehensive explanation of timelock encryption and usage.

## How Timelock Encryption Works

Timelock encryption allows you to encrypt a message that can only be decrypted after a specific time. The Shutter Network uses:

- Threshold Cryptography: Distributed key generation and management
- Decentralized Keypers: Network of nodes that collectively manage decryption keys
- Time-based Release: Keys are only released after the specified timestamp
- Trustless Operation: No single party can decrypt messages early

## Use Cases

- Sealed Bid Auctions: Hide bids until auction ends
- Time-delayed Announcements: Schedule future reveals
- Dead Man's Switch: Messages that unlock if you don't check in
- Contest Reveals: Hide answers until contest ends
- Future Communications: Send messages to your future self

## Configuration

### Environment Variables

- `PORT`: Server port (default: 5002)
- `SHUTTER_API_BASE`: Shutter API endpoint (default: Chiado testnet)
- `SHUTTER_REGISTRY_ADDRESS`: Registry contract address

### Custom Configuration

Edit `src/server.py` to modify:
- API endpoints
- Timeout values
- Error handling behavior
- Additional tools

## Testing

Run the example script to test functionality:

```bash
python examples/usage_example.py
```

Health check endpoint:
```bash
curl https://shutter-mcp-b76e270d48c5.herokuapp.com/health
```

Local testing:
```bash
curl http://localhost:5002/health
```

## Project Structure

```
shutter-mcp-server/
├── src/
│   └── server.py              # Main server implementation
├── scripts/
│   ├── deploy.sh              # Deployment script
│   └── start.sh               # Start script
├── examples/
│   └── usage_example.py       # Usage examples
├── docs/
│   └── API.md                 # API documentation
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Docker configuration
├── docker-compose.yml         # Docker Compose configuration
├── Procfile                   # Heroku process configuration
├── deploy-heroku.ps1          # PowerShell deployment script
└── README.md                  # This file
```

## Security Considerations

**IMPORTANT: This is alpha software with significant limitations:**

- **Demo Implementation**: Current encryption is for demonstration purposes only
- **Testnet Only**: Uses Chiado testnet - not suitable for production data
- **No Production Encryption**: Does not implement full Shutter encryption algorithms yet
- **Experimental Status**: API and functionality may change without notice
- **No Data Guarantees**: No persistence or availability guarantees

**For Production Use:**
- Implement proper Shutter encryption algorithms
- Use mainnet deployment when available
- Add authentication and access controls
- Implement proper key management
- Use HTTPS in production deployments

## Troubleshooting

### Server Won't Start
- Check Python version (3.11+ required)
- Verify all dependencies are installed: `pip install -r requirements.txt`
- Check port availability: `lsof -i :5002` (Linux/Mac) or `netstat -an | findstr :5002` (Windows)

### Claude Integration Issues
- Ensure server is accessible from the internet
- Verify MCP endpoint returns proper responses: `curl https://shutter-mcp-b76e270d48c5.herokuapp.com/mcp`
- Check CORS configuration for cross-origin requests

### VS Code Integration Issues
- Verify MCP extension is installed and enabled
- Check server configuration in VS Code settings
- Use local server for development: `http://localhost:5002/mcp`

### Shutter API Errors
- Verify internet connectivity
- Check Shutter Network status
- Ensure timestamps are in the future

## Development

### Adding New Tools

1. Define the tool function with `@mcp.tool()` decorator
2. Add comprehensive docstring with parameter descriptions
3. Include proper error handling and user guidance
4. Test with the example script

### Modifying Time Parsing

Edit the `parse_time_expression` method in the `ShutterTimelock` class to support additional time formats.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests and documentation
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Acknowledgments

- [Shutter Network](https://shutter.network/) for timelock encryption infrastructure
- [Model Context Protocol](https://modelcontextprotocol.io/) for the integration framework
- [FastAPI](https://fastapi.tiangolo.com/) for the web framework

## Support

- Issues: Open a GitHub issue
- Documentation: See `docs/` directory
- Examples: Check `examples/` directory

---

**Version**: 2.1.0  
**Last Updated**: August 2025  
**Compatibility**: Claude Web, VS Code MCP, MCP Protocol 2024-11-05