# Config Drift Guard MCP

A read-only Model Context Protocol server for comparing environment configuration without exposing detected secrets.

## Capabilities

- Parse `.env`, YAML, JSON, and Java Properties files.
- Normalize nested configuration into stable key paths.
- Detect added, removed, type-changed, value-changed, and secret-changed entries.
- Mask likely credentials, private keys, bearer tokens, and credential-bearing URLs.
- Restrict file access to explicitly allowed directories.
- Run entirely locally without network requests.

## Tools

### `inspect_config`

Parse one file and return normalized entries, value types, warnings, and protected values.

### `compare_configs`

Compare a baseline file with a target file and return drift items with risk levels.

### `scan_secrets`

Find likely plaintext secrets while returning only masks and SHA-256 fingerprints.

## Install

```bash
npm install
npm run build
```

Node.js 20 or later is required.

## Configure

Set `CONFIG_DRIFT_ALLOWED_ROOTS` to one or more directories. Use the operating system path delimiter (`;` on Windows, `:` on Linux and macOS).

```bash
# Windows PowerShell
$env:CONFIG_DRIFT_ALLOWED_ROOTS='D:\configs\dev;D:\configs\prod'
node dist/index.js
```

```bash
# Linux or macOS
CONFIG_DRIFT_ALLOWED_ROOTS=/srv/config/dev:/srv/config/prod node dist/index.js
```

If the variable is omitted, only the current working directory is allowed.

## MCP Client Configuration

```json
{
  "mcpServers": {
    "config-drift-guard": {
      "command": "node",
      "args": ["/absolute/path/config-drift-guard-mcp/dist/index.js"],
      "env": {
        "CONFIG_DRIFT_ALLOWED_ROOTS": "/absolute/path/configs"
      }
    }
  }
}
```

## Example

The repository includes `examples/dev.yaml` and `examples/prod.yaml`.

```text
compare_configs({
  "baselineFile": "/absolute/path/examples/dev.yaml",
  "targetFile": "/absolute/path/examples/prod.yaml"
})
```

The result distinguishes missing keys, type drift, ordinary value drift, and secret fingerprint changes. Detected secret plaintext is never returned.

## Paired Skill

`skills/config-drift-remediation` converts MCP evidence into:

- Expected-environment differences.
- Prioritized defects.
- Secret-rotation recommendations.
- Key-level patch guidance.
- A post-change verification checklist.

## Security Model

- Read-only tools.
- No network access.
- No expression or script execution.
- Maximum input file size of 5 MiB.
- Allowed-directory enforcement.
- Secret masks and one-way fingerprints only.
- No configuration plaintext logging.

## Development

```bash
npm test
npm run build
npm pack --dry-run
```

## License

MIT