aai-gateway 0.4.3 → 0.5.2

package/README.md

@@ -4,55 +4,48 @@
 
 AAI Gateway turns many apps, agents, skills, and MCP servers into one MCP server.
 
-You connect your AI tool once. AAI Gateway handles discovery, import, routing, and exposure control behind that single entrypoint.
+## 核心价值
 
-Why this matters:
+### 价值 1：自然语言驱动的工具接入
 
-- One MCP connection instead of one MCP per app
-- Smaller context through progressive disclosure — AAI Gateway never exposes raw tool definitions upfront
+安装 AAI Gateway MCP 之后，你可以通过自然语言描述快速接入其他任意 MCP、技能，并操控其他 AI Agent 工具（包括 Claude Code、Codex、OpenCode 等）。
 
-  **App-level exposure, not tool-level.** Tools are grouped into apps and only the app interface is visible initially. Users interact through `app:<id>` guides instead of seeing dozens of individual tools.
+AAI Gateway 还集成搜索工具，可以帮助你从权威、主流的网站上搜索官方、安全的 MCP 和技能，并实现一句话安装。
 
-  **Two app interfaces, user chooses:**
+### 价值 2：渐进式披露策略
 
-  - `summary` — a natural language description; good for automatic triggering
-  - `keywords` — a compact keyword set; further reduces context overhead when users reference tools explicitly
+AAI Gateway 不会一次性向大模型上下文中塞入所有工具的描述，而是采用渐进式披露策略：
 
-  Both modes keep the full tool capability available downstream — it just stays hidden until actually needed.
+**MCP Server 级别**：先只暴露 MCP Server 的整体描述。当大模型发现需要使用某个具体工具时，会先返回工具使用指导，然后 Agent 根据指导调用统一的 `aai:exec` 去执行。`aai:exec` 接受 `appId`、`tool`、`tool args` 作为参数。
 
-- A cleaner path to mix MCP servers, skills, ACP agents, and CLI-backed apps
+**MCP / 技能 描述级别**：提供两个层级的披露策略：
 
-AAI Gateway is for one goal: make tool ecosystems feel smaller, sharper, and easier for agents to use.
+- `summary` — 自然语言描述，适合自动触发
+- `keywords` — 紧凑的关键词集合，进一步简化上下文占用
 
-## How To Use
+这让 OpenCode 这种需要大量工具和技能的场景下依然能良好运行。
 
-### 1. Connect Your AI Tool To AAI Gateway
+## 使用方案
 
-You do not need to preinstall `aai-gateway`.
+### 1. 安装 AAI Gateway MCP
 
-Use the same style users already know from mainstream MCP setups: launch it through `npx`.
+你不需要预装 `aai-gateway`。只需将其注册为用户级 MCP 服务器，通过 `npx` 启动即可。
 
-### Claude Code
-
-Official docs: <https://code.claude.com/docs/en/mcp>
+#### Claude Code
 
 ```bash
-claude mcp add --transport stdio aai-gateway -- npx -y aai-gateway
+claude mcp add --scope user --transport stdio aai-gateway -- npx -y aai-gateway
 ```
 
-### Codex
-
-Official docs: <https://developers.openai.com/learn/docs-mcp>
+#### Codex
 
 ```bash
 codex mcp add aai-gateway -- npx -y aai-gateway
 ```
 
-### OpenCode
+#### OpenCode
 
-Official docs: <https://opencode.ai/docs/config> and <https://opencode.ai/docs/mcp-servers/>
-
-Add this to `~/.config/opencode/opencode.json` or your project `opencode.json`:
+在 `~/.config/opencode/opencode.json` 中添加：
 
 ```json
 {
@@ -67,38 +60,47 @@ Add this to `~/.config/opencode/opencode.json` or your project `opencode.json`:
 }
 ```
 
