@erickwendel/ciphersuite-mcp 0.0.1

package/.github/agents/developer.agent.md

@@ -0,0 +1,79 @@
+---
+description: Node.js + TypeScript coding agent. Implements features, fixes bugs, and refactors with test-driven discipline. Uses SOLID principles, dependency injection, and immutable patterns. LLM prompts in files, all external calls mocked in tests.
+tools: ['vscode', 'execute', 'read', 'edit', 'search', 'web', 'agent', 'context7/*', 'todo']
+---
+
+## Mission
+
+Make minimal, safe edits that are proven by tests.
+
+## Success Criteria
+
+A task is done when:
+0. Typescript types don't show errors / no warnings
+1. Relevant test file(s) pass
+2. Full test suite passes
+3. User acceptance criteria met
+
+## Scope
+
+**Will do:**
+- Implement features with tests
+- Fix bugs with regression tests
+- Refactor while preserving behavior
+- Integrate LLM features (prompts in files, mocked in tests)
+
+**Won't do:**
+- Introduce unsafe patterns (`eval`, shell injection, secrets in logs)
+- Proceed with ambiguous requirements (will ask questions first)
+- Add dependencies without justification
+- Reorganize files unless requested
+- Move Typescript types to separate files (keep types co-located, never create a types.ts)
+- Don't create index.ts files to re-export modules
+
+## Required User Inputs
+
+Ask if missing:
+- Acceptance criteria and expected behavior
+- Current vs expected behavior (for bugs)
+- Constraints (Node version, environment)
+
+## Core Principles
+
+### Code Design
+- **Immutability**: Pure functions, no mutations, side effects at edges
+- **Single Responsibility**: One clear purpose per module/function/file
+- **Dependency Injection**: Pass dependencies via constructors/parameters
+- **Type Safety**: Explicit types, avoid `any`, co-locate with code
+
+### Configuration
+- Store all env vars and static values in config files
+- No hardcoded values in business logic
+
+### LLM Integration
+- Prompts in files (`prompts/*.txt`), never inline
+- All LLM calls through injected interface (e.g., `LLMClient`)
+- Mock LLM responses deterministically in tests
+
+### Testing (Node.js test runner)
+- Use `node:test` with `node:assert/strict`
+- Use fixures files for case scenarios
+- Test the full pipeline end-to-end
+- Mock only external boundaries (HTTP, LLM, DB)
+- Run targeted tests first, then full suite
+
+### Security
+- Treat all input as untrusted
+- Validate and sanitize appropriately
+- Never log or expose secrets
+
+## Workflow
+
+For each task:
+1. **Plan**: Brief summary of what changes and why
+2. **Edit**: Minimal modifications to existing files
+3. **Test**: Add/update tests, run targeted suite
+4. **Verify**: Run full test suite
+5. **Summary**: Note tradeoffs or follow-ups
+
+Ask clarifying questions when behavior, security, or architecture is unclear.

package/.vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "ciphersuite-mcp": {
+      "command": "node",
+      "args": ["--experimental-strip-types", "/Users/erickwendel/Downloads/projetos/ewit/cursos/ia-devs/pos-grad/modulo03/projetos/04-mcps-do-zero/src/index.ts"]
+    }
+  }
+}

package/README.md

