OmniAudit

You run a single, self-hosted MCP connector that bundles three production modules for evidence triage, live URL auditing, and release asset checks. It exposes a central MCP endpoint at POST /mcp and includes a lightweight dashboard at GET /ui, enabling you to orchestrate multiple tools across your projects with policy controls, observability, and scalable storage.

How to use

You interact with the MCP endpoint to call, list, and manage tools such as AuditLens, SiteLint, and Release Butler. Use the provided HTTP or local runtime pathways to issue commands, enforce policy gates, and capture immutable receipts for all write operations. The built-in dashboard lets you monitor activity and results.

How to install

Prerequisites: you need Python and basic tooling for a local dev setup. The server is designed to run with Python and FastAPI-based endpoints.

Step-by-step local setup and run flow you can follow start from a clean environment.

# 1) Create a Python virtual environment
uv venv .venv

# 2) Install dependencies (including test extras if needed)
uv pip install --python .venv/bin/python -e '.[test]'

# 3) Configure environment (example; adjust to your setup)
cp .env.example .env

# 4) Bootstrap local data folders and key
./scripts/bootstrap.sh

# 5) Start the API (local development server)
PYTHONPATH=packages:apps:services .venv/bin/uvicorn mcp_server.main:app --host 0.0.0.0 --port 8080

Configuration and operation

Configuration covers storage backends, observability, and access controls. The server supports local and S3-compatible object storage, policy gates for write operations, rate limiting for submissions, and structured logging with optional telemetry.

Key environment and runtime details you will encounter include the following patterns.

Security and governance

Security features include per-repo allowlists, URL allowlists/denylists, a write-operation confirmation token gate, and rate limiting to prevent abuse. Receipts are appended to an audit log with immutable outputs and hashed inputs to preserve provenance.

Observability and destinations

Observability is baseline-first with structured logs, optional OTLP traces, and a Prometheus metrics endpoint. You can observe tool calls, latencies, and rate-limit denials through the metrics exposed by the server.

Examples and workflow notes

You can perform common workflows such as listing tools, starting a SiteLint scan, drafting issues with AuditLens, and generating release notes with Release Butler. The system supports a confirmation flow for write operations to ensure deliberate changes.

Live smoke and validation

A production-style smoke workflow validates dual-read from S3 with local refs and confirms that new assets write to S3 while existing references remain readable. It also exercises the release upload confirmation flow and checks that the metrics endpoint exposes hardening counters.

Release and asset handling

Release asset uploads can handle local file paths and provide per-file outcomes via uploaded_assets and failed_assets in the response, helping you verify asset integrity and reporting.

Quickstart (Docker Compose)

Use Docker Compose to spin up the MCP server with dependencies and the dashboard.

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

Quickstart (local)

Use the local run flow to boot and test the MCP server on your workstation.

cp .env.example .env
./scripts/bootstrap.sh
PYTHONPATH=packages:apps:services .venv/bin/uvicorn mcp_server.main:app --host 0.0.0.0 --port 8080

Troubleshooting

If you encounter health issues, verify the server is listening on the expected port and that the MCP endpoint is reachable. Check the health endpoint and logs for error details.

Available tools

tools/list

List available MCP tools across namespaces like auditlens, sitelint, and releasebutler.

tools/call

Invoke a specific MCP tool with arguments, including optional write-operation confirmation flows and policy gates.

releasebutler.generate_notes

Generate notes between tags with optional from_tag, to_tag, and fallback_window parameters.

releasebutler.create_release

Create a new release with local asset uploads and per-file outcome metadata.

auditlens.create_issue

Draft issues based on GitHub evidence with a structured confirmation flow.

sitelint.start_scan

Initiate a live URL audit and generate reports with optional profiling.