# 📡 Remote Communication MCP Server

A production-ready **Model Context Protocol (MCP)** server built with **Node.js** and **TypeScript** that exposes email communication tools over **HTTP/SSE Transport** (using `StreamableHTTPServerTransport`).

This remote implementation allows AI clients like Claude Desktop, Cursor, or MCP Inspector to connect to a publicly hosted instance (e.g., deployed on Render) rather than running the process locally.

---

## 📖 What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that enables AI applications to connect to external tools and data sources. While local MCP servers run as child processes over `stdio`, remote MCP servers expose a web server communicating over JSON-RPC streamed via HTTP Server-Sent Events (SSE).

```
┌──────────────────┐            HTTP / SSE            ┌─────────────────────┐
│    AI Client     │ ◄──────────────────────────────► │  Remote MCP Server  │
│ (Claude/Cursor/  │        JSON-RPC over POST        │    (This Project)   │
│  MCP Inspector)  │      & Event Stream (GET)        │                     │
└──────────────────┘                                  └─────────────────────┘
```

---

## 🏗️ Architecture

```
┌────────────────────────────────────────────────────────────────────────┐
│                                AI Client                               │
│                  (Claude Desktop / Cursor / Inspector)                 │
└───────────────────┬───────────────────────────────▲────────────────────┘
                    │                               │
                    │ HTTP POST /mcp                │ GET /mcp (SSE Stream)
                    ▼                               │
┌───────────────────────────────────────────────────┴────────────────────┐
│                  Remote MCP Server (Express / Node.js)                 │
│                                                                        │
│   ┌───────────────────────────────────────────────────────────────┐    │
│   │                     Active Sessions Store                     │    │
│   │             Maps: Session ID ──► MCP Server Session           │    │
│   │                                                               │    │
│   │ ┌───────────────────────────────────────────────────────────┐ │    │
│   │ │                     MCP Server Session                    │ │    │
│   │ │  ┌──────────────────────────────────────────────────────┐ │ │    │
│   │ │  │                   Streamable Transport               │ │ │    │
│   │ │  └──────────────────────────┬───────────────────────────┘ │ │    │
│   │ │                             ▼                             │ │    │
│   │ │  ┌──────────────────────────────────────────────────────┐ │ │    │
│   │ │  │                     McpServer                        │ │ │    │
│   │ │  │ ┌──────────────┐ ┌────────────────┐ ┌──────────────┐ │ │ │    │
│   │ │  │ │ health_check │ │ list_providers │ │  send_email  │ │ │ │    │
│   │ │  │ └──────────────┘ └────────────────┘ └───────┬──────┘ │ │ │    │
│   │ │  └─────────────────────────────────────────────┼────────┘ │ │    │
│   │ └────────────────────────────────────────────────┼──────────┘ │    │
│   └──────────────────────────────────────────────────┼────────────┘    │
│                                                      │                 │
│                                         ┌────────────▼─────────────┐   │
│                                         │     EmailService         │   │
│                                         │     (Nodemailer)         │   │
│                                         └────────────┬─────────────┘   │
└──────────────────────────────────────────────────────┼─────────────────┘
                                                       │
                                                       ▼
                                          ┌──────────────────────────┐
                                          │      SMTP Server         │
                                          │  (Gmail, Outlook, etc.)  │
                                          └──────────────────────────┘
```

---

## 📁 Project Structure

```
communication-mcp-server/
├── src/
│   ├── server.ts              # Entry point — Express + Streamable HTTP Server
│   ├── config/
│   │   └── index.ts           # Environment configuration loader
│   ├── tools/
│   │   ├── index.ts           # Tool registry (registers all tools)
│   │   ├── health.tool.ts     # health_check tool
│   │   ├── providers.tool.ts  # list_providers tool
│   │   └── email.tool.ts      # send_email tool
│   ├── services/
│   │   └── email.service.ts   # Email delivery via Nodemailer
│   ├── utils/
│   │   ├── logger.ts          # Pino logger (writes to stderr)
│   │   └── validators.ts      # Email validation utilities
│   └── types/
│       └── index.ts           # TypeScript type definitions
├── .env.example               # Environment variable template
├── .gitignore                 # Git ignore rules
├── package.json               # Dependencies & scripts
├── render.yaml                # Render.com deployment blueprint
├── tsconfig.json              # TypeScript configuration
└── README.md                  # This file
```

---

## 🛠️ Available Endpoints & Tools

