infra-mcp 0.1.0__tar.gz

infra_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing (OIDC)
+      contents: read   # required for actions/checkout on private repos
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Check distributions
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

infra_mcp-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+docs/
+specs/
+CLAUDE.md
+SKILL.md
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+*.log
+.env*
+.DS_Store
+Thumbs.db
+infra-mcp.yaml
+infra-mcp.discovered.yaml
+!infra-mcp.yaml.example
+.claude/
+.idea/
+.specify/
+_demo.py

infra_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+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.

infra_mcp-0.1.0/README.md

@@ -0,0 +1,85 @@
+# 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.

infra_mcp-0.1.0/infra-mcp.yaml.example

@@ -0,0 +1,45 @@
+# infra-mcp configuration — single source of truth (plain text).
+# Copy to ~/.infra-mcp/infra-mcp.yaml and edit. Manage file permissions yourself
+# (e.g. chmod 600). Override the location with the INFRA_MCP_CONFIG env var or
+# the --config / -c CLI flag.
+
+# Local audit log location (append-only JSONL). Optional.
+audit_log_path: ~/.infra-mcp/audit.jsonl
+
+# Application log level (NOT the audit log). Optional. Default: WARNING.
+log_level: WARNING
+
+# At least one VM is required.
+vms:
+  - name: vm-med-files          # logical name, lowercase-kebab, starts with a letter
+    host: 192.168.1.10          # SSH hostname or IP (never exposed to the agent)
+    user: deploy                # SSH username
+    # SSH auth: provide key_path OR password (at least one).
+    key_path: ~/.ssh/id_rsa     # path to SSH private key
+    # password: "secret"        # plain-text SSH password (alternative to key_path)
+    # Per-VM known_hosts override. Optional; falls back to ~/.ssh/known_hosts.
+    known_hosts_file: ~/.ssh/known_hosts
+
+    # Watched systemd units. This list is the ALLOWLIST for service tool calls —
+    # a service not listed here is rejected before any SSH connection is made.
+    services:
+      - karaf
+      - haproxy
+
+    # Allowed directories for get_log_file. Must be ABSOLUTE paths. A requested
+    # path (after `..` normalization) must resolve inside one of these.
+    log_dirs:
+      - /var/log/karaf
+      - /var/log/haproxy
+
+    # PostgreSQL databases on this VM (connection is local to the VM).
+    databases:
+      - name: prod-db           # logical name, globally unique across all VMs
+        db_name: medfiles       # actual PostgreSQL database name
+        user: infra_readonly    # read-only role (created by `infra-mcp setup`)
+        # Read-only role password. Use the sentinel "keyring" to load it from the
+        # system keychain instead (stored under service "infra-mcp", key = name).
+        password: "keyring"
+        host: localhost         # optional, default localhost
+        port: 5432              # optional, default 5432
+        slow_query_ms: 1000     # optional, default 1000; threshold for "long-running"

infra_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "infra-mcp"
+version = "0.1.0"
+description = "Local stdio MCP server for read-only diagnosis of on-prem Linux VMs and PostgreSQL databases"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "esp4ce" }]
+dependencies = [
+    "mcp[cli]>=1.28,<2.0",
+    "paramiko>=3.0,<4",  # sshtunnel 0.4 (unmaintained) references paramiko.DSSKey, removed in paramiko 4
+    "psycopg2-binary>=2.9",
+    "sshtunnel>=0.4",
+    "pydantic>=2.11",
+    "pyyaml>=6.0",
+    "typer>=0.12",
+    "keyring>=24.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/esp4ce/infra-mcp"
+Repository = "https://github.com/esp4ce/infra-mcp"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[project.scripts]
+infra-mcp = "infra_mcp.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/infra_mcp"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

infra_mcp-0.1.0/src/infra_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""infra-mcp: read-only MCP server for on-prem VM and PostgreSQL diagnosis."""
+
+__version__ = "0.1.0"

infra_mcp-0.1.0/src/infra_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Enable `python -m infra_mcp`."""
+
+from infra_mcp.cli import app
+
+if __name__ == "__main__":
+    app()

infra_mcp-0.1.0/src/infra_mcp/audit.py

@@ -0,0 +1,28 @@
+"""Append-only JSONL audit writer. One line per remote command."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _now_iso() -> str:
+    """ISO-8601 UTC timestamp, e.g. 2026-06-17T14:22:01Z."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def log_command(audit_log_path: Path, target: str, cmd: str, exit_code: int) -> None:
+    """Append one audit entry. Creates the parent directory if needed."""
+    audit_log_path.parent.mkdir(parents=True, exist_ok=True)
+    entry = {"ts": _now_iso(), "target": target, "cmd": cmd, "exit_code": exit_code}
+    with audit_log_path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(entry, separators=(",", ":")) + "\n")
+
+
+def read_tail(audit_log_path: Path, lines: int) -> list[str]:
+    """Return the last `lines` audit entries, oldest first. Empty if no log yet."""
+    if not audit_log_path.exists():
+        return []
+    all_lines = audit_log_path.read_text(encoding="utf-8").splitlines()
+    return [ln for ln in all_lines if ln.strip()][-lines:]

