Metadata-Version: 2.4
Name: infra-mcp
Version: 0.1.0
Summary: Local stdio MCP server for read-only diagnosis of on-prem Linux VMs and PostgreSQL databases
Project-URL: Homepage, https://github.com/esp4ce/infra-mcp
Project-URL: Repository, https://github.com/esp4ce/infra-mcp
Author: esp4ce
License: MIT
Requires-Python: >=3.11
Requires-Dist: keyring>=24.0
Requires-Dist: mcp[cli]<2.0,>=1.28
Requires-Dist: paramiko<4,>=3.0
Requires-Dist: psycopg2-binary>=2.9
Requires-Dist: pydantic>=2.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: sshtunnel>=0.4
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# infra-mcp

A local **stdio MCP server** that gives an AI agent read-only visibility into
on-premise Linux VMs (SSH + journald) and PostgreSQL databases. The agent can
diagnose service failures, retrieve bounded logs, and check DB health without any
user terminal interaction.

v0.1 is deliberately **read-only**. Every remote operation is gated by:

- an **SSH command/service allowlist** (checked before any network call),
- a **SQL `SELECT` guard** + `READ ONLY` transaction,
- a **directory allowlist** for log-file access (with `..` traversal blocked),

and every executed remote command is written to an append-only **audit log**.

## Install

```bash
uv tool install infra-mcp
# or from source:
uv tool install -e /path/to/infra-probe
```

(`pip install infra-mcp` also works.)

## Configure

Copy [`infra-mcp.yaml.example`](infra-mcp.yaml.example) to
`~/.infra-mcp/infra-mcp.yaml` and edit it. Override the path with `--config` or
the `INFRA_MCP_CONFIG` environment variable.

Generate a starter config from your `~/.ssh/config`:

```bash
infra-mcp generate-config -o ~/.infra-mcp/infra-mcp.yaml
```

Create the read-only PostgreSQL role(s) (admin password is prompted, never stored):

```bash
infra-mcp setup
```

Check VM reachability:

```bash
infra-mcp test
```

## Run

```bash
infra-mcp run
# or: python -m infra_mcp run
```

Register it with your MCP client (Claude Code, Cursor, …) as a **stdio** server
whose command is `infra-mcp run`.

## Tools

| Tool | Purpose |
|------|---------|
| `list_vms` | All VMs with reachability + watched services (no IPs) |
| `get_infra_overview` | Service states + DB health for one VM in a single call |
| `get_service_status` | systemd state, uptime, last 5 log lines |
| `get_service_logs` | Bounded journald logs, filtered by severity |
| `get_log_file` | Last N lines of an allowed log file, optional grep |
| `get_db_status` | Connection counts, waiting locks, long-running query count |
| `query_db` | Bounded caller-supplied `SELECT` |
| `get_audit_log` | Recent entries from the local audit log |

All output is bounded at the source (hard cap 200 log lines, 100 DB rows) and
returned as plain text / compact TSV.

## Development

```bash
uv pip install -e ".[dev]"
pytest
ruff check .
```

Tests cover output bounding, the SQL guard, and the path/command allowlists — no
live VM or database required.
