# GitOps Safe MCP

A deliberately narrow stdio MCP server extracted from `spectrenet-mcp` commit `2e63f009d8f4642e17398685baef0251811d6637`. It exposes only:

- `repository_status`: Git status and five recent commits (read-only).
- `diff_summary`: unstaged diff statistics and working-tree names (read-only).
- `tofu_validate`: `tofu fmt -check -recursive` and `tofu validate -no-color`.
- `ansible_syntax`: one contained YAML playbook through a pinned/operator-managed `ansible-playbook --syntax-check` command.

There are **no** Git write, OpenTofu plan/apply, Ansible playbook-run, shell, or arbitrary-command tools.

## Important Ansible warning

**Ansible syntax-check is not guaranteed to be inert: lookup plugins and some collection/plugin loading can execute code while parsing a playbook.** Treat the configured repository and dependencies as trusted code. Run this server under a dedicated unprivileged account, with a scrubbed environment, read-only repository mount, no production credentials, and restricted network/filesystem access. The executable must be configured as an absolute operator-managed path (or an absolute operator-owned wrapper); it is never accepted from a tool argument.

## Safety boundaries

All configured child paths and requested playbooks are resolved (including symlinks), must be relative, must exist, and must remain strictly below their allowed resolved root. Every subprocess receives the same explicit minimal allowlist (`PATH`, basic user/locale/terminal/temp variables, and `XDG_*`); Ansible alone additionally receives the contained `ANSIBLE_CONFIG`. Unrelated process credentials, cloud tokens, and provider secrets are not inherited. Subprocesses use argv arrays, fixed verbs/flags, timeouts, and bounded stdout/stderr. Audit JSONL includes timestamp, UUID request ID, tool/target, non-mutating marker, exit code, timeout status, and duration—but not command output or environment values.

This is defense in depth, not a sandbox. See [Security](SECURITY.md) and [Architecture](docs/ARCHITECTURE.md).

## Install and run

Python 3.11+ and `uv` are recommended:

```sh
uv sync --extra test
cp .env.example .env.reference  # reference only; the package does not load dotenv files
uv run gitops-safe-mcp
```

Inject settings with a service manager or secret/configuration manager. Ensure the audit directory is writable only by the service/operator.

## Verify

```sh
uv run --extra test pytest
uv run python -m compileall -q src tests
uv build
```

Tests use temporary fake repositories and fake executables. They do not run OpenTofu or Ansible against real infrastructure.