### HTTP Endpoints
- `GET /health` - Public endpoint returning server configuration and status.
- `POST /mcp` - MCP JSON-RPC message endpoint.
- `GET /mcp` - MCP Server-Sent Events (SSE) stream endpoint.
- `DELETE /mcp` - Terminates the MCP session.

### Registered MCP Tools
| Tool | Description | Parameters |
|------|-------------|------------|
| `health_check` | Returns server status, timestamp, version, and uptime | None |
| `list_providers` | Lists configured communication providers | None |
| `send_email` | Sends an email via SMTP | `to`, `subject`, `text`, `html?` |

---

## 🚀 Installation

### Prerequisites

- **Node.js** >= 18.0.0
- **npm** >= 9.0.0
- An SMTP email account (e.g., Gmail with App Password)

### Setup

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

# 2. Install dependencies
npm install

# 3. Configure environment variables
cp .env.example .env
# Edit .env with your SMTP credentials, PORT, and optional API_KEY

# 4. Build the project
npm run build
```

---

## ⚙️ Configuration

Copy `.env.example` to `.env` and fill in your values:

| Variable | Description | Default / Example |
|----------|-------------|-------------------|
| `NODE_ENV` | Environment mode | `development` |
| `LOG_LEVEL` | Pino log level (`debug`, `info`, `warn`, `error`) | `info` |
| `PORT` | HTTP Server port | `3000` |
| `API_KEY` | Optional token to secure the MCP endpoints | (None) |
| `CORS_ORIGIN` | CORS allowed origins | `*` |
| `SMTP_HOST` | SMTP server hostname | `smtp.gmail.com` |
| `SMTP_PORT` | SMTP server port | `587` |
| `SMTP_SECURE` | Use TLS (`true` for port 465) | `false` |
| `SMTP_USER` | SMTP authentication username | — |
| `SMTP_PASS` | SMTP authentication password (Gmail App Password) | — |
| `SMTP_FROM` | Default sender address | — |

---

## 🏃 Running Locally

### Development Mode (with hot reload)

```bash
npm run dev
```

### Production Mode

```bash
npm run build
npm start
```

---

## 🔌 Connecting to the Server

Remote HTTP MCP servers require a client that supports HTTP/SSE transport.

### 1. Connecting via Claude Desktop

Claude Desktop natively supports remote MCP servers. Add the server under the `mcpServers` object using the `sse` type:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "communication-remote": {
      "url": "https://your-app-name.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer your-optional-api-key"
      }
    }
  }
}
```

*Note: Replace `https://your-app-name.onrender.com/mcp` with your actual local or deployed URL (e.g. `http://localhost:3000/mcp` for local testing).*

### 2. Connecting via Cursor

Cursor supports connecting to remote MCP servers using the `SSE` server type:

1. Open Cursor **Settings** → **Features** → **MCP**.
2. Click **+ Add New MCP Server**.
3. Fill in the options:
   - **Name**: `communication-remote`
   - **Type**: `SSE`
   - **URL**: `https://your-app-name.onrender.com/mcp`

If you secured your server with an `API_KEY`, make sure you configure your client or URL to pass the authorization header or use URL query params like `https://your-app-name.onrender.com/mcp?api_key=your-key`.

### 3. Connecting via MCP Inspector

Verify your remote server's functionality visually using the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector http://localhost:3000/mcp
```
*(Add headers if API key authentication is enabled)*

---

## 🚢 Deployment to Render

The repository contains a `render.yaml` blueprint to quickly deploy this project as a **Web Service** on [Render](https://render.com).

1. Push your code to a Git repository (GitHub/GitLab).
2. Go to your [Render Dashboard](https://dashboard.render.com).
3. Click **New +** → **Blueprint**.
4. Select your connected repository.
5. Configure the environment variables (`SMTP_HOST`, `SMTP_USER`, `SMTP_PASS`, `API_KEY`, etc.) in the Render UI.
6. Click **Deploy**.

Render will build and deploy the application, setting up an HTTPS endpoint automatically (e.g. `https://communication-mcp-server.onrender.com`).

---

## 🔮 Future Improvements

- [ ] **SMS Integration** — Add SMS support via Twilio or other professional SMS API gateway.
- [ ] **Rate Limiting** — Add Express rate limiter middleware to prevent spam/abuse on the public route.
- [ ] **Persistent Session Stores** — Move active sessions from in-memory map to Redis to allow multi-instance auto-scaling.
- [ ] **JWT Authentication** — Implement OAuth2/JWT-based authorization for multi-tenant users.
- [ ] **Message History** — Database integration to track email history and delivery logs.

---

## 📄 License

MIT