aai-gateway

[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) --- # AAI Gateway: Unified MCP & Skill Management, Shared Across AI Agents, 99% Context Token Savings [](https://www.npmjs.com/package/aai-gateway) [](./LICENSE) --- ## What Is It **AAI** = **Agent App Interface** AAI Gateway is the interaction gateway for Agent Apps. What is an **Agent App**? An Agent App is a collection of capabilities that an Agent can use. For example: - An **MCP Server** is an Agent App — it provides a set of tools - A **Skill package** is an Agent App — it provides one or more skills In AAI Gateway, they are abstracted as **Agent Apps** under unified management. Import once, and all AI Agents can use them immediately. --- ## What Problems Does It Solve ### Context Bloat Traditional: 10 MCPs × 5 tools = **50 full schemas ≈ 7,500 tokens** injected into every conversation. AAI Gateway: each Agent App needs only **fewer than 50 tokens for a summary**, with details loaded on demand. **99% token savings.** ### Finding Tools Is Hard Traditional: search GitHub → read READMEs → copy JSON configs → debug connections → restart Agent. AAI Gateway: **tell your Agent "use AAI to search for xxx" — auto-searches, installs, ready to use**. > "Use AAI to search for a browser automation tool" > > → Search → finds Playwright MCP → Agent summarizes a one-line Agent App summary → install → ready to use, no restart needed > "Use AAI to search for a PPT creation skill" > > → Search → finds PPT Skill → uses skill description as Agent App summary → install → ready to use, no restart needed ### Duplicate Config Configure the same thing in Claude Code, Codex, and OpenCode separately? Import once through AAI Gateway, all Agents share instantly. --- ## Quick Start (30 Seconds) **Claude Code:** ```bash claude mcp add --scope user --transport stdio aai-gateway -- npx -y aai-gateway ``` **Codex:** ```bash codex mcp add aai-gateway -- npx -y aai-gateway ``` **OpenCode** — add to `~/.config/opencode/opencode.json`: ```json { "mcp": { "aai-gateway": { "type": "local", "command": ["npx", "-y", "aai-gateway"], "enabled": true } } } ``` **[OpenClaw](https://openclaw.ai):** ```bash openclaw plugins install openclaw-aai-gateway-plugin ``` Once installed, just tell your Agent what you want to do. --- ## Built-in Tools | Tool | Description | |------|-------------| | `search:discover` | Search and install new tools with natural language | | `mcp:import` | Import an MCP Server as an Agent App | | `skill:import` | Import a Skill package as an Agent App | | `listAllAaiApps` | List all registered Agent Apps | | `enableApp` / `disableApp` | Enable or disable an Agent App per Agent | | `removeApp` | Remove an Agent App | | `aai:exec` | Execute a specific tool within an Agent App | Each imported Agent App generates an **`app_<app-id>`** tool that returns the full operation guide and tool list when called. ### Preset Agent Apps (auto-discovered when locally installed) | App ID | Name | Description | |--------|------|-------------| | `claude` | Claude Code | AI coding assistant for code editing, analysis, and development | | `codex` | Codex | OpenAI-powered AI coding assistant | | `opencode` | OpenCode | AI development assistant for editing files and running commands | --- ## Architecture  --- ## Developers: Get Your Agent App Auto-Discovered Create an `aai.json` descriptor and submit it to `src/discovery/descriptors/`. When a user's local environment meets the `discovery.checks` conditions, the Agent will auto-discover your Agent App. ```json { "schemaVersion": "2.0", "version": "1.0.0", "app": { "name": { "default": "My App" } }, "discovery": { "checks": [ { "kind": "command", "command": "my-app" } ] }, "access": { "protocol": "mcp", "config": { "command": "my-app-mcp", "args": ["--stdio"] } }, "exposure": { "summary": "Use when the user wants to do X." } } ``` `discovery.checks` supports three check types: `command` (command exists), `file` (file exists), `path` (directory exists). Supported protocols: `mcp`, `skill`, `acp-agent` Welcome to [submit a PR](../../pulls) to contribute new Agent App descriptors, or [open an issue](../../issues) for feedback.