<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/anonsec-header.svg">
    <img alt="AnonSec MCP Server - Anonymous Email Management Header" src="assets/anonsec-header.svg" width="100%">
  </picture>
</p>

<h1 align="left">Firefox Relay MCP Server - Anonymous Email Management</h1>
<p align="left">
  <a href="https://scorecard.dev/viewer/?uri=github.com/VRIL-LABS/anonsec-mcp-server"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/VRIL-LABS/anonsec-mcp-server/badge"></a>
</p>
<p align="left">
  <strong>Production-Ready MCP Server for Firefox Relay Anonymous Email Operations</strong>
</p>

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node-%3E%3D22.0.0-green.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.6.3-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-2.0.0-orange.svg)](https://modelcontextprotocol.io/)

<sub>// crafted for the security community — funding keeps it maintained</sub>

[![GitHub Sponsors](assets/donate/github-sponsors.svg)](https://github.com/sponsors/VRIL-LABS)
[![Open Collective](assets/donate/open-collective.svg)](https://opencollective.com/vrillabs)
[![Ko-fi](assets/donate/ko-fi.svg)](https://ko-fi.com/vrillabs)
[![Buy Me a Coffee](assets/donate/buy-me-a-coffee.svg)](https://buymeacoffee.com/vrillabs)
[![thanks.dev](assets/donate/thanks-dev.svg)](https://thanks.dev/u/gh/vril-labs)

---

## Overview

**Firefox Relay MCP Server** (`anonsec-mcp-server`) is a production-grade Model Context Protocol server that provides comprehensive anonymous email management capabilities through Firefox Relay addresses. Built with privacy, security, and operational excellence as core principles, this server enables AI agents and applications to send, receive, and process emails while maintaining complete anonymity.

## Core Value Proposition

- **Privacy-First**: All email operations maintain sender anonymity through Firefox Relay infrastructure
- **PQC-Ready**: Post-Quantum Cryptography ready encryption architecture for data at rest
- **Production-Grade**: Built with golden-standard programming practices for reliability and security
- **MCP Native**: Full Model Context Protocol 2.0 compliance with tools and resources

## Quick Start

### Prerequisites

- Node.js >= 18.0.0
- npm or yarn
- Firefox Relay account and API access

### Installation

```bash
# Clone the repository
git clone https://github.com/VRIL-LABS/anonsec-mcp-server.git
cd anonsec-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm run dev
```

### Configuration

Create a `.env` file with your Firefox Relay credentials:

```env
FIREFOX_RELAY_API_KEY=your_api_key_here
ENCRYPTION_KEY=your_32_byte_hex_key_here
DATABASE_PATH=./data/anonsec.sqlite
PORT=3000
```

The encryption key must be exactly 32 bytes (64 hex characters). Generate one with:

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

## Capabilities

### Email Management
- List new/unread emails from Firefox Relay addresses
- Read full email content with decryption
- Retrieve all emails with filtering
- Get latest email from any relay address

### OTP Handling
- Extract OTP codes from emails
- Validate OTP format and confidence
- Check OTP expiration
- Re-extract OTP from email body

### Email Sending
- Send anonymous emails through relay addresses
- Support for plain text and HTML content
- Custom headers and metadata
- OTP email simulation

## Project Structure

```
.
├── src/
│   ├── index.ts          # Server entry point and configuration
│   ├── api/
│   │   └── index.ts      # Firefox Relay API client
│   ├── config/
│   │   └── index.ts      # Configuration management
│   ├── db/
│   │   └── index.ts      # SQLite database service
│   ├── tools/
│   │   ├── all_emails.ts
│   │   ├── latest_email.ts
│   │   ├── latest_email_otp.ts
│   │   ├── new_emails.ts
│   │   ├── read_emails.ts
│   │   └── send_anon_email.ts
│   ├── types/
│   │   └── index.ts      # Type definitions
│   └── utils/
│       ├── crypto.ts     # Encryption utilities
│       └── otp.ts        # OTP extraction utilities
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md
```

## Tools

The server provides 6 MCP tools:

1. **new_emails** - Retrieve new/unread emails
2. **read_emails** - Read full email content
3. **all_emails** - List all emails with filtering
4. **latest_email** - Get the latest email
5. **latest_email_otp** - Extract OTP from latest email
6. **send_anon_email** - Send anonymous emails

## Resources

- `urn:anonsec:relay/addresses` - Firefox Relay address management
- `urn:anonsec:email/collection` - Email collection access
- `urn:anonsec:otp/emails` - OTP emails collection
- `urn:anonsec:server/info` - Server information
- `urn:anonsec:audit/logs` - Audit logs
- `urn:anonsec:email/{emailId}` - Individual email access

## Security Features

- **AES-256-GCM Encryption** for data at rest
- **Immutable audit logs** for all operations
- **Request ID tracking** for traceability
- **Security validation** for sensitive operations
- **OTP code masking** in responses (never exposed)
- **Sensitive data redaction** in audit logs

## Architecture

The server follows a clean, production-ready architecture:

1. **MCP Server Layer** - Server initialization, tool registration, request handling
2. **Tools Layer** - Individual tool implementations
3. **Core Services Layer** - Database, API client, configuration, types, utilities
4. **Data Layer** - SQLite database with PQC-ready encryption

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Security

See [SECURITY.md](SECURITY.md) for vulnerability reporting and security practices.

## License

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

---

<p align="center">
  <sub>Built by <strong>VRIL-LABS</strong> · Ancient Knowledge · Future Technology</sub>
</p>