OmniAudit MCP Server

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>//<sha256>...
• existing local file refs continue to resolve via fallback reads
• no migration is required for existing receipt `result_re