# MCP server

`mcp_server.mjs` exposes the `m2pack` CLI as MCP tools over stdio.

This keeps the packing logic in the compiled CLI and uses MCP only as an
automation layer for bots and local tooling.

## Why this layout

- the C++ binary remains the single source of truth
- no duplicate archive logic in Python
- Linux-native development workflow
- works well with Codex, Claude Desktop, Inspector, and other MCP hosts

## Setup

```bash
cd /path/to/m2pack-secure
npm install
cmake -S . -B build
cmake --build build -j
npm run mcp
```

## Environment

- `M2PACK_BINARY`
  Use this when `m2pack` is not located at `build/m2pack`.

## Tool contract

### `pack_keygen`

Inputs:

- `out_dir`

### `pack_build`

Inputs:

- `input_dir`
- `output_archive`
- `key_file`
- `signing_secret_key_file`
- `key_id` optional

### `pack_diff`

Inputs:

- `left`
- `right`

### `pack_list`

Inputs:

- `archive`

### `pack_verify`

Inputs:

- `archive`
- `public_key_file` optional
- `key_file` optional

### `pack_extract`

Inputs:

- `archive`
- `output_dir`
- `key_file`

### `pack_export_client_config`

Inputs:

- `key_file`
- `public_key_file`
- `output_header`
- `key_id` optional

### `pack_export_runtime_key`

Inputs:

- `key_file`
- `public_key_file`
- `output_file`
- `key_id` optional
- `format` optional, `json` or `blob`

### `pack_binary_info`

No input. Returns the active `m2pack` binary path.

## Smoke test

Run a local roundtrip test with the bundled Node MCP client:

```bash
npm run mcp:smoke
```

That test:

- spawns `mcp_server.mjs`
- connects over stdio
- lists tools
- calls `pack_binary_info`

## Python variant

The repo also contains a Python FastMCP server for teams that prefer Python for
agent tooling.

Setup:

```bash
python3 -m venv .venv-mcp
. .venv-mcp/bin/activate
pip install -r requirements-mcp.txt
```

Run:

```bash
python mcp_server.py
```

Smoke test:

```bash
python scripts/mcp_smoke_test.py
```

## Claude Desktop style config example

```json
{
  "mcpServers": {
    "m2pack-secure": {
      "command": "node",
      "args": ["/absolute/path/to/m2pack-secure/mcp_server.mjs"],
      "env": {
        "M2PACK_BINARY": "/absolute/path/to/m2pack-secure/build/m2pack"
      }
    }
  }
}
```