<div align="center">

# Marra Local Memory MCP

Secure local MCP server for encrypted memory files.

[![Languages](https://img.shields.io/badge/Languages-ENG%20%7C%20RU-2563eb?style=for-the-badge)](#languages)
[![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
[![npm](https://img.shields.io/badge/npm-11%2B-CB3837?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/)
[![MCP](https://img.shields.io/badge/Protocol-MCP-7c3aed?style=for-the-badge)](https://modelcontextprotocol.io/)
[![AES-256-GCM](https://img.shields.io/badge/Data-AES--256--GCM-0f766e?style=for-the-badge)](https://nodejs.org/api/crypto.html)
[![RSA-OAEP](https://img.shields.io/badge/Key%20Wrapping-RSA--OAEP--SHA256-0891b2?style=for-the-badge)](https://nodejs.org/api/crypto.html)

<p>
  <a href="#english">English</a> · <a href="#русский">Русский</a>
</p>

</div>

## Languages

`ENG` · [`English`](#english)<br>
`RU` · [`Русский`](#русский)

<a id="english"></a>

## English

### What it does

Marra Local Memory MCP is a local stdio MCP server for reading and updating a small allow-listed set of encrypted memory files.

It exposes exactly three tools:

- `memory_status` — returns encryption state and revisions;
- `memory_get` — decrypts and reads a registered memory file;
- `memory_update` — encrypts and atomically updates a file with revision locking.

### Requirements

- Windows
- Node.js 22 or newer
- npm 11 or newer

Check the installed versions:

```powershell
node --version
npm --version
```

### Installation

Open PowerShell in `MCP_tool`:

```powershell
npm install
npm run setup
```

`npm run setup` creates the local RSA key pair, encrypted files, and the local cache. The private key remains local and is excluded from Git.

### Start

Run the server over stdio:

```powershell
npm start
```

The server does not open an HTTP port. Your MCP client starts it as a child process.

The ready-to-use connection configuration is in [`mcp.json`](./mcp.json):

```json
{
  "mcpServers": {
    "marra-local-memory": {
      "command": "node",
      "args": ["D:\\Marra\\MCP_tool\\src\\server.js"],
      "cwd": "D:\\Marra\\MCP_tool"
    }
  }
}
```

Copy this configuration into the configuration file of your MCP client.

### Tool input

Read a registered file:

```json
{
  "file_id": "memory"
}
```

Update it using the current revision:

```json
{
  "file_id": "memory",
  "content": "New content",
  "expected_revision": 0
}
```

Allowed IDs are `memory` and `shared_data`. Stale writes return `REVISION_CONFLICT`; read the latest revision and retry the update.

### Security model

- Content is encrypted with AES-256-GCM.
- AES keys are wrapped with RSA-OAEP-SHA256.
- Tools accept registered `file_id` values only, never arbitrary paths.
- Absolute paths, `..`, symlinks, and arbitrary extensions are not exposed through the MCP API.
- Writes use atomic replacement and a local write queue.
- Private keys, encrypted runtime data, and decrypted cache files are excluded from Git.
- Never share or commit `storage/keys/private.pem`.

### Tests

```powershell
npm test
npm audit --omit=dev
```

<a id="русский"></a>

## Русский

Локальный stdio MCP-сервер для чтения и обновления зарегистрированных зашифрованных memory-файлов.

Доступны три инструмента:

- `memory_status` — состояние шифрования и ревизии;
- `memory_get` — расшифровка и чтение файла;
- `memory_update` — шифрование и атомарное обновление с проверкой ревизии.

### Установка и запуск

В PowerShell из папки `MCP_tool`:

```powershell
npm install
npm run setup
npm start
```

Конфигурация подключения находится в [`mcp.json`](./mcp.json). Скопируйте её в настройки MCP-клиента.

Разрешены только `file_id`: `memory` и `shared_data`. Произвольные пути, абсолютные пути и `..` не принимаются.

Данные шифруются AES-256-GCM, AES-ключи — RSA-OAEP-SHA256. Приватный ключ нельзя передавать или добавлять в Git.

### Проверка

```powershell
npm test
npm audit --omit=dev
```