-### What You Get After Connecting
+### 2. 搜索并安装 MCP 或技能
+
+如果你不知道该安装哪个 MCP 或技能，可以让 AI 工具调用 `import:search`。
+
+`import:search` 会：
+
+- 将用户请求转换为搜索关键词
+- 推荐更安全的权威来源优先搜索
+- 将搜索结果规范化为候选列表
+- 为每个候选项生成临时 ID 供用户确认
+- 将确认的项目路由到 `mcp:import` 或 `skill:import` 流程
+
+**推荐的搜索来源顺序**：
 
-Once connected, your AI tool can use AAI Gateway tools such as:
+1. 官方目录：`modelcontextprotocol/registry`、`modelcontextprotocol/servers`、`openai/skills`
+2. 社区精选列表：`punkpeye/awesome-mcp-servers`、`ComposioHQ/awesome-claude-skills`
+3. 高审查来源：如 ClawHub 等开放市场（需额外谨慎）
 
-- `remote:discover`
-- `aai:exec`
-- `mcp:import`
-- `skill:import`
-- `mcp:refresh`
-- `import:config`
+> 注意：推荐列表是首选起点，而非硬性白名单。请勿随意推荐来自不知名小网站工具。对于市场平台，请额外检查维护者身份、仓库活跃度、README 质量和许可证是否可见。
 
-### 2. Import An MCP Server
+### 3. 导入 MCP Server
 
-The main workflow is: copy a mainstream MCP config snippet into your AI tool and ask it to import that server through AAI Gateway.
+主流程：复制主流 MCP 配置片段到 AI 工具，让它通过 AAI Gateway 导入。
 
-The AI tool should:
+AI 工具会：
 
-1. read the MCP config you pasted
-2. ask you to choose an exposure mode
-3. call `mcp:import`
+1. 读取你粘贴的 MCP 配置
+2. 询问你选择暴露模式
+3. 调用 `mcp:import`
 
-AAI Gateway keeps the import parameters close to normal MCP config shapes:
+AAI Gateway 保持导入参数与标准 MCP 配置格式一致：
 
-- stdio MCP: `command`, `args`, `env`, `cwd`
-- remote MCP: `url`, optional `transport`, optional `headers`
+- stdio MCP：`command`、`args`、`env`、`cwd`
+- remote MCP：`url`、可选 `transport`、可选 `headers`
 
-Before import, the AI tool should ask you to choose:
+导入前请选择暴露模式：
 
-- `summary`: easier automatic triggering
-- `keywords`: leaves room for more tools, but usually needs more explicit keyword mentions
+- `summary`：更容易自动触发
+- `keywords`：为更多工具留出空间，但通常需要更明确的关键词提及
 
-Example: import a normal stdio MCP config
+**stdio MCP 示例**：
 
 ```json
 {
@@ -107,7 +109,7 @@ Example: import a normal stdio MCP config
 }
 ```
 
-Example: import a normal remote Streamable HTTP MCP config
+**Remote Streamable HTTP MCP 示例**：
 
 ```json
 {
@@ -115,7 +117,7 @@ Example: import a normal remote Streamable HTTP MCP config
 }
 ```
 
-Example: import a normal remote SSE MCP config
+**Remote SSE MCP 示例**：
 
 ```json
 {
@@ -124,29 +126,23 @@ Example: import a normal remote SSE MCP config
 }
 ```
 
-After import, AAI Gateway returns:
+导入完成后，AAI Gateway 返回：
 
-- the generated app id
-- the generated `keywords`
-- the generated `summary`
-- the guide tool name: `app:<id>`
+- 生成的 app id
+- 生成的 `keywords`
+- 生成的 `summary`
+- 引导工具名称：`app:<id>`
 
-Important:
+> **重要**：导入后需重启 AI 工具才能使用新导入的工具。重启后，导入的应用将显示为 `app:<id>`，使用 `aai:exec` 执行实际操作。
 
-- Restart your AI tool before using the newly imported tool.
-- After restart, the imported app will appear as `app:<id>`.
-- Use `aai:exec` to actually run the imported app’s operations.
+### 4. 导入技能 (Skill)
 