@@ -0,0 +1,150 @@
+# @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 ready-to-use prompts — 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 |
+| 💬 Prompt | `decrypt_message_prompt` | Pre-built prompt that asks the agent to decrypt 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
+
+- **Node.js v24+** (see `engines` in `package.json`)
+
+---
+
+## Installation
+
+```bash
+npm install
+```
+
+No build step is needed — the server runs TypeScript directly via Node.js native TypeScript support.
+
+---
+
+## Using in VS Code
+
+### 1. Add the MCP server configuration
+
+Create (or open) `.vscode/mcp.json` in your workspace and add:
+
+```json
+{
+  "mcpServers": {
+    "ciphersuite-mcp": {
+      "command": "node",
+      "args": ["--experimental-strip-types", "ABSOLUTE_PATH_TO_PROJECT/src/index.ts"]
+    }
+  }
+}
+```
+
+or via npm
+```json
+{
+  "mcpServers": {
+    "ciphersuite-mcp": {
+      "command": "npx",
+      "args": ["-y", "@erickwendel/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
+npm run mcp:inspect
+```
+
+This opens the inspector at `http://localhost:5173` and connects it to the running server.
+
+---
+
+## Running tests
+
+```bash
+# Run all tests once
+npm test
+
+# Run tests in watch mode (with debugger)
+npm run test:dev
+```
+
+The test suite covers:
+
+- Encrypting a message
+- Decrypting a message with the correct passphrase
+- Listing and reading the `encryption://info` resource
+- Fetching both prompts
+- Error: decrypting with the wrong passphrase
+- Error: decrypting a malformed ciphertext
+
+---
+
+## Project structure
+
+```
+src/
+  index.ts   # Entry point — connects the server to stdio transport
+  mcp.ts     # All tools, resources, and prompts are registered here
+tests/
+  mcp.test.ts
+```
+
+---
+
+## Available scripts
+
+| Script | Description |
+|---|---|
+| `npm start` | Start the server (used by MCP clients) |
+| `npm run dev` | Start with file-watch and Node.js inspector |
+| `npm test` | Run all tests |
+| `npm run test:dev` | Run tests in watch mode |
+| `npm run mcp:inspect` | Open the MCP Inspector UI |

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@erickwendel/ciphersuite-mcp",
+  "version": "0.0.1",
+  "description": "",
+  "main": "index.js",
+  "bin": {
+    "commit": "./src/index.ts"
+  },
+  "scripts": {
+    "start": "node src/index.ts",
+    "dev": "node --watch --inspect src/index.ts",
+    "test": "node --test tests/**/*.test.ts",
+    "mcp:inspect": "npx @modelcontextprotocol/inspector node src/index.ts",
+    "test:dev": "node --inspect --test --watch tests/**/*.test.ts",
+    "test:unit:dev": "node --inspect --test --watch tests/**/*unit.test.ts",
+    "test:unit": "node --inspect --test tests/**/*unit.test.ts",
+    "test:e2e:dev": "node --inspect --test --watch tests/**/*e2e.test.ts",
+    "test:e2e": "node --inspect --test tests/**/*e2e.test.ts"
+  },
+  "keywords": [],
+  "author": "erickwendel",
+  "license": "ISC",
+  "type": "module",
+  "engines": {
+    "node": "v24.14.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@types/node": "^24.11.0",
+    "zod": "^3.25.76"
+  }
+}

package/refs.txt

@@ -0,0 +1 @@
+https://modelcontextprotocol.io/docs/tools/inspector

package/src/index.ts

@@ -0,0 +1,13 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { server } from "./mcp.ts";
+
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Encrypt MCP Server running on stdio");
+}
+
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/src/mcp.ts

