Unified AI System v0.3.3: a terminal-first AI gateway with 8 MCP tools

[happy520ai]

Pre-submission Checklist

• This post follows the MCP community guidelines

What would you like to share?

I built Unified AI System, an open, terminal-first AI gateway that can run as a credential-free local MCP server for Codex, Cursor, Cline, and other stdio hosts. The current release, io.github.happy520ai/unified-ai-system@0.3.3, is live in the official MCP Registry.

The design keeps the operational boundary usable through CLI, API, SDK, and MCP. A graphical console can remain optional for governance workflows instead of becoming a requirement for running or verifying the gateway.

The MCP surface exposes eight tools:

• gateway_chat, gateway_health, gateway_readiness
• knowledge_readiness
• workflow_actions, workflow_health
• workforce_agents, workforce_health

The credential-free path is deliberately deterministic. The MCP process starts an isolated local gateway backed by a fake provider, proves that real-provider mode is disabled before serving tools, rechecks that boundary before chat, and removes the managed process when the MCP session ends. Contributors can reproduce a complete initialize -> tools/list -> tools/call path without an account or API key.

Try it with Codex

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

The same image works as a generic stdio server:

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

A separate one-command demo starts the HTTP gateway, checks health and readiness, sends one deterministic fake-provider request, prints the evidence, and cleans up:

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

The implementation lesson that changed the release test

Our first dedicated MCP container launched through pnpm mcp. A package-manager lifecycle banner reached stdout before the server response and corrupted JSON-RPC framing, even though source-level tests were green.

The released image now invokes the Node entrypoint directly. Its verification harness talks to the image's actual default command, performs MCP initialize, initialized, tools/list, and tools/call, checks all eight tools, proves executionMode: fake and realProviderCallsMade: false, and verifies both container and child-gateway teardown.

The reusable pattern is small:

• Treat stdout as protocol-only for stdio servers.
• Test the package's real default command, not only a command override.
• Gate tool exposure on an observable safety invariant.
• Recheck cost-bearing boundaries at call time.
• Verify process teardown as part of the protocol contract.

What changed in v0.3.3

• Added a Codex plugin bundle and marketplace metadata.
• Added focused Codex, Cursor, and Cline setup paths.
• Added a terminal-first project site and a technical design note.
• Published multi-architecture images for linux/amd64 and linux/arm64.
• Strengthened credential-free public-clone and published-image verification.

This remains a public engineering preview, not a production-certification, L5-autonomy, or AGI claim. Real-provider execution remains explicit and scoped.

Relevant Links

• GitHub repository: https://github.com/happy520ai/unified-ai-system
• Project site: https://happy520ai.github.io/unified-ai-system/
• Terminal-first design note: https://happy520ai.github.io/unified-ai-system/terminal-first-ai-gateway.html
• Official MCP Registry entry: https://registry.modelcontextprotocol.io/v0.1/servers/io.github.happy520ai%2Funified-ai-system/versions/0.3.3
• v0.3.3 release: https://github.com/happy520ai/unified-ai-system/releases/tag/v0.3.3
• 60-second Codex + Docker web guide: https://happy520ai.github.io/unified-ai-system/codex-mcp-docker-quickstart.html
• Source quickstart with three safe tasks: https://github.com/happy520ai/unified-ai-system/blob/master/docs/codex-mcp-quickstart.md
• Current repository CI: https://github.com/happy520ai/unified-ai-system/actions/runs/30728513874
• Published-image verification: https://github.com/happy520ai/unified-ai-system/actions/runs/30724933173

I would value concrete feedback on the next MCP workflow: should the gateway remain inspection-first, or add approval-gated mutation tools? Which operation would be useful enough to expose, and what evidence or approval should it require?