OmniAudit MCP

Single self-hosted MCP connector that ships three production modules:

• AuditLens (auditlens.*): GitHub PR/run evidence triage and issue drafting.

• SiteLint (sitelint.*): live URL audit and report generation.

• Release Butler (releasebutler.*): release asset checksums and release-note workflows.

It exposes one MCP endpoint at POST /mcp and includes a lightweight dashboard at GET /ui.

Features implemented

• MCP tools across all required namespaces (auditlens, sitelint, releasebutler, core).

• Backward-compatible releasebutler.generate_notes extensions:

  • optional from_tag

  • optional to_tag

  • optional fallback_window

• releasebutler.create_release local file asset upload (assets[]) with per-file outcome metadata:

  • uploaded_assets[]

  • failed_assets[]

• Object storage hardening:

  • local backend

  • s3 backend with dual-read behavior (new writes to S3, legacy local refs still readable)

• Policy controls:

  • repo write allowlist

  • URL allowlist/denylist

  • write-operation confirmation token gate

  • rate limiting for scan submissions and GitHub writes

• Receipt-first write operations with immutable output references.

• Append-only audit log storage with hashed tool inputs.

• Observability baseline:

  • structured logs (LOG_FORMAT=json|plain)

  • optional OTLP traces (OTEL_ENABLED=true)

  • Prometheus /metrics endpoint (PROMETHEUS_ENABLED=true)

• GitHub auth providers:

  • fine-grained PAT

  • GitHub App installation token flow

• S3/MinIO-compatible object storage support for artifacts and reports.

• SQL storage for jobs, receipts, audit logs, and secret records.

Repository layout

• apps/mcp_server - FastAPI MCP server and dashboard endpoints

• packages/omniaudit - domain modules, runtime, security, storage

• services/worker - Celery worker and async SiteLint task

• tests - unit + integration tests

• infra - Dockerfiles

Architecture diagram

Support matrix

Quickstart (local)

1. Create env and install dependencies:

2. Configure environment:

3. Bootstrap local data folders and key:

4. Run API:

Optional SiteLint browser stack:

5. Health check:

Quickstart (Docker Compose)

API endpoint: http://localhost:8080/mcp Metrics endpoint: http://localhost:8080/metrics

ChatGPT Connector setup

In ChatGPT Developer Mode connector modal:

• Name: OmniAudit MCP

• MCP Server URL: https://<your-host>/mcp

• Authentication:

  • set to None if MCP_AUTH_MODE=none

  • set to API key flow if you enable MCP_AUTH_MODE=api_key

Storage backend modes

Default mode is local:

S3/MinIO mode with dual-read, S3-write:

Behavior in s3 mode:

• new immutable objects are written to s3://<bucket>/<prefix>/<sha256>...

• existing local file refs continue to resolve via fallback reads

• no migration is required for existing receipt result_ref values

MCP examples

List tools:

Start site scan:

Write operation risk gate flow (auditlens.create_issue):

1. Call without confirmation_token and read structuredContent.confirmation_token.

2. Repeat call with that token to execute write and receive receipt_id.

Generate tag-to-tag notes:

Create release with local assets (confirmation flow):

1. First call releasebutler.create_release without confirmation_token.

2. Re-call with returned confirmation_token and local file paths in assets[].

3. Inspect uploaded_assets and failed_assets in structuredContent.

Live smoke workflow

Run production-style dual-read/S3-write smoke checks locally:

Outputs:

• artifacts/smoke/<timestamp>/summary.json

• artifacts/smoke/<timestamp>/responses/*.json

Key assertions:

• legacy local refs remain readable after switching to S3 backend

• new writes become s3://...

• release upload confirmation flow succeeds with local assets

• metrics endpoint exposes hardening counters

Observability

Structured logging:

Optional OTLP tracing:

Prometheus metrics:

Exposed series include:

• omniaudit_tool_calls_total{tool,status}

• omniaudit_tool_latency_seconds{tool}

• omniaudit_write_gate_denied_total{tool}

• omniaudit_rate_limit_denied_total{bucket}

Tests

Notes

• sitelint.start_scan runs inline by default for deterministic single-user behavior.

• Set SITELINT_ASYNC_MODE=true and run worker service to process scan jobs via Celery.

• GitHub API operations require valid credentials in .env.

• In Docker + MinIO setups, keep S3_FORCE_PATH_STYLE=true for compatibility.

• For roadmap and release-note policy, see docs/ROADMAP.md and docs/CHANGELOG_POLICY.md.

See docs/ARCHITECTURE.md and docs/OPERATIONS.md for details.