Unified AI System: Self-Hosted AI Gateway & MCP Server

<p align="center"> <strong>Open-source AI gateway for deterministic prompt enhancement, governed execution, and reproducible verification.</strong> </p> <p align="center"> <a href="README.md">English</a> | <a href="README.zh-CN.md">zh-CN</a> | <a href="https://happy520ai.github.io/unified-ai-system/">Project Site</a> </p> <p align="center"> <a href="https://github.com/happy520ai/unified-ai-system"> <img alt="GitHub stars" src="https://img.shields.io/github/stars/happy520ai/unified-ai-system?style=flat-square&label=Stars" /> </a> <a href="https://github.com/happy520ai/unified-ai-system/actions/workflows/ci.yml"> <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/happy520ai/unified-ai-system/ci.yml?branch=master&style=flat-square&label=CI" /> </a> <a href="https://github.com/happy520ai/unified-ai-system/releases/latest"> <img alt="Release" src="https://img.shields.io/github/v/release/happy520ai/unified-ai-system?style=flat-square" /> </a> <img alt="Maturity: hardened Public Preview" src="https://img.shields.io/badge/maturity-hardened_Public_Preview-f59e0b?style=flat-square" /> <a href="https://registry.modelcontextprotocol.io/v0.1/servers/io.github.happy520ai%2Funified-ai-system/versions/0.8.0"> <img alt="Official MCP Registry: active" src="https://img.shields.io/badge/Official_MCP_Registry-active-1f883d?style=flat-square" /> </a> <a href="LICENSE"> <img alt="License" src="https://img.shields.io/github/license/happy520ai/unified-ai-system?style=flat-square" /> </a> </p>

🏆 Qloo Agentic Hackathon 2026 entry — TasteRouter: an AI agent that finds the neighbourhood that already loves your business idea, powered by Qloo Taste AI. Live demo: https://tasterouter.tasterouter.workers.dev · Code & docs

<p align="center"> <img src="docs/assets/readme-hero.png" alt="Unified AI System — self-hosted AI gateway: one governed boundary for models, agents, tools, budgets and evidence, with four release gates and zero credentials to start" width="100%" /> </p>

Unified AI System turns a rough request into a structured, reviewable prompt before execution. It gives teams one self-hosted surface for OpenAI-compatible SDKs, MCP, A2A, CLI, and HTTP while keeping provider calls explicit — with virtual keys and token budgets, exact response caching plus an opt-in lexical-approximate similarity layer, reverse MCP governance with REST→MCP generation, a terminal-first JSON operations overview, and operations-focused observability.

Where this README makes a claim about MCP servers in the wild, it is measured rather than asserted: nine measurements of the public MCP ecosystem (40 registry-advertised servers, asked anonymously, every page naming its own denominator) and the same results as machine-readable data (nine questions in ten measurement legs, 400 rows, 2026-09-28).

Current maturity: hardened Public Preview. The credential-free path is reproducible and CI-gated; production deployment still requires your own provider staging, HA/DR drills, security review, and operating evidence.

Try It in 60 Seconds

<p align="center"> <img src="docs/assets/readme-terminal.png" alt="Terminal proof: one docker run command prints the enhanced prompt with providerCalled=false evidence and exits clean" width="100%" /> </p>

Verify the project without signing in:

docker run --rm ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.8.0 pnpm gateway demo

