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

flowchart LR
  ChatGPT -->|MCP JSON-RPC| API["FastAPI /mcp"]
  API --> Runtime["MCP Runtime"]
  Runtime --> AuditLens["AuditLens"]
  Runtime --> SiteLint["SiteLint"]
  Runtime --> ReleaseButler["Release Butler"]
  Runtime --> Policy["Policy + Risk Gate + Rate Limits"]
  Runtime --> Receipts["Receipts + Audit Logs"]
  Runtime --> ObjectStore["ObjectStore (Local or S3 Dual-Read)"]
  Runtime --> Jobs["JobStore"]
  Worker["Celery Worker"] --> SiteLint
  SiteLint --> Reports["Reports + Evidence"]
  ReleaseButler --> GitHub["GitHub API"]
  AuditLens --> GitHub
  API --> Metrics["/metrics"]

Support matrix

Quickstart (local)

1. Create env and install dependencies:

uv venv .venv
uv pip install --python .venv/bin/python -e '.[test]'

2. Configure environment:

cp .env.example .env

3. Bootstrap local data folders and key:

./scripts/bootstrap.sh

4. Run API:

PYTHONPATH=packages:apps:services .venv/bin/uvicorn mcp_server.main:app --host 0.0.0.0 --port 8080

Optional SiteLint browser stack:

./scripts/install_sitelint_toolchain.sh

5. Health check:

curl -s http://localhost:8080/healthz

Quickstart (Docker Compose)

cp .env.example .env
./scripts/bootstrap.sh
docker compose up --build

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:

OBJECT_STORE_BACKEND=local

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

OBJECT_STORE_BACKEND=s3
OBJECT_STORE_BUCKET=omniaudit
OBJECT_STORE_PREFIX=omniaudit
S3_ENDPOINT_URL=http://minio:9000
S3_FORCE_PATH_STYLE=true
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin

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:

curl -s http://localhost:8080/mcp -H 'Content-Type: application/json' -d '{
  "jsonrpc":"2.0",
  "id":1,
  "method":"tools/list",
  "params":{}
}'

Start site scan:

curl -s http://localhost:8080/mcp -H 'Content-Type: application/json' -d '{
  "jsonrpc":"2.0",
  "id":2,
  "method":"tools/call",
  "params":{
    "name":"sitelint.start_scan",
    "arguments":{
      "url":"https://example.com",
      "profile":"standard",
      "viewport_set":"desktop_mobile"
    }
  }
}'

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:

curl -s http://localhost:8080/mcp -H 'Content-Type: application/json' -d '{
  "jsonrpc":"2.0",
  "id":3,
  "method":"tools/call",
  "params":{
    "name":"releasebutler.generate_notes",
    "arguments":{
      "repo":"Prekzursil/AdrianaArt",
      "from_tag":"v1.0.0",
      "to_tag":"v2.0.0",
      "fallback_window":25
    }
  }
}'

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:

./scripts/smoke_hardening_pass2.sh

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:

LOG_FORMAT=json

Optional OTLP tracing:

OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318/v1/traces

Prometheus metrics:

PROMETHEUS_ENABLED=true

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

TMPDIR=/tmp TEMP=/tmp TMP=/tmp .venv/bin/pytest -q -s

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.