# @erickwendel/ciphersuite-mcp

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that provides AES-256-CBC encryption and decryption tools, a resource describing the algorithm, and a ready-to-use prompt — all runnable directly inside VS Code Copilot Chat.

---

## What it does

| Capability | Name | Description |
|---|---|---|
| 🔧 Tool | `encrypt_message` | Encrypts any plain-text message with a passphrase |
| 🔧 Tool | `decrypt_message` | Decrypts a previously encrypted message with the same passphrase |
| 📄 Resource | `encryption://info` | Returns details about the algorithm, key derivation, and output format |
| 💬 Prompt | `encrypt_message_prompt` | Pre-built prompt that asks the agent to encrypt a message |

### How encryption works

- **Algorithm**: AES-256-CBC
- **Key derivation**: `scrypt(passphrase, fixedSalt, 32)` — you pass any passphrase string; the server derives a strong 32-byte key automatically
- **Output format**: `<IV in hex>:<ciphertext in hex>` — keep the full string to decrypt later
- **IV**: a fresh random 16-byte IV is generated on every encryption call, so the same message encrypted twice produces different output

---

## Prerequisites

- **Python 3.11+**
- [**uv**](https://docs.astral.sh/uv/) (recommended) or `pip`

---

## Installation

```bash
uv sync
```

or with `pip`:

```bash
pip install -e ".[dev]"
```

---

## Using in VS Code

### 1. Add the MCP server configuration

Create (or open) `.vscode/mcp.json` in your workspace and add:

```json
{
  "servers": {
    "ciphersuite-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "ciphersuite_mcp"]
    }
  }
}
```

> **Tip:** You can also add this server to your user-level MCP config at `~/.vscode/mcp.json` to make it available in every workspace.

### 2. Reload VS Code

Open the Command Palette (`Cmd+Shift+P`) and run **Developer: Reload Window** (or just restart VS Code).

### 3. Use it in Copilot Chat

Open Copilot Chat (Agent mode) and try:

```
Encrypt the message "Hello, World!" using the passphrase "my-secret-key"
```

```
Decrypt this message: a3f1...:<ciphertext> using the passphrase "my-secret-key"
```

```
Show me the encryption://info resource
```

The agent will automatically call the appropriate tool and return the result.

---

## Running the MCP Inspector

The MCP Inspector lets you explore and test all tools, resources, and prompts interactively in a browser UI:

```bash
npx @modelcontextprotocol/inspector uv run python -m ciphersuite_mcp
```

This opens the inspector at `http://localhost:5173` and connects it to the running server.

---

## Running tests

```bash
uv run pytest
```

The test suite covers:

- Encrypting a message
- Decrypting a message with the correct passphrase
- Error: decrypting with the wrong passphrase
- Listing the `encryption://info` resource
- Fetching the `encrypt_message_prompt`

---

## Project structure

```
src/ciphersuite_mcp/
  __init__.py
  __main__.py   # Entry point — connects the server to stdio transport
  server.py     # All tools, resources, and prompts are registered here
  service.py    # AES-256-CBC encryption/decryption logic
tests/
  conftest.py   # Shared MCP client fixture
  test_mcp.py
```

---

## Available commands

| Command | Description |
|---|---|
| `uv run python -m ciphersuite_mcp` | Start the server (used by MCP clients) |
| `uv run pytest` | Run all tests |
| `uv run pytest -k <expr>` | Run a subset of tests |
| `npx @modelcontextprotocol/inspector uv run python -m ciphersuite_mcp` | Open the MCP Inspector UI |