aai-gateway 0.5.2 → 0.7.0

package/README.md

@@ -1,35 +1,31 @@
 # AAI Gateway
 
-## One MCP. Many Apps. Less Context.
+## Why AAI Gateway
 
-AAI Gateway turns many apps, agents, skills, and MCP servers into one MCP server.
+AAI stands for **Agent App Interface**.
 
-## 核心价值
+### Three Pain Points of MCP/Skill Configuration
 
-### 价值 1：自然语言驱动的工具接入
+**1. Context Token Waste**: Every MCP server injects its schema, descriptions, and tool lists into the prompt. As you add more servers, the model spends more tokens understanding tools than executing tasks.
 
-安装 AAI Gateway MCP 之后，你可以通过自然语言描述快速接入其他任意 MCP、技能，并操控其他 AI Agent 工具（包括 Claude Code、Codex、OpenCode 等）。
+**2. Config Cannot Be Shared Across Agents**: MCP/Skill configured in Claude Code cannot be directly used in OpenCode or Codex. You have to configure it separately for each agent tool.
 
-AAI Gateway 还集成搜索工具，可以帮助你从权威、主流的网站上搜索官方、安全的 MCP 和技能，并实现一句话安装。
+**3. Requires Agent Restart After Installation**: Traditionally, adding a new MCP or Skill requires restarting the agent tool to take effect.
 
-### 价值 2：渐进式披露策略
+### What AAI Gateway Solves
 
-AAI Gateway 不会一次性向大模型上下文中塞入所有工具的描述，而是采用渐进式披露策略：
+- **Progressive Disclosure**: Expose app overview first, reveal tool details only when needed, avoiding context explosion
+- **Centralized Config Management**: Import MCP/Skill once, share across all agent tools
+- **Hot Loading**: Auto-notify agents after import, **no restart required**
+- **Natural Language Interaction**: Search, import, and manage MCPs/Skills through simple conversation
 
-**MCP Server 级别**：先只暴露 MCP Server 的整体描述。当大模型发现需要使用某个具体工具时，会先返回工具使用指导，然后 Agent 根据指导调用统一的 `aai:exec` 去执行。`aai:exec` 接受 `appId`、`tool`、`tool args` 作为参数。
+AAI Gateway unifies MCP servers, Skills, ACP agents, and CLI tools under one roof, making it simple and efficient for agents to discover and use software.
 
-**MCP / 技能 描述级别**：提供两个层级的披露策略：
+## How To Use
 
-- `summary` — 自然语言描述，适合自动触发
-- `keywords` — 紧凑的关键词集合，进一步简化上下文占用
+### 1. Install AAI Gateway MCP
 
-这让 OpenCode 这种需要大量工具和技能的场景下依然能良好运行。
-
-## 使用方案
-
-### 1. 安装 AAI Gateway MCP
-
-你不需要预装 `aai-gateway`。只需将其注册为用户级 MCP 服务器，通过 `npx` 启动即可。
+You do not need to preinstall `aai-gateway`. Simply register it as a user-level MCP server and launch it via `npx`.
 
 #### Claude Code
 
@@ -45,7 +41,7 @@ codex mcp add aai-gateway -- npx -y aai-gateway
 
 #### OpenCode
 
-在 `~/.config/opencode/opencode.json` 中添加：
+Add to `~/.config/opencode/opencode.json`:
 
 ```json
 {
@@ -60,47 +56,43 @@ codex mcp add aai-gateway -- npx -y aai-gateway
 }
 ```
 
-### 2. 搜索并安装 MCP 或技能
-
-如果你不知道该安装哪个 MCP 或技能，可以让 AI 工具调用 `import:search`。
-
-`import:search` 会：
+### 2. Search and Install MCP or Skill
 
-- 将用户请求转换为搜索关键词
-- 推荐更安全的权威来源优先搜索
-- 将搜索结果规范化为候选列表
-- 为每个候选项生成临时 ID 供用户确认
-- 将确认的项目路由到 `mcp:import` 或 `skill:import` 流程
+If you don't know which MCP or skill to install, just ask your AI tool to search for what you need using AAI Gateway (e.g., "please search for a filesystem MCP" or "find me a git commit skill").
 
-**推荐的搜索来源顺序**：
+The search will:
 