On Apple Silicon, put --platform linux/amd64 before the image name. Both published arm64 tags - the gateway and the MCP server - carry x86-64 native modules, so this demo fails there today (#190, with the reading and the command that reproduces it).

No Docker daemon, or an Apple Silicon machine where the line above is known to fail? The same proof runs from a source checkout, and with dependencies already installed the demo itself takes seconds rather than minutes: the one run we captured measured 14.0 s of wall time on a single laptop, and that page says plainly it is one run, not a benchmark:

git clone https://github.com/happy520ai/unified-ai-system.git
cd unified-ai-system
corepack enable && pnpm install --frozen-lockfile    # prerequisites: Node 22.18.0+, pnpm 11.19.0
pnpm gateway demo "Build a small API for my team" --enhance --profile coding --evidence

Measured on this machine - Windows, Node v25.8.1, no Docker engine installed - exit 0, "mode": "fake", "providerCalled": false, "credentialRequired": false, 4,787 bytes, and three consecutive runs came out byte-identical. The install line in front of the demo is the part that is not sixty seconds; pnpm verify:public-clone, further down, is a longer optional check and not a prerequisite for this run.

Expected behavior:

• local fake-provider execution
• visible execution: fake
• deterministic output
• no API key or account needed
• container exits automatically

One-command natural-language enhancement preview:

docker run --rm ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.8.0 \
  pnpm gateway demo "Build a small API for my team" --enhance --profile coding --evidence

This starts an isolated fake-provider gateway, enhances the request locally, prints the structured prompt, and cleans up without an API key.

Check the tool roster of a published image without installing it (from a clone):

node tools/verify-image-roster.mjs 0.8.0

It reads MCP_TOOL_NAMES out of the container layer over plain HTTPS and verifies every blob against the digest its manifest names — no Docker daemon, no registry login. Expected: a line reading tools 15. The same command against 0.4.0 reports nine, so the number tracks the artifact rather than the prose written about it. The eight-tag history behind those counts — including why latest and 0.8.0 ship the same interface as different bytes — is in the image roster note.

Try Before Installing

<p align="center"> <a href="https://happy520ai.github.io/unified-ai-system/#enhance?prompt=Build+a+small+API+for+my+team&amp;profile=coding&amp;language=en"> <img src="docs/assets/prompt-enhancement-demo.png" alt="Unified AI System turns a rough request into a structured coding prompt" width="100%" /> </a> <br /> _{The original request stays visible. The local enhancer adds execution requirements, output requirements, and completion criteria.} </p>

Open a ready-to-run coding example in the browser Prompt Lab

The link loads a real request and renders the enhanced prompt locally. No account, API key, or provider call is required.

Run the same proof against the published container:

docker run --rm ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.8.0 pnpm gateway demo "Build a small API for my team" --enhance --profile coding --evidence

The evidence confirms that the original request was preserved, the result is deterministic, and providerCalled=false. Codex, VS Code, Claude Code, Gemini CLI, OpenCode, Cursor, Cline, Continue, and generic stdio clients can reach the same gateway through authenticated, permission-scoped MCP tools (15 in the current source build; inspect the tool list of your installed image). The source build also provides a protocol-tested MCP Streamable HTTP endpoint for clients that connect by URL.

Useful in a real workflow? Star the repository or share one reproducible result.

The Gateway at a Glance

<p align="center"> <img src="docs/assets/readme-architecture.png" alt="Architecture: OpenAI/Anthropic SDKs, MCP clients, A2A, CLI, and HTTP enter one gateway that adds prompt enhancement, virtual keys, exact cache with an optional semantic layer, reverse MCP governance, observability, and audit — providers stay behind a three-gate whitelist with the fake provider as the credential-free default" width="100%" /> <br /> _{Clients keep their native protocols; the gateway adds keys, budgets, cache, and audit. The published image exposes fifteen bounded MCP tools, matching the current source build; both are inspectable after connecting. Controlled writes additionally require Agent Governance when enabled.} </p>

Choose Your First Path

| Your goal | Start here | What you get | | --- | --- | --- | | Try it before installing | Browser Prompt Lab | A local, deterministic preview with no account or API key. | | See who has accepted it | Where this project is listed | Curated catalogues and public MCP directories that carry an entry today, each with the URL that proves it, re-probed nightly. | | Verify the published runtime | 60-second Docker demo | A disposable fake-provider run with visible evidence and cleanup. | | Connect an agent client | Codex and MCP quickstart | A pinned MCP container with an inspectable tool list. | | Choose a client path | MCP compatibility matrix | Install commands, first checks, and honest evidence boundaries. | | Integrate with an application | Prompt enhancement guide | CLI, HTTP, SDK, curl, Python, and JavaScript paths. | | Keep an existing OpenAI client | OpenAI-compatible API | Point baseURL at /v1 for Chat Completions, function tools, Responses, streaming, and model discovery. | | Connect another agent | A2A v1.0 gateway | Verify an optionally signed Agent Card/JWKS and run tenant-scoped tasks with bounded memory, same-host SQLite, or cross-host PostgreSQL state plus fenced execution leases. | | Check client runtime certification | Client runtime certification | Evidence-backed catalog state: 52 verified, 2,084 pending manual evidence, and 0 failed across 2,136 unique entries. | | Run the certification suites yourself | Client runtime certification | node tools/verify-client-runtimes-serial.mjs --client tag:mainstream for sequential reports, node tools/run-global-client-discovery.mjs --source-manifest docs/client-runtime-catalog-sources-worldwide.json --execute --serial --max 0 for global coverage, and add --require-manual-evidence --manual-evidence docs/client-runtime-evidence.example.json to fail on missing manual proof. | | Inspect the enhancement contract | Credential-free evaluation | Eight representative cases for profiles, languages, signals, determinism, and zero provider calls. | | Diagnose a first-run problem | Troubleshooting matrix | Shell-specific checks without exposing credentials. | | Verify an MCP client | MCP client report | Record one Codex, Cursor, Cline, or generic stdio run with a sm