@@ -0,0 +1,168 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { randomBytes, createCipheriv, createDecipheriv, scryptSync } from 'node:crypto';
+import z from "zod";
+
+export const server = new McpServer({
+    name: "@erickwendel/ciphersuite-mcp",
+    version: "0.0.1",
+});
+
+
+// Fixed salt — same passphrase always derives the same key so decryption works across calls
+const SALT = 'mcp-encrypter-salt';
+
+function deriveKey(passphrase: string): Buffer {
+    return scryptSync(passphrase, SALT, 32);
+}
+
+function encrypt(text: string, key: string): string {
+    const iv = randomBytes(16);
+    const cipher = createCipheriv('aes-256-cbc', deriveKey(key), iv);
+    const encrypted = Buffer.concat([
+        cipher.update(Buffer.from(text, 'utf8')),
+        cipher.final(),
+    ]);
+    return `${iv.toString('hex')}:${encrypted.toString('hex')}`;
+}
+
+function decrypt(encryptedText: string, key: string): string {
+    const [ivHex, ...rest] = encryptedText.split(':');
+    const iv = Buffer.from(ivHex, 'hex');
+    const encrypted = Buffer.from(rest.join(':'), 'hex');
+    const decipher = createDecipheriv('aes-256-cbc', deriveKey(key), iv);
+    const decrypted = Buffer.concat([
+        decipher.update(encrypted),
+        decipher.final(),
+    ]);
+    return decrypted.toString('utf8');
+}
+
+
+server.registerTool(
+    "encrypt_message",
+    {
+        description: "Encrypt a message",
+        inputSchema: {
+            message: z.string().describe("The message to encrypt"),
+            encryptionKey: z.string().describe("Any passphrase to use for encryption — the server derives a strong key from it automatically"),
+        },
+        outputSchema: {
+            encryptedMessage: z.string().describe("The encrypted message (format: iv:ciphertext)"),
+        }
+    },
+    async ({ message, encryptionKey }) => {
+        try {
+            const encryptedMessage = encrypt(message, encryptionKey);
+            return {
+                content: [{ type: "text", text: encryptedMessage }],
+                structuredContent: { encryptedMessage },
+            };
+        } catch (err) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Failed to encrypt message! Check if the message and encryption key are correct. Error details: ${err instanceof Error ? err.message : String(err)}` }],
+            };
+        }
+    },
+);
+
+server.registerTool(
+    "decrypt_message",
+    {
+        description: "Decrypt a message that was encrypted with the encrypt_message tool",
+        inputSchema: {
+            encryptedMessage: z.string().describe("The encrypted message to decrypt (format: iv:ciphertext)"),
+            encryptionKey: z.string().describe("The same passphrase used during encryption"),
+        },
+        outputSchema: {
+            decryptedMessage: z.string().describe("The decrypted plain-text message"),
+        }
+    },
+    async ({ encryptedMessage, encryptionKey }) => {
+        try {
+            const decryptedMessage = decrypt(encryptedMessage, encryptionKey);
+            return {
+                content: [{ type: "text", text: decryptedMessage }],
+                structuredContent: { decryptedMessage },
+            };
+        } catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to decrypt message! Check if the encrypted message is correct and if the encryption key matches the one used for encryption. Error details: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+            };
+        }
+    },
+);
+
+server.registerResource(
+    "encryption://info",
+    "encryption://info",
+    { description: "Describes the encryption algorithm, key requirements, and output format used by this server." },
+    async () => ({
+        contents: [
+            {
+                uri: "encryption://info",
+                mimeType: "text/plain",
+                text: `
+Algorithm : AES-256-CBC
+Key derivation: scrypt (passphrase + fixed server salt → 32-byte key)
+Output format: <16-byte IV in hex>:<ciphertext in hex>  (separated by ":")
+Notes:
+  - Users pass any passphrase — the server derives a strong 32-byte key automatically using scrypt.
+  - A random IV is generated for every encryption — the same message encrypted twice will produce different output.
+  - Use the exact same passphrase to decrypt.
+  - Keep the full "iv:ciphertext" string to decrypt later.
+`.trim(),
+            },
+        ],
+    }),
+);
+
+server.registerPrompt(
+    "encrypt_message_prompt",
+    {
+        description: "Prompt to encrypt a plain-text message using the encrypt_message tool",
+        argsSchema: {
+            message: z.string().describe("The plain-text message to encrypt"),
+            encryptionKey: z.string().describe("Any passphrase — the server derives a strong key automatically"),
+        },
+    },
+    ({ message, encryptionKey }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Please encrypt the following message using the encrypt_message tool.\nMessage: ${message}\nEncryption key: ${encryptionKey}`,
+                },
+            },
+        ],
+    }),
+);
+
+server.registerPrompt(
+    "decrypt_message_prompt",
+    {
+        description: "Prompt to decrypt a message using the decrypt_message tool",
+        argsSchema: {
+            encryptedMessage: z.string().describe("The iv:ciphertext string to decrypt"),
+            encryptionKey: z.string().describe("The same passphrase used during encryption"),
+        },
+    },
+    ({ encryptedMessage, encryptionKey }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Please decrypt the following message using the decrypt_message tool.\nEncrypted message: ${encryptedMessage}\nEncryption key: ${encryptionKey}`,
+                },
+            },
+        ],
+    }),
+);

package/tests/helpers.ts

@@ -0,0 +1,19 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+
+export async function createTestClient () {
+  const transport = new StdioClientTransport({
+    command: 'node',
+    args: ['--experimental-strip-types', 'src/index.ts']
+  })
+
+  const client = new Client({
+    name: 'test-client',
+    version: '1.0.0'
+  }, {
+    capabilities: {}
+  })
+
+  await client.connect(transport)
+  return client
+}

package/tests/mcp.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, after, before } from 'node:test'
+import assert from 'node:assert'
+import { createTestClient,} from './helpers.ts'
+import { Client } from '@modelcontextprotocol/sdk/client'
+
+async function encryptMessage(client: Client, message: string, key: string) {
+ const result = await client.callTool({
+      name: "encrypt_message",
+      arguments: {
+        message,
+        encryptionKey: key
+      }
+    }) as unknown as { structuredContent: { encryptedMessage: string } }
+
+    return result
+}
+
+describe('MCP Tool Tests', async () => {
+  let client: Client;
+  let key: string;
+
+  before(async () => {
+    client = await createTestClient()
+    key = 'my-super-secret-passphrase';
+  })
+
+  after(async () => {
+    await client.close()
+  })
+
+  it('should encrypt a message', async () => {
+    const message = "Hello, World!"
+    const result = await encryptMessage(client, message, key)
+
+    assert.ok(result.structuredContent.encryptedMessage.length > 60, 'Encrypted message should not be empty')
+  })
+
+  it('should decrypt a message', async () => {
+
+    const message = "Hello, World!"
+    const encryptedMessage = (await encryptMessage(client, message, key)).structuredContent.encryptedMessage
+
+    const result = await client.callTool({
+      name: "decrypt_message",
+      arguments: {
+        encryptedMessage: encryptedMessage,
+        encryptionKey: key
+      }
+    }) as unknown as { structuredContent: { decryptedMessage: string } }
+
+    assert.strictEqual(result.structuredContent.decryptedMessage, message, 'Decrypted message should match original')
+  })
+
+  it('should list the encryption://info resource', async () => {
+    const { resources } = await client.listResources()
+    const info = resources.find(r => r.uri === 'encryption://info')
+    assert.ok(info, 'encryption://info resource should be listed')
+  })
+
+  it('should read the encryption://info resource', async () => {
+    const result = await client.readResource({ uri: 'encryption://info' })
+    const content = result.contents[0]
+    assert.ok(content, 'Resource should have content')
+    assert.ok('text' in content && typeof content.text === 'string' && content.text.includes('AES-256-CBC'), 'Resource should describe the algorithm')
+  })
+
+  it('should return the encrypt_message_prompt', async () => {
+    const result = await client.getPrompt({
+      name: 'encrypt_message_prompt',
+      arguments: { message: 'Secret text', encryptionKey: key }
+    })
+    const text = result.messages[0].content
+    assert.ok('text' in text && text.text.includes('encrypt_message'), 'Prompt should reference the encrypt_message tool')
+    assert.ok('text' in text && text.text.includes('Secret text'), 'Prompt should include the message')
+  })
+
+  it('should return the decrypt_message_prompt', async () => {
+    const encryptedMessage = (await encryptMessage(client, 'Prompt test', key)).structuredContent.encryptedMessage
+    const result = await client.getPrompt({
+      name: 'decrypt_message_prompt',
+      arguments: { encryptedMessage, encryptionKey: key }
+    })
+    const text = result.messages[0].content
+    assert.ok('text' in text && text.text.includes('decrypt_message'), 'Prompt should reference the decrypt_message tool')
+    assert.ok('text' in text && text.text.includes(encryptedMessage), 'Prompt should include the encrypted message')
+  })
+
+  it('should return isError when decrypting with wrong passphrase', async () => {
+    const encryptedMessage = (await encryptMessage(client, 'Secret', key)).structuredContent.encryptedMessage
+
+    const result = await client.callTool({
+      name: 'decrypt_message',
+      arguments: { encryptedMessage, encryptionKey: 'wrong-passphrase' }
+    }) as unknown as { isError: boolean; content: { type: string; text: string }[] }
+
+    assert.strictEqual(result.isError, true, 'Should return isError: true')
+    assert.ok(result.content[0].text.includes('Failed to decrypt'), 'Error message should describe the failure')
+  })
+
+  it('should return isError when decrypting a malformed message', async () => {
+    const result = await client.callTool({
+      name: 'decrypt_message',
+      arguments: { encryptedMessage: 'not-valid-ciphertext', encryptionKey: key }
+    }) as unknown as { isError: boolean; content: { type: string; text: string }[] }
+
+    assert.strictEqual(result.isError, true, 'Should return isError: true')
+    assert.ok(result.content[0].text.includes('Failed to decrypt'), 'Error message should describe the failure')
+  })
+})

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": [
+      "ES2022"
+    ],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "allowSyntheticDefaultImports": true,
+    "types": [
+      "node"
+    ]
+  },
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}