Unified AI System
About
Self-hosted MCP and AI gateway that turns rough natural language into structured prompts with governed routing and reproducible verification for Codex, Cursor, and Cline.
Details
- Author
- happy520ai
- Categories
- Developer Tools
Jump to
Setup
Install Unified AI System in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/happy520ai/unified-ai-system
Follow the installation instructions in the repository README, then restart your MCP client.
Unified AI System: Self-Hosted AI Gateway & MCP Server
Open-source AI gateway for deterministic prompt enhancement, governed execution, and reproducible verification.
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 the feature set you'd expect from a commercial LLM gateway: virtual keys with token budgets, exact + semantic response caching, reverse MCP governance with REST→MCP generation, and production observability.
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.5.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, andproviderCalled=false. Codex, VS Code, Claude Code, Gemini CLI, OpenCode, Cursor, Cline, Continue, and generic stdio clients can reach the same gateway through twelve governed MCP tools. 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 repositoryorshare one reproducible result.
Clients keep their native protocols; the gateway adds keys, budgets, cache, and audit. Twelve governed MCP tools are inspectable from any MCP client.
Everything below runs from the same self-hosted process — opt-in and fake-provider-first, so you can try every feature with zero credentials:
Published infrastructure benchmark (fake provider, single node): chat JSON p5015.6 ms, SSE TTFT p502.8 ms,402 req/sat concurrency 8, cache hits5.6× fasterthan misses — see thegateway benchmark.
- Prompt enhancement for teammates who do not write perfect prompts.
- Clean-clone verification without credentials or hidden setup.
- Provider-free HTTP examples for curl and Python's standard library.
- OpenAI SDK, CLI, HTTP API, shared SDK, MCP, Codex, Cursor, Cline, and Continue entry points.
- Clear boundaries: no AGI claim, no L5 claim, no silent provider behavior.
- Protocol-first onboarding: any OpenAI-compatible MCP, A2A, or HTTP client can be onboarded via a short setup + reproducible report path; we prioritize verification over marketing claims.
docker run --rm ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.5.0 pnpm gateway demo
- local fake-provider execution
- visibleexecution: 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.5.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.
You can also pipe a request directly into the published image without cloning the repository:
printf '%s' "Plan a launch for a small API" \ | docker run --rm -i ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.5.0 \ pnpm --silent gateway demo --enhance --profile planning --language en --json
PowerShell equivalent for a request file:
Get-Content .\request.txt -Raw | docker run --rm -i ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.5.0 pnpm --silent gateway demo --enhance --profile planning --language en --json
The container still uses the disposable fake-provider path and exits after the result is printed.
Use--language zh-CNor--language enwhen the enhancement output should follow an explicit language instead of automatic detection.
Start the gateway first (from a source checkout):
pnpm gateway enhance "Build a small API for my team" --profile coding pnpm gateway chat "Build a small API for my team" --enhance --profile coding
The CLI also accepts a request from stdin, which is useful for shell pipelines and text files:
printf '%s' "Plan a launch for a small API" \ | pnpm gateway enhance --profile planning --language en cat request.txt | pnpm gateway enhance --profile auto --json
PowerShell users can pipe the same path withGet-Content .\request.txt -Raw.
Start the source gateway withpnpm gateway serve, then keep your existing OpenAI client and change only its base URL:
import OpenAI from "openai"; const client = new OpenAI({ baseURL: "http://127.0.0.1:3100/v1", apiKey: process.env.PME_AUTH_TOKEN || "local-development", }); const result = await client.chat.completions.create({ model: "local-fake-model", messages: [{ role: "user", content: "Build a small API for my team" }], }); console.log(result.choices[0].message.content);
The credential-free gate verifies this path with the official OpenAI JavaScript SDK7.4.0. With the source gateway running, reproduce it with:
The focused compatibility layer supports text completions, streaming, model listing, and optional local prompt enhancement. See theOpenAI-compatible API guidefor Python, supported fields, auth behavior, and explicit limitations.
Prefer Node.js? The dependency-free example verifies the provider-free response before printing the enhanced JSON:
node docs/examples/prompt-enhancement.mjs "Help me plan a small API for my team" --profile planning --language en
Prefer Go? The standard-library example checks provider-free readiness and prints JSON evidence before showing the enhanced prompt:
go run docs/examples/prompt-enhancement.go "Help me plan a small API for my team" --profile planning --language en
For a no-clone prompt-enhancement walkthrough, start the published gateway image and follow theprovider-free curl example:
read -rsp "Enter a random gateway token (32+ characters): " PME_AUTH_TOKEN printf '\n' export PME_AUTH_TOKEN docker run --rm --publish 127.0.0.1:3100:3100 \ --env AI_GATEWAY_SERVICE_HOST=0.0.0.0 \ --env AI_GATEWAY_PROVIDER_MODE=fake \ --env AI_GATEWAY_REAL_PROVIDER_ENABLED=false \ --env PME_ENTERPRISE_AUTH_ENABLED=true \ --env PME_AUTH_TOKEN \ ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.5.0
Keep that process running while you send the curl request. The response includesmetadata.providerCalled=false. For a credential-free HTTP stream, use thecurl SSE exampleto inspectstart,chunk, anddoneevents withexecutionMode=fake. The gateway refuses non-loopback listening when authentication is disabled; see thecritical attack-chain hardening report.
pnpm gateway serve pnpm gateway status pnpm gateway doctor pnpm gateway chat "Hello from Unified AI System"
codex mcp add unified-ai-system -- docker run --rm -i ghcr.io/happy520ai/unified-ai-system/mcp-server:0.5.0
Restart Codex, run/mcp verboseto verify the twelve tools, then follow the60-second Codex MCP quickstartfor a safe first prompt-enhancement call and removal command.
For MCP clients that connect by URL, the source build provides a loopback-only Streamable HTTP endpoint:
pnpm mcp:http # http://127.0.0.1:3210/mcp
See theMCP server guidefor remote-bind authentication and the published-release boundary.
codex plugin marketplace add happy520ai/unified-ai-system --ref master npx skills add happy520ai/unified-ai-system --skill unified-ai-gateway --agent codex --copy --yes
The plugin pins thereviewed immutable v0.4.9 MCP imageand starts it without container networking or Linux capabilities.
Skill hub:https://skills.sh/happy520ai/unified-ai-system/unified-ai-gateway
git clone https://github.com/happy520ai/unified-ai-system.git cd unified-ai-system corepack enable corepack prepare pnpm@9.15.4 --activate pnpm install --frozen-lockfile pnpm verify:public-clone pnpm gateway demo
For a prepared cloud workspace, useGitHub Codespaces. See the value first:
pnpm gateway demo "Build a small API for my team" --enhance --profile coding --evidence
For the complete credential-free clone check, runpnpm verify:public-cloneafter the demo. The repository's devcontainer keeps the default path provider-free. Codespaces availability and usage limits are controlled by GitHub.
For a source checkout, start the gateway with a readiness check:
docker compose up --build -d docker compose ps curl http://127.0.0.1:3100/health/check
The service becomeshealthyonly after/health/checkresponds successfully. When finished, stop it with:
The Compose file treats.envas optional and leaves provider behavior explicit; the credential-free fake-provider path remains the default.
If the project helps your workflow, run one reproducible path,star the repository, and share the smallest useful result through thestructured Usage Report.
For a ready-to-review CLI packet, append--evidenceto the enhanced demo:
pnpm gateway demo "Build a small API for my team" --enhance --profile coding --evidence
Review the original request and output before sharing the generated JSON. The packet also recordsdetectedSignalsand the item count for eachcompiledSectionsentry, so a reviewer can see which request signals were carried into the structured prompt without reading internal logs.
For the browser Prompt Lab, use itsCopy evidenceorDownload evidenceaction, then paste or attach the JSON in the optional Prompt Lab evidence field of the same report. UseCopy share linkwhen you want another browser to reproduce the same local input, profile, and language; review the prompt first because the URL fragment contains the input text.
- Documentationfor setup, the CLI, prompt enhancement, and providers.
- Codex MCP quickstartfor the fastest agent-tool integration; thesource guideis kept in the repository.
- Contributing guidefor focused changes and safe verification.
- Usage Report templatefor reproducible feedback.
- Cite this project,Roadmap, andSupport.
We separate what is verified from what is not claimed:
- Clean clone + fake-provider path:Yes
- Hosted public API:No
- Real provider execution by default:No, must be explicitly enabled
- Browser chat UI in this repo:No(CLI/API/MCP are first-class)
- Production ready / AGI / L5:Not claimed
Real provider calls are disabled by default. Configure safely via.env.exampleanddocs/providers.md.
pnpm check pnpm test pnpm check:public pnpm verify:public-clone pnpm verify:mcp
CI onmaster`runs Linux checks, container startup smoke tests, MCP discovery, and process-cleanup checks.
- Official MCP Registry entry
- Release v0.5.0
- Codex MCP server README
- Roadmap
- Vision
- Support
If the gateway saves you a proxy migration or an afternoon of prompt cleanup,a starhelps more people find it.
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
Create crafted UI components inspired by the best 21st.dev design engineers.
Bring agent evaluations, observability, and synthetic test set generation directly into your IDE for free with Galileo's new MCP server
An MCP server to help AI assistants to answer questions and generate AccelByte Extend SDK code more effectively .
MCP server for AI Diagram Maker — generate beautiful software engineering diagrams directly inside Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI agent
ALAPI MCP Tools,Call hundreds of API interfaces via MCP
AI-powered SVG animation generator that transforms static files into animated SVG components using the Allyson platform
MCP server that gives AI assistants on-demand access to 1,500+ amCharts docs, ~300 code examples, and 1000+ class API references.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.