-### 3. Import A Skill
+技能导入同样通过 AI 工具完成。告诉 AI 工具调用 `skill:import`，然后提供：
 
-Skills are imported through the AI tool as well.
+- 本地技能路径
+- 或暴露 `SKILL.md` 的远程技能根 URL
 
-Ask the AI tool to call `skill:import`, then give it either:
-
-- a local skill path
-- a remote skill root URL that exposes `SKILL.md`
-
-Examples:
+**本地技能示例**：
 
 ```json
 {
@@ -154,49 +150,155 @@ Examples:
 }
 ```
 
+**远程技能示例**：
+
 ```json
 {
   "url": "https://example.com/skill"
 }
 ```
 
-Just like MCP import, skill import returns:
+与 MCP 导入一样，技能导入返回 `app id`、`keywords`、`summary` 和 `app:<id>` 引导工具名称。
 
-- the generated app id
-- generated `keywords`
-- generated `summary`
-- the guide tool name: `app:<id>`
+导入后需重启 AI 工具。
 
-Then restart your AI tool before using the imported skill.
+### 5. 支持的 ACP Agents
 
-### 4. Supported ACP Agents
+AAI Gateway 还能通过 ACP 控制类应用的 Agent。
 
-AAI Gateway can also control app-like agents through ACP.
-
-Currently supported ACP agent types:
+当前支持的 ACP Agent 类型：
 
 - OpenCode
 - Claude Code
 - Codex
 
-## App Auto Discovery
+## 原理
 
-AAI Gateway discovers apps from four places:
+### 架构图
 
