{
  "markdown": "# Unified AI System: Self-Hosted AI Gateway & MCP Server\n\n<p align=\"center\">\n  <strong>Open-source AI gateway for deterministic prompt enhancement, governed execution, and reproducible verification.</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"README.md\">English</a> |\n  <a href=\"README.zh-CN.md\">zh-CN</a> |\n  <a href=\"https://happy520ai.github.io/unified-ai-system/\">Project Site</a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/happy520ai/unified-ai-system\">\n    <img alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/happy520ai/unified-ai-system?style=flat-square&label=Stars\" />\n  </a>\n  <a href=\"https://github.com/happy520ai/unified-ai-system/actions/workflows/ci.yml\">\n    <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\" />\n  </a>\n  <a href=\"https://github.com/happy520ai/unified-ai-system/releases/latest\">\n    <img alt=\"Release\" src=\"https://img.shields.io/github/v/release/happy520ai/unified-ai-system?style=flat-square\" />\n  </a>\n  <img alt=\"Maturity: hardened Public Preview\" src=\"https://img.shields.io/badge/maturity-hardened_Public_Preview-f59e0b?style=flat-square\" />\n  <a href=\"https://registry.modelcontextprotocol.io/v0.1/servers/io.github.happy520ai%2Funified-ai-system/versions/0.7.0\">\n    <img alt=\"Official MCP Registry: active\" src=\"https://img.shields.io/badge/Official_MCP_Registry-active-1f883d?style=flat-square\" />\n  </a>\n  <a href=\"LICENSE\">\n    <img alt=\"License\" src=\"https://img.shields.io/github/license/happy520ai/unified-ai-system?style=flat-square\" />\n  </a>\n</p>\n\n<p align=\"center\">\n  <img\n    src=\"docs/assets/readme-hero.png\"\n    alt=\"Unified AI System — self-hosted AI gateway with 12 governed MCP tools, four release gates, 23 defended attack cases, and zero credentials to start\"\n    width=\"100%\"\n  />\n</p>\n\nUnified 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.\n\n> **Current maturity:** hardened **Public Preview**. The credential-free path is\n> reproducible and CI-gated; production deployment still requires your own\n> provider staging, HA/DR drills, security review, and operating evidence.\n\n## Try Before Installing\n\n<p align=\"center\">\n  <a href=\"https://happy520ai.github.io/unified-ai-system/#enhance?prompt=Build+a+small+API+for+my+team&amp;profile=coding&amp;language=en\">\n    <img\n      src=\"docs/assets/prompt-enhancement-demo.png\"\n      alt=\"Unified AI System turns a rough request into a structured coding prompt\"\n      width=\"100%\"\n    />\n  </a>\n  <br />\n  <sub>The original request stays visible. The local enhancer adds execution requirements, output requirements, and completion criteria.</sub>\n</p>\n\n[**Open a ready-to-run coding example in the browser Prompt Lab**](https://happy520ai.github.io/unified-ai-system/#enhance?prompt=Build+a+small+API+for+my+team&profile=coding&language=en)\n\nThe link loads a real request and renders the enhanced prompt locally. No\naccount, API key, or provider call is required.\n\nRun the same proof against the published container:\n\n```bash\ndocker run --rm ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.7.0 pnpm gateway demo \"Build a small API for my team\" --enhance --profile coding --evidence\n```\n\nThe evidence confirms that the original request was preserved, the result is\ndeterministic, and `providerCalled=false`. Codex, VS Code, Claude Code, Gemini\nCLI, OpenCode, Cursor, Cline, Continue, and generic stdio clients can reach the\nsame gateway through twelve governed MCP tools. The source build also provides a\nprotocol-tested MCP Streamable HTTP endpoint for clients that connect by URL.\n\nUseful in a real workflow? [Star the repository](https://github.com/happy520ai/unified-ai-system) or [share one reproducible result](https://github.com/happy520ai/unified-ai-system/issues/new?template=usage-verification-report.yml&title=%5BUsage%20Report%5D%20Quickstart).\n\n## The Gateway at a Glance\n\n<p align=\"center\">\n  <img\n    src=\"docs/assets/readme-architecture.png\"\n    alt=\"Architecture: OpenAI/Anthropic SDKs, MCP clients, A2A, CLI, and HTTP enter one gateway that adds prompt enhancement, virtual keys, exact + semantic cache, reverse MCP governance, observability, and audit — providers stay behind a three-gate whitelist with the fake provider as the credential-free default\"\n    width=\"100%\"\n  />\n  <br />\n  <sub>Clients keep their native protocols; the gateway adds keys, budgets, cache, and audit. Twelve governed MCP tools are inspectable from any MCP client.</sub>\n</p>\n\n## Choose Your First Path\n\n| Your goal | Start here | What you get |\n| --- | --- | --- |\n| Try it before installing | [Browser Prompt Lab](https://happy520ai.github.io/unified-ai-system/#enhance) | A local, deterministic preview with no account or API key. |\n| Verify the published runtime | [60-second Docker demo](#try-it-in-60-seconds) | A disposable fake-provider run with visible evidence and cleanup. |\n| Connect an agent client | [Codex and MCP quickstart](https://happy520ai.github.io/unified-ai-system/codex-mcp-docker-quickstart.html) | A pinned MCP container and twelve inspectable tools. |\n| Choose a client path | [MCP compatibility matrix](docs/mcp-client-compatibility.md) | Install commands, first checks, and honest evidence boundaries. |\n| Integrate with an application | [Prompt enhancement guide](https://happy520ai.github.io/unified-ai-system/prompt-enhancement.html) | CLI, HTTP, SDK, curl, Python, and JavaScript paths. |\n| Keep an existing OpenAI client | [OpenAI-compatible API](docs/openai-compatible-api.md) | Point `baseURL` at `/v1` for Chat Completions, function tools, Responses, streaming, and model discovery. |\n| Connect another agent | [A2A v1.0 gateway](docs/a2a-protocol.md) | 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. |\n| Check client runtime certification | [Client runtime certification](docs/client-runtime-certification.md) | Current evidence-backed catalog state: 52 verified, 2,084 pending manual evidence, and 0 failed across 2,136 unique entries. |\n| Run mainstream certification one-by-one | [Client runtime certification](docs/client-runtime-certification.md) | Run `node tools/verify-client-runtimes-serial.mjs --client tag:mainstream` for sequential reports and explicit manual evidence states. |\n| Run global protocol coverage | [Client runtime certification](docs/client-runtime-certification.md) | Run `node tools/run-global-client-discovery.mjs --source-manifest docs/client-runtime-catalog-sources-worldwide.json --execute --serial --max 0`. |\n| Run strict global certification | [Client runtime certification](docs/client-runtime-certification.md) | Add `--require-manual-evidence --manual-evidence docs/client-runtime-evidence.example.json` to fail on missing manual proof. |\n| Inspect the enhancement contract | [Credential-free evaluation](docs/prompt-enhancement.md#prompt-enhancement-evaluation) | Eight representative cases for profiles, languages, signals, determinism, and zero provider calls. |\n| Diagnose a first-run problem | [Troubleshooting matrix](docs/first-run-troubleshooting.md) | Shell-specific checks without exposing credentials. |\n| Verify an MCP client | [MCP client report](https://github.com/happy520ai/unified-ai-system/issues/new?template=mcp-client-report.yml) | Record one Codex, Cursor, Cline, or generic stdio run with a small evidence set. |\n| Contribute or report a run | [Usage report](https://github.com/happy520ai/unified-ai-system/issues/new?template=usage-verification-report.yml) or [good first issue #106](https://github.com/happy520ai/unified-ai-system/issues/106) | A reproducible feedback path for users and maintainers. |\n\n## Gateway Capabilities\n\nEverything below runs from the same self-hosted process — opt-in and\nfake-provider-first, so you can try every feature with zero credentials:\n\n<p align=\"center\">\n  <img\n    src=\"docs/assets/readme-capabilities.png\"\n    alt=\"Capability cards: OpenAI, Anthropic, and Gemini APIs; virtual keys and budgets; exact and semantic cache; reverse MCP governance; observability; local-first RAG; provider governance; and a 23-attack security regression\"\n    width=\"100%\"\n  />\n</p>\n\n| Capability | What you get | Docs |\n| --- | --- | --- |\n| OpenAI + Anthropic + Gemini compatible APIs | `/v1/chat/completions` (SSE streaming, tools, image/audio input, n>1), `/v1/messages` with **native Anthropic streaming and prompt-caching passthrough**, **native Gemini inbound** `:generateContent/:streamGenerateContent/:batchGenerateContent`, the Responses API, and model discovery — keep your existing SDK, change only the base URL. | [OpenAI-compatible API](docs/openai-compatible-api.md) · [Gemini](docs/gemini-provider.md) |\n| Virtual keys + budgets | Issue `uai-` keys with periodic token budgets (daily/monthly windows), per-key request limits, soft-budget alerts, spend attribution, and instant revocation. Consumers never hold provider keys. | [Virtual keys](docs/virtual-keys.md) · [Spend reporting](docs/spend-reporting.md) |\n| Response cache — exact + lexical-approximate | Tenant-scoped hot-path caching with byte-identical JSON/SSE replay, plus an opt-in similarity layer for near-duplicate requests. The default layer is deterministic lexical approximation, not a semantic model; attach a real embedding endpoint via the HTTP embedding hook for semantic-grade matching. | [Response cache](docs/response-cache-hot-path.md) |\n| Operations overview API (terminal-first) | `GET /api/overview` returns a compact JSON snapshot (provider mode, health, readiness, request stats, circuit state) behind `dashboard:read` — a lightweight companion to `/metrics` for CLI and dashboard tooling. The gateway serves no browser page; the public-clone gate keeps it terminal-first. | [Observability](docs/observability-export.md) |\n| Guardrails — deterministic & local | Input/output scans: pasted secrets block, PII redacts, injection phrasings warn, banned terms and size limits enforce — no cloud tier, no extra credentials, <0.2 ms measured overhead, runtime-configurable per rule. | [Guardrails](docs/guardrails.md) |\n| Reverse MCP governance | Aggregate upstream MCP servers (Streamable HTTP and stdio) behind one authenticated, audited, allow-listed surface — plus **REST→MCP**: any OpenAPI 3 spec becomes governed MCP tools. | [Reverse MCP governance](docs/reverse-mcp-governance.md) |\n| Observability | Chat-specific Prometheus metrics on `/metrics` — tokens per model, cache hit rates, TTFT histograms, virtual-key rejections, guardrail findings — plus an opt-in Langfuse export and a per-key spend report API/CLI. | [Observability](docs/observability-export.md) |\n| Vector retrieval | A credential-free deterministic embedding provider and the SQLite vector store activate `mode: \"vector\"` RAG with strict tenant isolation. | [Providers & knowledge](docs/providers.md) |\n| Provider governance | A three-gate whitelist matrix for real providers, a runtime credential store (locally permissioned file; virtual keys and user tokens are stored SHA-256-hashed, provider runtime credentials in cleartext for local execution — see the honest-boundaries note), request cost guards, circuit breakers, and fallback chains. | [Provider enablement](docs/real-provider-enablement.md) |\n| Local-client intelligence gateway | Tenant-scoped inventory; server-bound per-client PoP with optional durable single-host replay protection; policy-pinned fake-provider dispatch for OpenAI, Anthropic, Gemini, and native chat; dry-run autonomous management; governed execution with durable dispatch/receipt reconciliation, a receipt-feedback outbox, and exactly-once aggregate learning; irreversible revocation; and transactional MCP onboarding for Claude-compatible, Cursor, and VS Code JSON profiles. Credential-free fixture flows are proven; real-client atomic-receipt certification, real-provider certification, distributed state, external rollback anchors, and a deployed protected Windows authority remain release gates. | [Design and evidence boundary](docs/local-client-intelligence-gateway.md) |\n| Enterprise governance + security drills | JWT auth, RBAC, tenant isolation with audit hash chains — verified by a repeatable 23-attack live security regression. | [Security drill](tools/security-attack-regression.mjs) |\n| Enterprise identity & provisioning | **OIDC SSO** (authorization code + PKCE + JWKS signature verification, issues an API token on login) and **SCIM 2.0** user provisioning (bearer-auth create/get/list/patch/deactivate). | [Security drill](tools/security-attack-regression.mjs) · [Enterprise SSO & SCIM](docs/enterprise-sso.md) |\n| Operator traffic control | Configurable **weighted routing splits** and **shadow traffic** (`AI_GATEWAY_WEIGHTED_ROUTES_JSON`): shadow calls are separately accounted; real-provider shadowing also requires `AI_GATEWAY_SHADOW_REAL_PROVIDER_ENABLED=true`. | [Multi-process deployment](docs/multi-process-deployment.md) |\n| Hot-path RAG + billing evidence | Opt-in `unified_ai.rag` knowledge injection on `/v1/chat/completions`; central usage evidence and an admin-only exact-attempt USD statement comparison. Local statement previews remain explicitly non-legal and no payment gateway is connected. | [Spend reporting](docs/spend-reporting.md) |\n| Multi-instance controls | `AI_GATEWAY_MULTI_INSTANCE=true` keeps same-host SQLite defaults. Explicit PostgreSQL modes cover cross-host quotas, response idempotency, dispatch tombstones, WebSocket/A2A/Workforce leases and terminal fences, approvals, billable usage, and a shared HMAC audit chain. Current source also gates governed irreversible built-ins, webhooks, MCP/OpenAPI mutations, and custom tools with durable effect tombstones. A destructive CI drill restores PostgreSQL 17, builds a real asynchronous streaming standby, proves WAL replay, then uses a bounded three-failure-plus-confirmation controller to promote the one known standby and switch a stable endpoint. Before destruction, a real Docker-bridge partition separates the probe/standby from a still-writable primary; an independent fence must block promotion, then bridge healing must restore health and replay the partition marker. After failover, the fenced old-primary volume is `pg_rewind -R` synchronized and first starts only as a standby; it must keep streaming after the promoted primary restarts. A separate manifested physical base backup and continuous WAL archive are also restored archive-only to an exact LSN where an included marker exists and a later marker does not. The same eight clients recover after switch/restart. This is bounded LSN-PITR, single-bridge fencing, old-primary safe rejoin, single-standby automatic-failover, and at-most-once admission evidence, not provider-side exactly-once, multi-candidate election/quorum, external HA control, long-duration/off-host archive custody, time-based PITR, arbitrary multi-host partition/rejoin control, complete split-brain safety, or production RTO/RPO; resumable call-stack recovery, complete HA/DR, external WORM, and authenticated provider statements remain deployment work. | [Multi-process deployment](docs/multi-process-deployment.md) · [PostgreSQL recovery drill](docs/postgresql-recovery-drill.md) · [External-effect fencing](docs/external-effect-fencing.md) |\n\nPublished infrastructure benchmark (fake provider, single node): chat JSON p50 **15.6 ms**, SSE TTFT p50 **2.8 ms**, **402 req/s** at concurrency 8, cache hits **5.6× faster** than misses — see the [gateway benchmark](docs/benchmarks/2026-08-gateway-benchmark.md).\n\n## Why People Use It\n\n- Prompt enhancement for teammates who do not write perfect prompts.\n- Clean-clone verification without credentials or hidden setup.\n- Provider-free HTTP examples for curl and Python's standard library.\n- OpenAI SDK, CLI, HTTP API, shared SDK, MCP, Codex, Cursor, Cline, and Continue entry points.\n- Clear boundaries: no AGI claim, no L5 claim, no silent provider behavior.\n- Protocol-first onboarding: the governed JSON transaction path currently supports\n  Claude-compatible, Cursor, and VS Code profiles. Other MCP, A2A, or HTTP clients\n  require an explicit adapter/principal binding and reproducible certification report.\n\n## Try It in 60 Seconds\n\n<p align=\"center\">\n  <img\n    src=\"docs/assets/readme-terminal.png\"\n    alt=\"Terminal proof: one docker run command prints the enhanced prompt with providerCalled=false evidence and exits clean\"\n    width=\"100%\"\n  />\n</p>\n\nVerify the project without signing in:\n\n```bash\ndocker run --rm ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.7.0 pnpm gateway demo\n```\n\nExpected behavior:\n\n- local fake-provider execution\n- visible `execution: fake`\n- deterministic output\n- no API key or account needed\n- container exits automatically\n\nOne-command natural-language enhancement preview:\n\n```bash\ndocker run --rm ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.7.0 \\\n  pnpm gateway demo \"Build a small API for my team\" --enhance --profile coding --evidence\n```\n\nThis starts an isolated fake-provider gateway, enhances the request locally,\nprints the structured prompt, and cleans up without an API key.\n\nYou can also pipe a request directly into the published image without cloning\nthe repository:\n\n```bash\nprintf '%s' \"Plan a launch for a small API\" \\\n  | docker run --rm -i ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.7.0 \\\n      pnpm --silent gateway demo --enhance --profile planning --language en --json\n```\n\nPowerShell equivalent for a request file:\n\n```powershell\nGet-Content .\\request.txt -Raw |\n  docker run --rm -i ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.7.0 `\n    pnpm --silent gateway demo --enhance --profile planning --language en --json\n```\n\nThe container still uses the disposable fake-provider path and exits after the\nresult is printed.\n\nUse `--language zh-CN` or `--language en` when the enhancement output should\nfollow an explicit language instead of automatic detection.\n\nPrompt enhancement example:\n\nStart the gateway first (from a source checkout):\n\n```bash\npnpm gateway serve\n```\n\nThen, in another terminal:\n\n```bash\npnpm gateway enhance \"Build a small API for my team\" --profile coding\npnpm gateway chat \"Build a small API for my team\" --enhance --profile coding\n```\n\nThe CLI also accepts a request from stdin, which is useful for shell pipelines\nand text files:\n\n```bash\nprintf '%s' \"Plan a launch for a small API\" \\\n  | pnpm gateway enhance --profile planning --language en\ncat request.txt | pnpm gateway enhance --profile auto --json\n```\n\nPowerShell users can pipe the same path with `Get-Content .\\request.txt -Raw`.\n\n### Existing OpenAI SDKs\n\nStart the source gateway with `pnpm gateway serve`, then keep your existing\nOpenAI client and change only its base URL:\n\n```js\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  baseURL: \"http://127.0.0.1:3100/v1\",\n  apiKey: process.env.PME_AUTH_TOKEN || \"local-development\",\n});\n\nconst result = await client.chat.completions.create({\n  model: \"local-fake-model\",\n  messages: [{ role: \"user\", content: \"Build a small API for my team\" }],\n});\n\nconsole.log(result.choices[0].message.content);\n```\n\nThe credential-free gate verifies this path with the official OpenAI\nJavaScript SDK `7.4.0`. With the source gateway running, reproduce it with:\n\n```bash\nnode docs/examples/openai-sdk-chat.mjs\n```\n\nThe focused compatibility layer supports text completions, streaming, model\nlisting, and optional local prompt enhancement. See the\n[OpenAI-compatible API guide](docs/openai-compatible-api.md) for Python,\nsupported fields, auth behavior, and explicit limitations.\n\nPrefer Node.js? The dependency-free example verifies the provider-free response\nbefore printing the enhanced JSON:\n\n```bash\nnode docs/examples/prompt-enhancement.mjs \"Help me plan a small API for my team\" --profile planning --language en\n```\n\nPrefer Go? The standard-library example checks provider-free readiness and\nprints JSON evidence before showing the enhanced prompt:\n\n```bash\ngo run docs/examples/prompt-enhancement.go \"Help me plan a small API for my team\" --profile planning --language en\n```\n\nFor a no-clone prompt-enhancement walkthrough, start the published gateway\nimage and follow the [provider-free curl example](docs/examples/prompt-enhancement-curl.md):\n\n```bash\nread -rsp \"Enter a random gateway token (32+ characters): \" PME_AUTH_TOKEN\nprintf '\\n'\nexport PME_AUTH_TOKEN\ndocker run --rm --publish 127.0.0.1:3100:3100 \\\n  --env AI_GATEWAY_SERVICE_HOST=0.0.0.0 \\\n  --env AI_GATEWAY_PROVIDER_MODE=fake \\\n  --env AI_GATEWAY_REAL_PROVIDER_ENABLED=false \\\n  --env PME_ENTERPRISE_AUTH_ENABLED=true \\\n  --env PME_AUTH_TOKEN \\\n  ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.7.0\n```\n\nKeep that process running while you send the curl request. The response\nincludes `metadata.providerCalled=false`. For a credential-free HTTP stream,\nuse the [curl SSE example](docs/examples/streaming-chat-curl.md) to inspect\n`start`, `chunk`, and `done` events with `executionMode=fake`.\nThe gateway refuses non-loopback listening when authentication is disabled;\nsee the [critical attack-chain hardening report](docs/security-hardening-attack-chain.md).\n\n## Use It\n\n### Terminal Workflow\n\nAfter `pnpm install`:\n\n```bash\npnpm gateway serve\npnpm gateway status\npnpm gateway doctor\npnpm gateway chat \"Hello from Unified AI System\"\n```\n\nThe protected local-client control plane has read-only inspection plus explicit\ngoverned lifecycle commands. Prefer supplying the admin virtual key through the\nenvironment so it is not written to shell history:\n\n```powershell\n$env:AGENT_CONSOLE_ADMIN_KEY = \"<admin-virtual-key>\"\npnpm gateway clients --json\npnpm gateway clients discover --json\npnpm gateway clients --help\n```\n\nDiscovery and smart-management default to dry-run. Mutations require explicit\nconfirmation and an admin key; uncertain writes are never retried. A registry\ninspection is not proof that a named application was configured or controlled. See\n[Local Client Intelligence Gateway](docs/local-client-intelligence-gateway.md)\nfor the adapter and evidence boundary.\n\n### MCP / Codex / Cursor / Cline\n\nPublished MCP command:\n\n```bash\ncodex mcp add unified-ai-system -- docker run --rm -i ghcr.io/happy520ai/unified-ai-system/mcp-server:0.7.0\n```\n\nRestart Codex, run `/mcp verbose` to verify the twelve tools, then follow the\n[60-second Codex MCP quickstart](https://happy520ai.github.io/unified-ai-system/codex-mcp-docker-quickstart.html) for a safe first\nprompt-enhancement call and removal command.\n\nFor MCP clients that connect by URL, the source build provides a loopback-only\nStreamable HTTP endpoint:\n\n```bash\npnpm mcp:http\n# http://127.0.0.1:3210/mcp\n```\n\nSee the [MCP server guide](packages/mcp-server/README.md#streamable-http) for\nremote-bind authentication and the published-release boundary.\n\n### Installable Agent Skill\n\n```bash\ncodex plugin marketplace add happy520ai/unified-ai-system --ref master\nnpx skills add happy520ai/unified-ai-system --skill unified-ai-gateway --agent codex --copy --yes\n```\n\nThe plugin pins the [reviewed immutable v0.4.9 MCP image](docs/security/mcp-image-review-0.4.9.md)\nand starts it without container networking or Linux capabilities.\n\nSkill hub: https://skills.sh/happy520ai/unified-ai-system/unified-ai-gateway\n\nFor local source work:\n\nRequires Node.js 22.18.0 or newer and pnpm 11.19.0.\n\n```bash\ngit clone https://github.com/happy520ai/unified-ai-system.git\ncd unified-ai-system\ncorepack enable\ncorepack prepare pnpm@11.19.0 --activate\npnpm install --frozen-lockfile\npnpm verify:public-clone\npnpm gateway demo\n```\n\nFor a prepared cloud workspace, use [GitHub Codespaces](https://codespaces.new/happy520ai/unified-ai-system?quickstart=1). See the value first:\n\n```bash\npnpm gateway demo \"Build a small API for my team\" --enhance --profile coding --evidence\n```\n\nFor the complete credential-free clone check, run `pnpm verify:public-clone`\nafter the demo. The repository's devcontainer keeps the default path\nprovider-free. Codespaces availability and usage limits are controlled by\nGitHub.\n\n### Docker Compose\n\nFor a source checkout, start the gateway with a readiness check:\n\n```bash\ndocker compose up --build -d\ndocker compose ps\ncurl http://127.0.0.1:3100/health/check\n```\n\nThe service becomes `healthy` only after `/health/check` responds successfully.\nWhen finished, stop it with:\n\n```bash\ndocker compose down\n```\n\nThe Compose file treats `.env` as optional and leaves provider behavior explicit;\nthe credential-free fake-provider path remains the default.\n\n## Share a Verified Result\n\nIf the project helps your workflow, run one reproducible path, [star the\nrepository](https://github.com/happy520ai/unified-ai-system), and share the\nsmallest useful result through the [structured Usage Report](https://github.com/happy520ai/unified-ai-system/issues/new?template=usage-verification-report.yml).\n\nFor a ready-to-review CLI packet, append `--evidence` to the enhanced demo:\n\n```bash\npnpm gateway demo \"Build a small API for my team\" --enhance --profile coding --evidence\n```\n\nReview the original request and output before sharing the generated JSON. The\npacket also records `detectedSignals` and the item count for each\n`compiledSections` entry, so a reviewer can see which request signals were\ncarried into the structured prompt without reading internal logs.\n\nFor the browser Prompt Lab, use its `Copy evidence` or `Download evidence`\naction, then paste or attach the JSON in the optional Prompt Lab evidence field\nof the same report.\nUse `Copy share link` when you want another browser to reproduce the same local\ninput, profile, and language; review the prompt first because the URL fragment\ncontains the input text.\n\n## Next Steps\n\n- [Documentation](docs/README.md) for setup, the CLI, prompt enhancement, and providers.\n- [Codex MCP quickstart](https://happy520ai.github.io/unified-ai-system/codex-mcp-docker-quickstart.html) for the fastest agent-tool integration; the [source guide](docs/codex-mcp-quickstart.md) is kept in the repository.\n- [Contributing guide](CONTRIBUTING.md) for focused changes and safe verification.\n- [Usage Report template](.github/ISSUE_TEMPLATE/usage-verification-report.yml) for reproducible feedback.\n- [Cite this project](CITATION.cff), [Roadmap](ROADMAP.md), and [Support](SUPPORT.md).\n\n## Honest Boundaries\n\nWe separate what is verified from what is not claimed:\n\n- Clean clone + fake-provider path: **Yes**\n- Hosted public API: **No**\n- Real provider execution by default: **No**, must be explicitly enabled\n- Browser chat UI in this repo: **No** (CLI/API/MCP are first-class)\n- Production ready / AGI / L5: **Not claimed**\n\nReal provider calls are disabled by default. Configure safely via `.env.example` and `docs/providers.md`.\n\n## Verify the Project\n\n```bash\npnpm check\npnpm test\npnpm check:public\npnpm verify:public-clone\npnpm verify:mcp\n```\n\nCI on `master` runs Linux checks, container startup smoke tests, MCP discovery, and process-cleanup checks.\n\n## Project Links\n\n- [Official MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.happy520ai%2Funified-ai-system/versions/0.7.0)\n- [Release v0.5.0](https://github.com/happy520ai/unified-ai-system/releases/tag/v0.7.0)\n- [Codex MCP server README](packages/mcp-server/README.md)\n- [Roadmap](ROADMAP.md)\n- [Vision](VISION.md)\n- [Support](SUPPORT.md)\n\n## Star History\n\nIf the gateway saves you a proxy migration or an afternoon of prompt cleanup,\n[a star](https://github.com/happy520ai/unified-ai-system/stargazers) helps\nmore people find it.\n\n[![Star History Chart](https://api.star-history.com/svg?repos=happy520ai/unified-ai-system&type=Date)](https://star-history.com/#happy520ai/unified-ai-system&Date)\n",
  "bytes": 28200,
  "sha": "b160a1a5717c3f3f79afbb5718863f8a3204510a04184c686a9e091a8ff20c5c",
  "repo_slug": "happy520ai/unified-ai-system",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_happy520ai_unified_ai_system_d9d5372f/readme"
}