MCP Email Service

A secure Model Context Protocol (MCP) server and client application for sending emails, featuring post-quantum cryptography (CRYSTALS-Kyber, Falcon, SPHINCS+), AES-256-GCM encryption, and spaCy-based natural language processing (NLP) for user requests. Designed for Ubuntu Linux, this service ensures quantum-resistant communication and robust email handling.

Table of Contents

- Features - Prerequisites - Environment Setup - Dependency Installation - Configuration - Installation - Usage - Usage Examples - Security - Troubleshooting - Contributing - License

Features

- Post-Quantum Cryptography: Uses CRYSTALS-Kyber for key exchange, Falcon for digital signatures, and SPHINCS+ as a backup signature algorithm. - Secure Encryption: Employs AES-256-GCM for authenticated encryption of messages. - Natural Language Processing: Leverages spaCy (en_core_web_sm) for robust parsing of email requests. - Real Email Sending: Integrates with SMTP servers (e.g., Gmail) for actual email delivery. - Asynchronous Communication: Built with asyncio for efficient server-client interactions. - Ubuntu Linux Support: Optimized for Ubuntu 22.04+ with detailed setup instructions.

Prerequisites

- Operating System: Ubuntu Linux 22.04 or later. - Python: Version 3.8 or higher. - Internet Connection: Required for email sending and dependency installation. - Git: For cloning the repository. - SMTP Account: A valid email account (e.g., Gmail with an App Password) for sending emails.

Environment Setup

1. Update System:

   sudo apt-get update
   sudo apt-get upgrade -y
   

2. Install System Dependencies:

   sudo apt-get install -y python3 python3-pip python3-dev build-essential libssl-dev libffi-dev python3-venv git cmake ninja-build

   

3. Clone the Repository:

   git clone https://github.com/<your-username>/mcp-email-service.git

   cd mcp-email-service

   

Dependency Installation

The application relies on Python libraries and, optionally, compiled C libraries for post-quantum cryptography. All dependencies are installed via the provided setup.sh script.

Python Dependencies

- pqcrypto==0.1.1: Post-quantum cryptography (Kyber, Falcon, SPHINCS+). - pyyaml==6.0.1: YAML configuration parsing. - spacy==3.7.2: NLP for processing user requests. - cryptography==42.0.5: AES-256-GCM encryption.

Optional C Library

- liboqs: Required if pqcrypto wheels are unavailable for your platform. The setup script compiles it automatically if needed.

Installation Steps

1. Run the Setup Script:

   chmod +x setup.sh
   ./setup.sh
   

This script: - Creates a virtual environment (venv). - Installs Python dependencies from requirements.txt. - Downloads the spaCy en_core_web_sm model. - Compiles liboqs and liboqs-python if pqcrypto installation fails. - Verifies installations of pqcrypto and cryptography.

2. Activate the Virtual Environment:

   source venv/bin/activate

   

Configuration

1. Server Configuration: - Edit server/config.yaml:

     server:
       host: "0.0.0.0"
       port: 8765
     email:
       server: "smtp.gmail.com"
       port: 587
       user: "your-email@gmail.com"
       password: "your-app-password"
     

- Email Settings: - user: Your email address. - password: An App Password (for Gmail, generate one in Google Account settings under Security > 2-Step Verification > App Passwords). - server and port: Your SMTP server details (e.g., smtp.gmail.com:587 for Gmail).

2. Client Configuration:
- Edit client/config.yaml:

     server:

       host: "localhost"

       port: 8765

     

- Set host and port to match the server's configuration.

3. Secure Configuration Files:
- Ensure server/config.yaml is protected (e.g., chmod 600 server/config.yaml), as it contains sensitive credentials.

Installation

After setting up the environment and dependencies: 1. Verify Virtual Environment:

   source venv/bin/activate
   python -c "import pqcrypto, spacy, cryptography; print('All dependencies installed')"
   

2. Test Configuration:
- Ensure server/config.yaml and client/config.yaml are correctly configured.
- Verify network access to the SMTP server.

Usage

1. Start the Application:

   chmod +x run.sh
   ./run.sh
   

- This starts the MCP server in the background and the client in the foreground. - Alternatively, run separately:

     source venv/bin/activate
     python server/mcp_server.py &
     python client/mcp_client.py
     

2. Interact with the Client:
- The client prompts for natural language input.
- Enter requests like: "Send an email to user@example.com with subject Hello and message This is a test."
- Type quit to exit.

3. Server Logs:
- The server prints connection and error messages to the console.
- Check logs for debugging issues.

Usage Examples

The client processes natural language requests using spaCy. Below are example inputs and their outcomes:

1. Basic Email:

   Input: Send an email to john.doe@example.com saying Hello, how are you?

   Output: Server response: {'status': 'success', 'message': 'Email sent'}

   

- Sends an email to john.doe@example.com with subject "Default Subject" and body "Hello, how are you?".

2. Email with Subject:

   Input: Email jane@example.com with subject Meeting Tomorrow and message Let's meet at 10 AM.

   Output: Server response: {'status': 'success', 'message': 'Email sent'}

   

- Sends an email to jane@example.com with subject "Meeting Tomorrow" and body "Let's meet at 10 AM.".

3. Complex Request:

   Input: Send a message to test@example.com with title Project Update and content Please review the latest report.

   Output: Server response: {'status': 'success', 'message': 'Email sent'}

   

- Sends an email to test@example.com with subject "Project Update" and body "Please review the latest report.".

4. Invalid Email:

   Input: Send an email to invalid saying Test

   Output: Server response: {'status': 'success', 'message': 'Email sent'}

   

- Falls back to default@example.com as the recipient.

Security

- Post-Quantum Cryptography: - CRYSTALS-Kyber (ML-KEM): Secures key exchange for quantum-resistant encryption. - Falcon: Provides primary digital signatures for authentication. - SPHINCS+: Backup signature algorithm for redundancy. - Symmetric Encryption: - AES-256-GCM: Ensures confidentiality, integrity, and authenticity of messages using a key derived from Kyber. - Configuration Security: - Protect server/config.yaml to safeguard email credentials. - Network Security: - Run the server on a trusted network or behind a firewall. - Consider TLS for SMTP connections (already enabled for Gmail).

Troubleshooting

- Email Sending Fails: - Verify server/config.yaml credentials and SMTP settings. - Ensure the email provider allows App Passwords (for Gmail, enable 2-Step Verification). - Check server logs for SMTP errors. - pqcrypto Installation Fails: - Run setup.sh again to compile liboqs and liboqs-python. - Ensure cmake and ninja-build are installed. - spaCy Issues: - Verify the en_core_web_sm model: python -m spacy download en_core_web_sm. - Check for sufficient memory (spaCy requires ~200MB). - Connection Errors: - Ensure client/config.yaml matches server/config.yaml for host and port. - Check if the server is running (ps aux | grep mcp_server.py). - General Debugging: - Run server and client separately to isolate issues. - Enable verbose logging by adding print statements in mcp_server.py or mcp_client.py.

Contributing

Contributions are welcome! Please follow these steps: 1. Fork the repository. 2. Create a feature branch (git checkout -b feature/your-feature). 3. Commit changes (git commit -m 'Add your feature'). 4. Push to the branch (git push origin feature/your-feature). 5. Open a Pull Request.

Please ensure code follows PEP 8 and includes tests where applicable.

License

This project is licensed under the MIT License. See the LICENSE file for details.

MIT License
Copyright (c) 2025 <Your Name>
Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.