-- desktop descriptors
-- web descriptors
-- gateway-managed imports
-- built-in ACP agent descriptors
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        AI Agent                             │
+│                    (Claude Code / Codex / OpenCode)         │
+└────────────────────────┬────────────────────────────────────┘
+                         │  One MCP Connection
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      AAI Gateway                            │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │              Progressive Disclosure Layer               ││
+│  │  - App-level exposure (not tool-level)                  ││
+│  │  - Summary / Keywords modes                              ││
+│  │  - Lazy tool loading on demand                          ││
+│  └─────────────────────────────────────────────────────────┘│
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │                   App Registry                           ││
+│  │  - MCP Servers    - Skills                               ││
+│  │  - ACP Agents     - CLI Tools                           ││
+│  └─────────────────────────────────────────────────────────┘│
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │                  Discovery Layer                         ││
+│  │  - Desktop Descriptors  - Web Descriptors               ││
+│  │  - Gateway Imports       - Built-in Descriptors          ││
+│  └─────────────────────────────────────────────────────────┘│
+└────────────────────────┬────────────────────────────────────┘
+                         │  Native Protocol
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    External Apps                            │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
+│  │   MCP    │ │  Skill   │ │   ACP    │ │   CLI    │       │
+│  │ Servers  │ │          │ │  Agents  │ │  Tools   │       │
+│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
+└─────────────────────────────────────────────────────────────┘
+```
 
-### The AAI Descriptor
+### 统一抽象：Agent App
+
+AAI Gateway 将 MCP、技能、ACP Agent、CLI 工具统一抽象为 **Agent App**。
+
+只要提供一个 App 的描述文件 (`aai.json`)，即可接入 AAI Gateway。描述文件告诉 AAI Gateway：
+
+- App 是什么
+- 如何连接
+- 如何以低上下文成本暴露
+
+### 描述文件示例
+
+#### MCP Server 描述文件
+
+```json
+{
+  "schemaVersion": "2.0",
+  "version": "1.0.0",
+  "app": {
+    "name": {
+      "default": "Filesystem Server"
+    }
+  },
+  "access": {
+    "protocol": "mcp",
+    "config": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    }
+  },
+  "exposure": {
+    "keywords": ["file", "filesystem", "read", "write"],
+    "summary": "Use this app when the user wants to read from or write to the local filesystem."
+  }
+}
+```
+
+#### Skill 描述文件
+
+```json
+{
+  "schemaVersion": "2.0",
+  "version": "1.0.0",
+  "app": {
+    "name": {
+      "default": "Git Commit Skill"
+    }
+  },
+  "access": {
+    "protocol": "skill",
+    "config": {
+      "url": "https://github.com/example/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."
+  }
+}
+```
 
-The descriptor is a small `aai.json` file. It tells AAI Gateway:
+#### ACP Agent 描述文件
 
-- what the app is
-- how to connect to it
-- how to expose it at low context cost
+```json
+{
+  "schemaVersion": "2.0",
+  "version": "1.0.0",
+  "app": {
+    "name": {
+      "default": "Claude Code"
+    }
+  },
+  "access": {
+    "protocol": "acp-agent",
+    "config": {
+      "agentType": "claude-code"
+    }
+  },
+  "exposure": {
+    "keywords": ["claude", "code", "coding", "agent"],
+    "summary": "Use this app when the user wants Claude Code to perform coding tasks."
+  }
+}
+```
 
-Minimal example:
+#### CLI 工具描述文件
 
 ```json
 {
@@ -204,7 +306,7 @@ Minimal example:
   "version": "1.0.0",
   "app": {
     "name": {
-      "default": "Example App"
+      "default": "Example CLI"
     }
   },
   "access": {
@@ -220,28 +322,53 @@ Minimal example:
 }
 ```
 
-Supported `access.protocol` values today:
+## 如何将更多 App 预置集成到 AAI Gateway
+
+### 提交 Pull Request
+
+如果你希望 AAI Gateway 默认打包某个 App 的描述文件，可以提交 PR。
 
-- `mcp`
-- `skill`
-- `acp-agent`
-- `cli`
+PR 需要包含：
 
-### Where To Put `aai.json`
+1. 描述文件本身
+2. 安全的发现规则（证明 App 确实已安装）
+3. 连接配置
+4. 说明为什么这个集成应该被捆绑
+
+内置 ACP Agent 描述文件位于：
+
+- `src/discovery/descriptors/`
+
+它们在以下文件中注册：
+
+- `src/discovery/agent-registry.ts`
+
+标准 PR 流程：
+
+1. 添加描述文件
+2. 添加或更新发现检查
+3. 在适当的发现源中注册
+4. 如果新集成面向用户，更新 README
+
+如果你不确定某个集成是否应该被捆绑，请先提交 Issue 讨论。
+
+### 描述文件放置位置
+
+AAI Gateway 从以下位置发现 App：
 
 #### Web Apps
 
-Publish it at:
+发布到：
 
-```text
+```
 https://<your-host>/.well-known/aai.json
 ```
 
-AAI Gateway fetches that path when the user calls `remote:discover`.
+用户调用 `remote:discover` 时，AAI Gateway 会获取该路径。
 
 #### macOS Apps
 
-Recommended locations scanned by the gateway:
+推荐位置：
 
 - `<YourApp>.app/Contents/Resources/aai.json`
 - `~/Library/Containers/<container>/Data/Library/Application Support/aai.json`
@@ -249,7 +376,7 @@ Recommended locations scanned by the gateway:
 
 #### Linux Apps
 
-The gateway scans for `aai.json` under:
+扫描以下位置：
 
 - `/usr/share`
 - `/usr/local/share`
@@ -257,50 +384,20 @@ The gateway scans for `aai.json` under:
 
 #### Windows Apps
 
-The gateway scans for `aai.json` under:
+扫描以下位置：
 
 - `C:\Program Files`
 - `C:\Program Files (x86)`
 - `%LOCALAPPDATA%`
 
-### Descriptor Guidelines
-
-Keep descriptors small and practical:
-
-- make `app.name.default` clear
-- keep `keywords` short and high-signal
-- 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 tool detail lazily.
-
-## Submit A Pull Request To Preload A Descriptor
-
-If you want AAI Gateway to ship with a descriptor by default, open a PR.
-
-What to include:
-
-- the descriptor itself
-- a safe discovery rule that proves the app is actually installed
-- the connection config
-- a short explanation of why the integration should be bundled
-
-Today, built-in ACP agent descriptors live in:
-
-- `src/discovery/descriptors/`
-
-And they are registered in:
-
-- `src/discovery/agent-registry.ts`
-
-For a typical PR:
-
-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.
+#### 描述文件编写建议
 
-If you are unsure whether an integration should be bundled, open an issue first.
+- 保持描述文件小而实用
+- `app.name.default` 要清晰
+- `keywords` 要短且高信号
+- `summary` 要解释何时应该使用该 App
+- 详细能力数据放在下游协议中，而非描述文件中
+- 如果你的 App 已使用 MCP，保持描述文件最小化，让 MCP 提供惰性工具详情
 
 ## Disclaimer
 

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { A as logger, D as createDesktopDiscovery, O as getManagedAppDir, T as AAI_GATEWAY_VERSION, _ as isMcpAccess, a as buildMcpImportConfig, b as getMcpExecutor, c as importSkill, d as upsertSkillRegistryEntry, f as upsertMcpRegistryEntry, i as IMPORT_LIMITS, l as normalizeExposureInput, m as createSecureStorage, n as createGatewayServer, o as buildSkillImportSource, r as EXPOSURE_LIMITS, s as importMcpServer, u as validateImportHeaders, v as isSkillAccess } from "./server-C2U35Fro.js";
+import { A as logger, D as createDesktopDiscovery, O as getManagedAppDir, T as AAI_GATEWAY_VERSION, _ as isMcpAccess, a as buildMcpImportConfig, b as getMcpExecutor, c as importSkill, d as upsertSkillRegistryEntry, f as upsertMcpRegistryEntry, i as IMPORT_LIMITS, l as normalizeExposureInput, m as createSecureStorage, n as createGatewayServer, o as buildSkillImportSource, r as EXPOSURE_LIMITS, s as importMcpServer, u as validateImportHeaders, v as isSkillAccess } from "./server-DQ0nbmQB.js";
 import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 //#region src/cli.ts
@@ -8,6 +8,11 @@ function parseKeyValue(value, flag) {
 	if (index === -1) throw new Error(`${flag} expects KEY=VALUE`);
 	return [value.slice(0, index), value.slice(index + 1)];
 }
+function parsePositiveInteger(value, flag) {
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${flag} expects a positive integer`);
+	return parsed;
+}
 function parseArgs(args) {
 	const dev = args.includes("--dev");
 	if (args.includes("--scan")) return {
@@ -16,9 +21,11 @@ function parseArgs(args) {
 	};
 	if (args[0] === "mcp" && args[1] === "import") {
 		const exposure = parseRequiredExposureArgs(args.slice(2));
+		let name;
 		let transport;
 		let url;
 		let launchCommand;
+		let timeout;
 		let launchCwd;
 		const launchArgs = [];
 		const launchEnv = {};
@@ -33,6 +40,10 @@ function parseArgs(args) {
 				case "--keyword":
 					i += 1;
 					break;
+				case "--name":
+					name = next;
+					i += 1;
+					break;
 				case "--transport":
 					if (next !== "streamable-http" && next !== "sse") throw new Error("--transport must be streamable-http or sse");
 					transport = next;
@@ -46,6 +57,10 @@ function parseArgs(args) {
 					launchCommand = next;
 					i += 1;
 					break;
+				case "--timeout":
+					timeout = parsePositiveInteger(next, "--timeout");
+					i += 1;
+					break;
 				case "--arg":
 					launchArgs.push(next);
 					i += 1;
@@ -71,9 +86,11 @@ function parseArgs(args) {
 					"--exposure",
 					"--summary",
 					"--keyword",
+					"--name",
 					"--transport",
 					"--url",
 					"--command",
+					"--timeout",
 					"--arg",
 					"--env",
 					"--cwd",
@@ -85,9 +102,11 @@ function parseArgs(args) {
 			command: "mcp-import",
 			dev,
 			...exposure,
+			...name ? { name } : {},
 			transport,
 			url,
 			launchCommand,
+			...timeout !== void 0 ? { timeout } : {},
 			launchArgs,
 			launchEnv,
 			launchCwd,
@@ -136,7 +155,7 @@ function parseArgs(args) {
 	}
 	if (args[0] === "app" && args[1] === "config") {
 		const localId = args[2];
-		if (!localId) throw new Error("Usage: aai-gateway app config <local-id>");
+		if (!localId) throw new Error("Usage: aai-gateway app config <app-id>");
 		let exposure;
 		let summary;
 		const keywords = [];
@@ -223,7 +242,7 @@ Usage:
   aai-gateway [options]
   aai-gateway mcp import [options]
   aai-gateway skill import [options]
-  aai-gateway app config <local-id> [options]
+  aai-gateway app config <app-id> [options]
 
 Options:
   --scan        Scan for desktop descriptors and exit
@@ -237,7 +256,9 @@ Shared metadata options:
   --keyword VALUE        Required for import and repeatable, max ${EXPOSURE_LIMITS.keywordCount} items, each max ${EXPOSURE_LIMITS.keywordLength} characters
 
 MCP import options:
+  --name TEXT           Optional app name used for display and app id generation, max ${IMPORT_LIMITS.nameLength} chars
   --command CMD          Import a local stdio MCP server, max ${IMPORT_LIMITS.commandLength} chars
+  --timeout MS           Optional MCP downstream inactivity timeout in milliseconds, default 60000
   --arg VALUE            Repeatable stdio argument, max ${IMPORT_LIMITS.argCount} items, each max ${IMPORT_LIMITS.argLength} chars
   --env KEY=VALUE        Repeatable stdio environment variable, max ${IMPORT_LIMITS.envCount} entries
   --cwd DIR              Working directory for stdio launch, max ${IMPORT_LIMITS.cwdLength} chars
@@ -277,20 +298,24 @@ async function runMcpImport(options) {
 		transport: options.transport,
 		url: options.url,
 		command: options.launchCommand,
+		timeout: options.timeout,
 		args: options.launchArgs,
 		env: options.launchEnv,
 		cwd: options.launchCwd
 	});
 	const result = await importMcpServer(executor, storage, {
+		name: options.name,
 		exposureMode: options.exposure,
 		keywords: options.keywords,
 		summary: options.summary,
 		config,
 		headers: options.headers
 	});
-	console.log(`Imported MCP app: ${result.entry.localId}`);
+	console.log(`Imported MCP app: ${result.descriptor.app.name.default}`);
+	console.log(`App ID: ${result.entry.localId}`);
 	console.log(`Descriptor: ${result.entry.descriptorPath}`);
 	console.log(`Managed directory: ${getManagedAppDir(result.entry.localId)}`);
+	console.log(`Tool name after restart: app:${result.entry.localId}`);
 	console.log(`Keywords: ${result.descriptor.exposure.keywords.join(", ")}`);
 	console.log(`Summary: ${result.descriptor.exposure.summary}`);
 	console.log(`Exposure mode: ${options.exposure}`);
@@ -307,9 +332,11 @@ async function runSkillImport(options) {
 		path: source.path,
 		url: source.url
 	});
-	console.log(`Imported skill: ${result.localId}`);
+	console.log(`Imported skill: ${result.descriptor.app.name.default}`);
+	console.log(`App ID: ${result.localId}`);
 	console.log(`Descriptor: ${join(getManagedAppDir(result.localId), "aai.json")}`);
 	console.log(`Skill directory: ${result.managedPath}`);
+	console.log(`Tool name after restart: app:${result.localId}`);
 	console.log(`Keywords: ${result.descriptor.exposure.keywords.join(", ")}`);
 	console.log(`Summary: ${result.descriptor.exposure.summary}`);
 	console.log(`Exposure mode: ${options.exposure}`);