-1. 官方目录：`modelcontextprotocol/registry`、`modelcontextprotocol/servers`、`openai/skills`
-2. 社区精选列表：`punkpeye/awesome-mcp-servers`、`ComposioHQ/awesome-claude-skills`
-3. 高审查来源：如 ClawHub 等开放市场（需额外谨慎）
+- Convert your request into search keywords
+- Recommend safer authoritative sources to search first
+- Normalize search results into a shortlist for your confirmation
+- Route confirmed items into the import flow
 
-> 注意：推荐列表是首选起点，而非硬性白名单。请勿随意推荐来自不知名小网站工具。对于市场平台，请额外检查维护者身份、仓库活跃度、README 质量和许可证是否可见。
+**Recommended Search Source Order**:
 
-### 3. 导入 MCP Server
+1. Official catalogs: `modelcontextprotocol/registry`, `modelcontextprotocol/servers`, `openai/skills`
+2. Community-curated lists: `punkpeye/awesome-mcp-servers`, `ComposioHQ/awesome-claude-skills`
+3. Higher-scrutiny sources: Open marketplaces like ClawHub (use with extra caution)
 
-主流程：复制主流 MCP 配置片段到 AI 工具，让它通过 AAI Gateway 导入。
+> Note: The recommended list is a starting point, not a hard allowlist. Do not casually suggest tools from unknown websites. For marketplace platforms, also verify the maintainer's identity, repository activity, README quality, and license visibility.
 
-AI 工具会：
+### 3. Import an MCP Server
 
-1. 读取你粘贴的 MCP 配置
-2. 询问你选择暴露模式
-3. 调用 `mcp:import`
+Main workflow: Copy a mainstream MCP config snippet into your AI tool and ask it to import that server through AAI Gateway.
 
-AAI Gateway 保持导入参数与标准 MCP 配置格式一致：
+The AI tool will:
 
-- stdio MCP：`command`、`args`、`env`、`cwd`
-- remote MCP：`url`、可选 `transport`、可选 `headers`
+1. Read the MCP config you pasted
+2. Inspect the downstream MCP tools through AAI Gateway
+3. Summarize when the MCP should be used
+4. Ask whether it should be enabled for the current agent only or for all agents
+5. Call `mcp:import`
 
-导入前请选择暴露模式：
+AAI Gateway keeps import parameters consistent with standard MCP config shapes:
 
-- `summary`：更容易自动触发
-- `keywords`：为更多工具留出空间，但通常需要更明确的关键词提及
+- stdio MCP: `command`, `args`, `env`, `cwd`
+- remote MCP: `url`, optional `transport`, optional `headers`
 
-**stdio MCP 示例**：
+**stdio MCP Example**:
 
 ```json
 {
@@ -109,7 +101,7 @@ AAI Gateway 保持导入参数与标准 MCP 配置格式一致：
 }
 ```
 
-**Remote Streamable HTTP MCP 示例**：
+**Remote Streamable HTTP MCP Example**:
 
 ```json
 {
@@ -117,7 +109,7 @@ AAI Gateway 保持导入参数与标准 MCP 配置格式一致：
 }
 ```
 
-**Remote SSE MCP 示例**：
+**Remote SSE MCP Example**:
 
 ```json
 {
@@ -126,55 +118,45 @@ AAI Gateway 保持导入参数与标准 MCP 配置格式一致：
 }
 ```
 
-导入完成后，AAI Gateway 返回：
+After import, AAI Gateway returns:
 
-- 生成的 app id
-- 生成的 `keywords`
-- 生成的 `summary`
-- 引导工具名称：`app:<id>`
+- The generated app id
+- The generated `summary`
+- The guide tool name: `app:<id>`
 
-> **重要**：导入后需重启 AI 工具才能使用新导入的工具。重启后，导入的应用将显示为 `app:<id>`，使用 `aai:exec` 执行实际操作。
+> AAI Gateway sends `tools/listChanged` after import. Clients that implement this notification can pick up new tools without restart.
 
-### 4. 导入技能 (Skill)
+### 4. Import a Skill
 
-技能导入同样通过 AI 工具完成。告诉 AI 工具调用 `skill:import`，然后提供：
+Skills are imported through the AI tool as well. Tell the AI tool to import a skill using AAI Gateway, then provide:
 
-- 本地技能路径
-- 或暴露 `SKILL.md` 的远程技能根 URL
+- A local skill path
 
