Unified AI System

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.

GitHub
3

Documentation

Unified AI System

Open-source AI gateway for deterministic prompt enhancement, governed execution, and reproducible verification.

English | zh-CN | Project Site

Open in GitHub Codespaces

GitHub stars CI Container HOL Plugin Scanner Release Official MCP Registry: active License

Unified AI System is a public gateway for models, agents, knowledge, and tools. It is built for teams that want rough natural language turned into executable intent before a model call, with explicit provider opt-in and evidence-first verification.

This is not a chat UI wrapper. It is a control plane for AI workflow execution.

Start here: run the 60-second demo, open it in Codespaces, and star the repository if it helps your workflow. Share one verified result in Issue #20.

Why People Use It

  • 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.
  • CLI, HTTP API, SDK, MCP, Codex, Cursor, and Cline entry points.
  • Clear boundaries: no AGI claim, no L5 claim, no silent provider behavior.

Unified AI System local prompt enhancement demo
v0.4.3: deterministic enhancement, no API key, no provider call.

Try It in 60 Seconds

Verify the project without signing in:

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

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.4.3 \
  pnpm gateway demo "Build a small API for my team" --enhance --profile coding

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

Use --language zh-CN or --language en when the enhancement output should follow an explicit language instead of automatic detection.

Prompt enhancement example:

Start the gateway first (from a source checkout):

pnpm gateway serve

Then, in another terminal:

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

For a no-clone prompt-enhancement walkthrough, start the published gateway image and follow the provider-free curl example:

docker run --rm --publish 3100:3100 \
  --env AI_GATEWAY_SERVICE_HOST=0.0.0.0 \
  --env AI_GATEWAY_PROVIDER_MODE=fake \
  --env AI_GATEWAY_REAL_PROVIDER_ENABLED=false \
  ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.4.3

Keep that process running while you send the curl request. The response includes metadata.providerCalled=false. For a credential-free HTTP stream, use the curl SSE example to inspect start, chunk, and done events with executionMode=fake.

Use It

Terminal Workflow

After pnpm install:

pnpm gateway serve
pnpm gateway status
pnpm gateway doctor
pnpm gateway chat "Hello from Unified AI System"

MCP / Codex / Cursor / Cline

Published MCP command:

codex mcp add unified-ai-system -- docker run --rm -i ghcr.io/happy520ai/unified-ai-system/mcp-server:0.4.3

Restart Codex, run /mcp verbose to verify the nine tools, then follow the 60-second Codex MCP quickstart for a safe first prompt-enhancement call and removal command.

Installable Agent Skill

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

Skill hub: https://skills.sh/happy520ai/unified-ai-system/unified-ai-gateway

For local source work:

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, use GitHub Codespaces, then run:

pnpm verify:public-clone
pnpm gateway demo "Build a small API for my team" --enhance --profile coding

The repository's devcontainer keeps the default path provider-free. Codespaces availability and usage limits are controlled by GitHub.

Help It Grow

If the project is useful, star the repository and keep the loop factual:

  1. Run one reproducible command and keep the output.
  2. Share one short post with the repo link.
  3. Ask for OS + one output line in issue #20.
  4. Save one verified result in docs/star-growth-evidence-pack.md.

Useful links:

Honest Boundaries

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.example and docs/providers.md.

Verify the Project

pnpm check
pnpm test
pnpm check:public
pnpm verify:public-clone
pnpm verify:mcp

CI on master runs Linux checks, container startup smoke tests, MCP discovery, and process-cleanup checks.

Project Links