gybob / aai-protocol
AAI (Agent App Interface) is an open protocol that makes any app accessible to AI Agents. One aai.json descriptor makes your desktop or web app(SaaS) instantly discoverable and callable. Skip slow GUI automation; go from invisible to Agent-native in milliseconds.
View on GitHubAI Architecture Analysis
This repository is indexed by RepoMind. By analyzing gybob/aai-protocol in our AI interface, you can instantly generate complete architecture diagrams, visualize control flows, and perform automated security audits across the entire codebase.
Our Agentic Context Augmented Generation (Agentic CAG) engine loads full source files into context on-demand, avoiding the fragmentation of traditional RAG systems. Ask questions about the architecture, dependencies, or specific features to see it in action.
Embed this Badge
Showcase RepoMind's analysis directly in your repository's README.
Repository Overview (README excerpt)
Crawler viewAAI Protocol > **App-level MCP gateway with progressive disclosure.** [ ]() **AAI (Agent App Interface) Protocol** is a lightweight specification for packaging, discovering, and executing capability-backed apps behind a single MCP gateway. Instead of connecting one MCP server per app, AAI lets you expose **multiple apps through one MCP connection** — with full control over what the AI client sees upfront. --- The Problem Traditional MCP setups require one connection per capability provider: Every tool from every server is dumped into the context. This is noisy, expensive, and reveals capabilities before you need them. The Solution AAI Gateway sits in front of everything and applies **progressive disclosure**: Only app-level interfaces are exposed upfront. Detailed tool execution happens on demand. --- Key Features Progressive Disclosure — App Level, Not Tool Level Tools are grouped into **apps**. Only the app interface is visible to the AI client — never raw tool schemas. Users choose how each app is exposed: | Mode | Description | |---|---| | | Natural language description; AI infers when to use | | | Compact keyword set; explicit triggering with minimal context | Both modes expose the same capability. Only the trigger mechanism differs. One Connection, Many Apps One MCP connection to the gateway — it routes to any backend: MCP servers, ACP agents, CLI tools, skills, or remote apps. Human-Readable Discovery All manifests are plain JSON with localized names and descriptions. No binary blobs, no proprietary formats. Consent-First Sensitive operations (e.g., filesystem write) can declare consent requirements. The gateway enforces them before execution. --- How It Works • Apps Declare Capabilities in • Gateway Exposes Only Apps The AI client sees , not the 10 underlying MCP tools: • On Demand, Detailed Guides When is called, the gateway returns the operation guide — a human-friendly list of what this app can do: • Execution via The AI calls with . Gateway checks consent → routes to MCP server → returns result. --- Spec Overview | Document | Description | |---|---| | AAI JSON | App manifest format ( structure) | | Architecture | Gateway internals and data flow | | Security | Authentication and authorization | | MCP Bridge | MCP server integration | --- Implementations Gateway • **aai-gateway** — Reference gateway implementation in TypeScript/Node.js Apps Apps are just directories with an manifest. See example-apps/ for templates. --- Version History | Version | Date | Summary | |---|---|---| | 0.1 | 2025-12-19 | Initial draft with MCP-only backend. | | 0.2 | 2026-01-15 | Added CLI, skill, and ACP agent protocols. | | 0.3 | 2026-03-20 | App-level exposure with summary/keywords modes. | --- Motivation We built AAI because: • **Context is expensive.** Every tool definition in the context costs tokens. • **Discovery should be gradual.** Showing every capability upfront is overwhelming. • **Users should be in control.** Different users have different privacy and UX preferences. AAI is our answer to "how do we expose many capabilities through one MCP connection without blowing up context size?" --- License MIT