-**本地技能示例**：
+If the skill is remote, download and extract the whole skill directory first. AAI Gateway only imports from a local directory and copies the full directory into managed storage.
 
-```json
-{
-  "path": "/absolute/path/to/skill"
-}
-```
-
-**远程技能示例**：
+**Local Skill Example**:
 
 ```json
 {
-  "url": "https://example.com/skill"
+  "path": "/absolute/path/to/skill"
 }
 ```
 
-与 MCP 导入一样，技能导入返回 `app id`、`keywords`、`summary` 和 `app:<id>` 引导工具名称。
-
-导入后需重启 AI 工具。
+AAI Gateway derives the imported skill summary from the skill's own `SKILL.md` description. It can also generate a lightweight proxy `SKILL.md` for the current agent so the agent can discover the skill automatically.
 
-### 5. 支持的 ACP Agents
+### 5. Supported ACP Agents
 
-AAI Gateway 还能通过 ACP 控制类应用的 Agent。
+AAI Gateway can also control app-like agents through ACP.
 
-当前支持的 ACP Agent 类型：
+Currently supported ACP agent types:
 
 - OpenCode
 - Claude Code
 - Codex
 
-## 原理
+## How It Works
 
-### 架构图
+### Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -188,7 +170,7 @@ AAI Gateway 还能通过 ACP 控制类应用的 Agent。
 │  ┌─────────────────────────────────────────────────────────┐│
 │  │              Progressive Disclosure Layer               ││
 │  │  - App-level exposure (not tool-level)                  ││
-│  │  - Summary / Keywords modes                              ││
+│  │  - Summary-only disclosure                               ││
 │  │  - Lazy tool loading on demand                          ││
 │  └─────────────────────────────────────────────────────────┘│
 │  ┌─────────────────────────────────────────────────────────┐│
@@ -198,8 +180,8 @@ AAI Gateway 还能通过 ACP 控制类应用的 Agent。
 │  └─────────────────────────────────────────────────────────┘│
 │  ┌─────────────────────────────────────────────────────────┐│
 │  │                  Discovery Layer                         ││
-│  │  - Desktop Descriptors  - Web Descriptors               ││
-│  │  - Gateway Imports       - Built-in Descriptors          ││
+│  │  - Desktop Descriptors  - Managed Imports                ││
+│  │  - Built-in Descriptors                                   ││
 │  └─────────────────────────────────────────────────────────┘│
 └────────────────────────┬────────────────────────────────────┘
                          │  Native Protocol
@@ -213,19 +195,19 @@ AAI Gateway 还能通过 ACP 控制类应用的 Agent。
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### 统一抽象：Agent App
+### Unified Abstraction: Agent App
 
-AAI Gateway 将 MCP、技能、ACP Agent、CLI 工具统一抽象为 **Agent App**。
+AAI Gateway unifies MCPs, Skills, ACP Agents, and CLI tools into **Agent Apps**.
 
-只要提供一个 App 的描述文件 (`aai.json`)，即可接入 AAI Gateway。描述文件告诉 AAI Gateway：
+To integrate an app with AAI Gateway, simply provide an app descriptor file (`aai.json`). The descriptor tells AAI Gateway:
 
-- App 是什么
-- 如何连接
-- 如何以低上下文成本暴露
+- What the app is
+- How to connect to it
+- How to expose it at low context cost
 
-### 描述文件示例
+### Descriptor Examples
 
-#### MCP Server 描述文件
+#### MCP Server Descriptor
 
 ```json
 {
@@ -244,13 +226,12 @@ AAI Gateway 将 MCP、技能、ACP Agent、CLI 工具统一抽象为 **Agent App
     }
   },
   "exposure": {
-    "keywords": ["file", "filesystem", "read", "write"],
     "summary": "Use this app when the user wants to read from or write to the local filesystem."
   }
 }
 ```
 
-#### Skill 描述文件
+#### Skill Descriptor
 
 ```json
 {
@@ -264,17 +245,16 @@ AAI Gateway 将 MCP、技能、ACP Agent、CLI 工具统一抽象为 **Agent App
   "access": {
     "protocol": "skill",
     "config": {
-      "url": "https://github.com/example/git-commit-skill"
+      "path": "/absolute/path/to/git-commit-skill"
     }
   },
   "exposure": {
-    "keywords": ["git", "commit", "version control"],
     "summary": "Use this app when the user wants to create git commits with auto-generated messages."
   }
 }
 ```
 