infra_mcp-0.1.0/src/infra_mcp/cli.py

@@ -0,0 +1,126 @@
+"""Typer CLI: run / setup / generate-config / test subcommands."""
+
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from infra_mcp.config import load_config
+from infra_mcp.errors import InfraMcpError
+
+app = typer.Typer(add_completion=False, help="Read-only infra diagnosis MCP server.")
+
+_ConfigOpt = typer.Option(None, "--config", "-c", help="Path to infra-mcp.yaml")
+
+
+@app.command()
+def run(config: Optional[Path] = _ConfigOpt) -> None:
+    """Start the stdio MCP server."""
+    from infra_mcp import server
+
+    try:
+        server.init_config(config)
+    except InfraMcpError as e:
+        typer.echo(f"ERROR: {e}", err=True)
+        raise typer.Exit(1) from e
+    server.mcp.run(transport="stdio")
+
+
+@app.command()
+def setup(config: Optional[Path] = _ConfigOpt) -> None:
+    """Scan VMs, detect PostgreSQL, and create read-only roles. Idempotent."""
+    from infra_mcp import setup as setup_mod
+
+    try:
+        cfg = load_config(config)
+    except InfraMcpError as e:
+        typer.echo(f"ERROR: {e}", err=True)
+        raise typer.Exit(1) from e
+    results = setup_mod.run_setup(cfg)
+    for name, ok, msg in results:
+        mark = "OK " if ok else "FAIL"
+        typer.echo(f"[{mark}] {name}: {msg}")
+    if any(not ok for _, ok, _ in results):
+        raise typer.Exit(1)
+
+
+@app.command(name="generate-config")
+def generate_config(
+    output: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write to this path instead of stdout"
+    ),
+) -> None:
+    """Discover VMs from ~/.ssh/config and write a starter infra-mcp.yaml."""
+    from infra_mcp import setup as setup_mod
+
+    yaml_text = setup_mod.generate_config()
+    if output is None:
+        typer.echo(yaml_text)
+    else:
+        output.expanduser().parent.mkdir(parents=True, exist_ok=True)
+        output.expanduser().write_text(yaml_text, encoding="utf-8")
+        typer.echo(f"Wrote {output}")
+
+
+@app.command()
+def discover(
+    config: Optional[Path] = _ConfigOpt,
+    output: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write enriched YAML here (default: stdout)"
+    ),
+    in_place: bool = typer.Option(
+        False, "--in-place", "-i", help="Overwrite the loaded config file in place"
+    ),
+) -> None:
+    """Connect to each configured VM and refresh services / log_dirs / databases."""
+    from infra_mcp import setup as setup_mod
+
+    try:
+        cfg = load_config(config)
+    except InfraMcpError as e:
+        typer.echo(f"ERROR: {e}", err=True)
+        raise typer.Exit(1) from e
+    yaml_text = setup_mod.discover_config(cfg)
+    target = config if (in_place and config) else output
+    if target is None:
+        typer.echo(yaml_text)
+    else:
+        target.expanduser().parent.mkdir(parents=True, exist_ok=True)
+        target.expanduser().write_text(yaml_text, encoding="utf-8")
+        typer.echo(f"Wrote {target}")
+
+
+@app.command()
+def test(config: Optional[Path] = _ConfigOpt) -> None:
+    """Attempt an SSH reachability check against each configured VM."""
+    from infra_mcp import ssh
+
+    try:
+        cfg = load_config(config)
+    except InfraMcpError as e:
+        typer.echo(f"ERROR: {e}", err=True)
+        raise typer.Exit(1) from e
+    any_unreachable = False
+    for vm in cfg.vms:
+        start = time.monotonic()
+        reachable = ssh.is_reachable(vm)
+        latency_ms = int((time.monotonic() - start) * 1000)
+        if reachable:
+            typer.echo(f"[OK ] {vm.name}: reachable ({latency_ms} ms)")
+        else:
+            any_unreachable = True
+            typer.echo(f"[FAIL] {vm.name}: unreachable")
+    if any_unreachable:
+        raise typer.Exit(1)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    sys.exit(app())

infra_mcp-0.1.0/src/infra_mcp/config.py

