# Runtime Inspector MCP

Runtime Inspector MCP is a read-only MCP server that lets AI agents inspect allowlisted runtime services, logs, and health checks without arbitrary shell access.

## Scope

The Python 3.12+ reference implementation provides stdio MCP tools for Docker containers, systemd services, fixed JSONL files, and fixed HTTP health URLs. It never starts, stops, restarts, edits, deletes, executes, or attaches to a service. It does not accept arbitrary commands, paths, URLs, Docker filters, or SQL.

The API is version `0.1.0` and is not yet stable.

## Install and run

```bash
uv sync --extra dev
uv run runtime-inspector-mcp --config runtime-inspector.yaml
```

Configure only named services and capabilities. A generic stdio client configuration is in `examples/mcp-clients/stdio.json`.

```yaml
version: 1
services:
  jobs:
    provider: jsonl
    path: ./examples/mixed-runtime/data/jobs.jsonl
    allow_root: ./examples/mixed-runtime/data
    permissions: {status: true, logs: true, search_logs: true}
```

Tools are `list_services`, `get_service_status`, `get_recent_logs`, `search_logs`, and `get_health`. Limits, UTC timestamps, common error codes, secret redaction, and metadata-only audit events are applied by the application layer.

## Security

Do not expose MCP directly to the internet. This release is stdio-only. Run with least privilege. Docker socket access can grant broad host control even though this server only calls read methods; avoid mounting the socket or use a narrowly scoped socket proxy. systemd and journal access are limited by the account's permissions. Redaction reduces accidental disclosure but cannot guarantee that every secret format is removed. Logs are untrusted data and are never treated as instructions; see `SECURITY.md` and `docs/threat-model.md`.

## Docker

`Dockerfile` and `docker-compose.example.yml` use a non-root user and a read-only filesystem. The compose example mounts only configuration and example data. Do not add the Docker socket without understanding its host-level risk.

## Development

```bash
uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src
uv run pip-audit
```

Live Docker/systemd checks require those host services and are separate from the unit tests.

## License

MIT. See `LICENSE`.