-#### ACP Agent 描述文件
+#### ACP Agent Descriptor
 
 ```json
 {
@@ -292,13 +272,12 @@ AAI Gateway 将 MCP、技能、ACP Agent、CLI 工具统一抽象为 **Agent App
     }
   },
   "exposure": {
-    "keywords": ["claude", "code", "coding", "agent"],
     "summary": "Use this app when the user wants Claude Code to perform coding tasks."
   }
 }
 ```
 
-#### CLI 工具描述文件
+#### CLI Tool Descriptor
 
 ```json
 {
@@ -316,59 +295,48 @@ AAI Gateway 将 MCP、技能、ACP Agent、CLI 工具统一抽象为 **Agent App
     }
   },
   "exposure": {
-    "keywords": ["example", "utility"],
     "summary": "Use this app when the user wants to work with Example App."
   }
 }
 ```
 
-## 如何将更多 App 预置集成到 AAI Gateway
+## Pre-bundling Apps in AAI Gateway
 
-### 提交 Pull Request
+### Submit a Pull Request
 
-如果你希望 AAI Gateway 默认打包某个 App 的描述文件，可以提交 PR。
+If you want AAI Gateway to ship with a descriptor for an app by default, open a PR.
 
-PR 需要包含：
+A PR should include:
 
-1. 描述文件本身
-2. 安全的发现规则（证明 App 确实已安装）
-3. 连接配置
-4. 说明为什么这个集成应该被捆绑
+1. The descriptor itself
+2. A safe discovery rule that proves the app is actually installed
+3. The connection config
+4. An explanation of why the integration should be bundled
 
-内置 ACP Agent 描述文件位于：
+Built-in ACP agent descriptors live in:
 
 - `src/discovery/descriptors/`
 
-它们在以下文件中注册：
+They are registered in:
 
 - `src/discovery/agent-registry.ts`
 
-标准 PR 流程：
-
-1. 添加描述文件
-2. 添加或更新发现检查
-3. 在适当的发现源中注册
-4. 如果新集成面向用户，更新 README
-
-如果你不确定某个集成是否应该被捆绑，请先提交 Issue 讨论。
+Standard PR workflow:
 
-### 描述文件放置位置
+1. Add the descriptor file
+2. Add or update discovery checks
+3. Register it in the appropriate discovery source
+4. Update the README if the new integration is user-facing
 
-AAI Gateway 从以下位置发现 App：
+If you're unsure whether an integration should be bundled, open an issue first to discuss.
 
-#### Web Apps
-
-发布到：
-
-```
-https://<your-host>/.well-known/aai.json
-```
+### Where to Place Descriptors
 
-用户调用 `remote:discover` 时，AAI Gateway 会获取该路径。
+AAI Gateway discovers apps from the following locations:
 
 #### macOS Apps
 
-推荐位置：
+Recommended locations:
 
 - `<YourApp>.app/Contents/Resources/aai.json`
 - `~/Library/Containers/<container>/Data/Library/Application Support/aai.json`
@@ -376,7 +344,7 @@ https://<your-host>/.well-known/aai.json
 
 #### Linux Apps
 
-扫描以下位置：
+Scanned locations:
 
 - `/usr/share`
 - `/usr/local/share`
@@ -384,20 +352,19 @@ https://<your-host>/.well-known/aai.json
 
 #### Windows Apps
 
-扫描以下位置：
+Scanned locations:
 
 - `C:\Program Files`
 - `C:\Program Files (x86)`
 - `%LOCALAPPDATA%`
 
-#### 描述文件编写建议
+#### Descriptor Guidelines
 
-- 保持描述文件小而实用
-- `app.name.default` 要清晰
-- `keywords` 要短且高信号
-- `summary` 要解释何时应该使用该 App
-- 详细能力数据放在下游协议中，而非描述文件中
-- 如果你的 App 已使用 MCP，保持描述文件最小化，让 MCP 提供惰性工具详情
+- Keep descriptors small and practical
+- Make `app.name.default` clear
+- Make `summary` explain when the app should be used
+- Put detailed capability data in the downstream protocol, not in the descriptor
+- If your app already speaks MCP, keep the descriptor minimal and let MCP provide lazy tool details
 
 ## Disclaimer