@@ -0,0 +1,153 @@
+"""Pydantic config models for infra-mcp.yaml + fail-fast load_config()."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field, ValidationError, field_validator, model_validator
+
+from infra_mcp.errors import ConfigError
+
+_NAME_PATTERN = r"^[a-z][a-z0-9-]*$"
+_KEYRING_SENTINEL = "keyring"
+
+
+class DatabaseConfig(BaseModel):
+    """One PostgreSQL database, embedded under its VM."""
+
+    name: str = Field(pattern=_NAME_PATTERN)
+    db_name: str
+    user: str
+    password: str
+    host: str = "localhost"
+    port: int = 5432
+    slow_query_ms: int = 1000
+
+    # SSH coordinates of the parent VM, stamped at load time by VMConfig so DB
+    # tools can open an ephemeral tunnel without a separate persistent connection.
+    ssh_host: str | None = None
+    ssh_user: str | None = None
+    ssh_password: str | None = None
+    ssh_key_path: Path | None = None
+    ssh_known_hosts_file: Path | None = None
+
+    @field_validator("slow_query_ms")
+    @classmethod
+    def _positive_threshold(cls, v: int) -> int:
+        if v <= 0:
+            raise ValueError("slow_query_ms must be > 0")
+        return v
+
+
+class VMConfig(BaseModel):
+    """One logical VM entry."""
+
+    name: str = Field(pattern=_NAME_PATTERN)
+    host: str
+    user: str
+    key_path: Path | None = None
+    password: str | None = None
+    known_hosts_file: Path | None = None
+
+    @model_validator(mode="after")
+    def _require_auth(self) -> "VMConfig":
+        if self.key_path is None and self.password is None:
+            raise ValueError(
+                f"VM {self.name}: provide key_path or password for SSH auth"
+            )
+        return self
+    services: list[str] = Field(default_factory=list)
+    # Remote (Linux) directories — validated as POSIX absolute paths, NOT local
+    # OS paths, so they work when the server runs on Windows/macOS.
+    log_dirs: list[str] = Field(default_factory=list)
+    databases: list[DatabaseConfig] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _stamp_db_ssh(self) -> "VMConfig":
+        for db in self.databases:
+            db.ssh_host = self.host
+            db.ssh_user = self.user
+            db.ssh_password = self.password
+            db.ssh_key_path = self.key_path
+            db.ssh_known_hosts_file = self.known_hosts_file
+        return self
+
+    @field_validator("log_dirs")
+    @classmethod
+    def _abs_log_dirs(cls, v: list[str]) -> list[str]:
+        for d in v:
+            if not d.startswith("/"):
+                raise ValueError(f"log_dirs entry must be an absolute path: {d}")
+        return v
+
+
+class InfraMcpConfig(BaseModel):
+    """Top-level config file model."""
+
+    vms: list[VMConfig] = Field(min_length=1)
+    audit_log_path: Path = Path("~/.infra-mcp/audit.jsonl").expanduser()
+    log_level: str = "WARNING"
+
+    @model_validator(mode="after")
+    def _unique_db_names(self) -> InfraMcpConfig:
+        seen: set[str] = set()
+        for vm in self.vms:
+            for db in vm.databases:
+                if db.name in seen:
+                    raise ValueError(f"duplicate database name across VMs: {db.name}")
+                seen.add(db.name)
+        return self
+
+    def find_vm(self, name: str) -> VMConfig | None:
+        return next((vm for vm in self.vms if vm.name == name), None)
+
+    def find_db(self, name: str) -> tuple[VMConfig, DatabaseConfig] | None:
+        for vm in self.vms:
+            for db in vm.databases:
+                if db.name == name:
+                    return vm, db
+        return None
+
+
+def _resolve_keyring_passwords(config: InfraMcpConfig) -> None:
+    """Replace the `keyring` sentinel with the credential from the system keychain."""
+    import keyring
+
+    for vm in config.vms:
+        for db in vm.databases:
+            if db.password == _KEYRING_SENTINEL:
+                secret = keyring.get_password("infra-mcp", db.name)
+                if secret is None:
+                    raise ConfigError(
+                        f"database {db.name} uses keyring but no credential found "
+                        f"under infra-mcp:{db.name}"
+                    )
+                db.password = secret
+
+
+def default_config_path() -> Path:
+    """Resolve config path from INFRA_MCP_CONFIG or the default location."""
+    env = os.environ.get("INFRA_MCP_CONFIG")
+    if env:
+        return Path(env).expanduser()
+    return Path("~/.infra-mcp/infra-mcp.yaml").expanduser()
+
+
+def load_config(path: Path | None = None) -> InfraMcpConfig:
+    """Load and validate config. Raises ConfigError on any failure (fail fast)."""
+    cfg_path = Path(path) if path is not None else default_config_path()
+    if not cfg_path.exists():
+        raise ConfigError(f"config file not found: {cfg_path}")
+    try:
+        raw = yaml.safe_load(cfg_path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as e:
+        raise ConfigError(f"invalid YAML in {cfg_path}: {e}") from e
+    try:
+        config = InfraMcpConfig.model_validate(raw)
+    except ValidationError as e:
+        raise ConfigError(f"config validation failed: {e}") from e
+    config.audit_log_path = config.audit_log_path.expanduser()
+    _resolve_keyring_passwords(config)
+    return config