aai-gateway 0.3.4 → 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +118 -104
  2. package/dist/cli.js +1 -1
  3. package/dist/index.js +2 -2
  4. package/dist/{server-BYtx5KIZ.js → server-DrBOLU_J.js} +686 -68
  5. package/dist/server-DrBOLU_J.js.map +1 -0
  6. package/package.json +1 -1
  7. package/dist/server-BYtx5KIZ.js.map +0 -1
package/README.md CHANGED
@@ -21,7 +21,13 @@
21
21
 
22
22
  ---
23
23
 
24
- ## 🚀 Core Innovation: Progressive Disclosure
24
+ ## Architecture
25
+
26
+ ![AAI Gateway Architecture](./images/architecture.png)
27
+
28
+ ---
29
+
30
+ ## 🚀 Core Innovations
25
31
 
26
32
  Traditional MCP servers return all tools on `tools/list`, causing:
27
33
 
@@ -32,7 +38,9 @@ Traditional MCP servers return all tools on `tools/list`, causing:
32
38
  → Reduced response accuracy
33
39
  ```
34
40
 
35
- **AAI Gateway's Solution**:
41
+ ### 1. Progressive Disclosure
42
+
43
+ AAI Gateway's solution:
36
44
 
37
45
  ```
38
46
  tools/list returns only lightweight entries:
@@ -47,6 +55,18 @@ Agent calls web:discover or app:<id> on-demand to get detailed operation guides
47
55
 
48
56
  **Result**: **95% reduction** in context usage, faster and more accurate Agent responses.
49
57
 
58
+ ### 2. Unified Descriptor
59
+
60
+ Every integration is normalized through the same `aai.json` descriptor model. At a high level, the descriptor defines:
61
+
62
+ - App identity and metadata
63
+ - Execution binding
64
+ - Tool definitions
65
+ - Parameter schemas
66
+ - Authentication requirements
67
+
68
+ For the full descriptor format, see the **[AAI Protocol `aai.json` spec](https://github.com/gybob/aai-protocol/blob/main/spec/aai-json.md)**.
69
+
50
70
  ---
51
71
 
52
72
  ## How It Works
@@ -76,7 +96,18 @@ Agent calls web:discover or app:<id> on-demand to get detailed operation guides
76
96
  → Executes and returns result
77
97
  ```
78
98
 
79
- ---
99
+ ### ACP Agent Workflow
100
+
101
+ ```
102
+ 1. AAI Gateway scans for installed ACP agents at startup
103
+ → Found agents appear as app:<agent-id> entries in tools/list
104
+ 2. User: "Use OpenCode to refactor this code"
105
+ → Agent finds matching app:dev.sst.opencode
106
+ 3. tools/call("app:dev.sst.opencode")
107
+ → Returns operation guide: session/new(), session/prompt(message)
108
+ 4. tools/call("aai:exec", {app: "dev.sst.opencode", tool: "session/prompt", args: {message: "refactor this code"}})
109
+ → Executes via ACP (stdio JSON-RPC) and returns result
110
+ ```
80
111
 
81
112
  ## 🔐 Security & Consent
82
113
 
@@ -103,17 +134,22 @@ AAI Gateway implements a **caller-aware consent mechanism** to protect user priv
103
134
  This ensures that each MCP client has explicit user authorization, preventing cross-client authorization leakage.
104
135
 
105
136
  > 💡 **Note**: Caller identity is informational and not a security boundary. The real security is enforced by the operating system (TCC on macOS, UAC on Windows, etc.).
137
+
106
138
  ---
107
139
 
108
140
  ## 📱 Supported Apps
109
141
 
110
142
  These apps have built-in descriptors and work out of the box:
111
143
 
112
- | App | Auth Type | Tools | Description |
113
- | ----------------- | -------------- | ----- | --------------------------------------------------- |
114
- | **Notion** | API Key | 11 | Notes, docs, knowledge base, project management |
115
- | **Yuque (语雀)** | API Key | 7 | Alibaba Cloud knowledge management platform |
116
- | **Feishu / Lark** | App Credential | 11 | Enterprise collaboration (docs, wiki, IM, calendar) |
144
+ | App | Type | Auth Type | Tools | Description |
145
+ | ----------------- | --------- | -------------- | ----- | --------------------------------------------------- |
146
+ | **Notion** | Web | API Key | 11 | Notes, docs, knowledge base, project management |
147
+ | **Yuque (语雀)** | Web | API Key | 7 | Alibaba Cloud knowledge management platform |
148
+ | **Feishu / Lark** | Web | App Credential | 11 | Enterprise collaboration (docs, wiki, IM, calendar) |
149
+ | **OpenCode** | ACP Agent | None | 4 | Open-source AI coding agent with terminal UI |
150
+ | **Claude Code** | ACP Agent | None | 4 | Anthropic's official AI coding agent |
151
+ | **Gemini CLI** | ACP Agent | None | 4 | Google's Gemini CLI coding agent |
152
+
117
153
  > 💡 Want to add your app? See [How to Integrate](#how-to-integrate) | [Upcoming Apps](#upcoming-apps)
118
154
 
119
155
  > ⚠️ **Note**: AAI Gateway is currently in active development. Bugs may exist. Contributions are welcome!
@@ -202,7 +238,7 @@ code --add-mcp '{"name":"aai-gateway","command":"npx","args":["aai-gateway"]}'
202
238
 
203
239
  ### How to Integrate
204
240
 
205
- There are two ways to integrate an app with AAI Gateway:
241
+ There are two ways to integrate an app with AAI Gateway today:
206
242
 
207
243
  #### Method 1: Provide a Descriptor File
208
244
 
@@ -219,28 +255,14 @@ AAI Gateway will automatically discover and load the descriptor.
219
255
 
220
256
  #### Method 2: Contribute to Built-in Registry
221
257
 
222
- For web apps without a hosted descriptor, you can add a built-in descriptor to AAI Gateway:
223
-
224
- 1. Create `src/discovery/descriptors/<app>.ts` following existing patterns
225
- 2. Register in `src/discovery/web-registry.ts`
226
- 3. Submit a pull request
227
-
228
- This is useful for:
258
+ For apps without a hosted descriptor, you can add a built-in descriptor:
229
259
 
230
- - Apps without official API documentation
231
- - Custom auth configurations
232
- - Cold-start scenarios
260
+ - **Web App**: Create `src/discovery/descriptors/<app>.ts`, register in `src/discovery/web-registry.ts`
261
+ - **ACP Agent**: Create `src/discovery/descriptors/<agent>-agent.ts`, register in `src/discovery/agent-registry.ts`
233
262
 
234
- #### Descriptor Format
263
+ Then submit a pull request.
235
264
 
236
- The descriptor follows the **[AAI Protocol specification](https://github.com/gybob/aai-protocol/blob/main/spec/aai-json.md)**. Key points:
237
-
238
- - All field names use **camelCase** (e.g., `schemaVersion`, `baseUrl`)
239
- - Supports **internationalized names** with language fallback
240
- - Auth types: `oauth2`, `apiKey`, `appCredential`, `cookie`
241
- - Tools defined with JSON Schema parameters
242
-
243
- For the complete spec, see **[aai.json Descriptor Spec](https://github.com/gybob/aai-protocol/blob/main/spec/aai-json.md)**.
265
+ > **Note**: ACP agents are auto-discovered by checking if the CLI command exists on the system.
244
266
 
245
267
  #### Supported Auth Types
246
268
 
@@ -253,12 +275,13 @@ For the complete spec, see **[aai.json Descriptor Spec](https://github.com/gybob
253
275
 
254
276
  #### Platform Support
255
277
 
256
- | Platform | Discovery | IPC | Consent | Storage |
257
- | ----------- | ---------------------- | ------------ | --------- | -------- |
258
- | **macOS** | Supported | Apple Events | osascript | Keychain |
259
- | **Linux** | XDG paths | DBus (gdbus) | zenity/kdialog | libsecret |
260
- | **Windows** | Program Files | COM (PowerShell) | PowerShell | CredMan |
261
- | **Web** | `.well-known/aai.json` | HTTP | N/A | Platform |
278
+ | Platform | Discovery | IPC | Consent | Storage |
279
+ | ----------- | ---------------------- | ---------------- | -------------- | --------- |
280
+ | **macOS** | Supported | Apple Events | osascript | Keychain |
281
+ | **Linux** | XDG paths | DBus (gdbus) | zenity/kdialog | libsecret |
282
+ | **Windows** | Program Files | COM (PowerShell) | PowerShell | CredMan |
283
+ | **Web** | `.well-known/aai.json` | HTTP | N/A | Platform |
284
+ | **Stdio** | Protocol only | Planned | N/A | N/A |
262
285
 
263
286
  > **Note**: Linux and Windows implementations are functional but may require additional testing and refinement. Contributions are welcome!
264
287
 
@@ -266,34 +289,39 @@ For the complete spec, see **[aai.json Descriptor Spec](https://github.com/gybob
266
289
 
267
290
  - **PowerShell 5.1+** (comes with Windows 10+)
268
291
  - **Execution Policy**: Must allow script execution
292
+
269
293
  ```powershell
270
294
  # Check current policy
271
295
  Get-ExecutionPolicy
272
-
296
+
273
297
  # Set to allow local scripts (recommended)
274
298
  Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
275
299
  ```
300
+
276
301
  - **Credential Manager**: Built-in Windows feature, no additional setup needed
277
302
 
278
303
  #### Linux Requirements
279
304
 
280
305
  - **DBus**: Usually pre-installed on modern Linux distributions
281
306
  - **Dialog Tools**: Install one of the following:
307
+
282
308
  ```bash
283
309
  # Ubuntu/Debian
284
310
  sudo apt install zenity # or kdialog
285
-
311
+
286
312
  # Fedora
287
313
  sudo dnf install zenity # or kdialog
288
-
314
+
289
315
  # Arch Linux
290
316
  sudo pacman -S zenity # or kdialog
291
317
  ```
318
+
292
319
  - **libsecret**: For secure credential storage
320
+
293
321
  ```bash
294
322
  # Ubuntu/Debian
295
323
  sudo apt install libsecret-tools
296
-
324
+
297
325
  # Fedora
298
326
  sudo dnf install libsecret
299
327
  ```
@@ -306,95 +334,81 @@ The following apps are planned for future integration, organized by priority:
306
334
 
307
335
  #### 🚀 Priority P0 - High Activity + Simple Integration
308
336
 
309
- | App | Auth Type | API Base | Description |
310
- |-----|-----------|----------|-------------|
311
- | **GitHub** | OAuth2 / API Key | `api.github.com` | Code hosting, repositories, issues, PRs |
312
- | **Linear** | API Key | `api.linear.app` | Modern project management |
313
- | **Stripe** | API Key | `api.stripe.com` | Payment processing |
314
- | **Slack** | OAuth2 / Bot Token | `slack.com/api` | Team messaging and channels |
315
- | **Jira** | OAuth2 / API Token | `api.atlassian.com` | Issue and project tracking |
316
- | **Gitee** | API Key | `gitee.com/api/v5` | Code hosting (China) |
337
+ | App | Auth Type | API Base | Description |
338
+ | ---------- | ------------------ | ------------------- | --------------------------------------- |
339
+ | **GitHub** | OAuth2 / API Key | `api.github.com` | Code hosting, repositories, issues, PRs |
340
+ | **Linear** | API Key | `api.linear.app` | Modern project management |
341
+ | **Stripe** | API Key | `api.stripe.com` | Payment processing |
342
+ | **Slack** | OAuth2 / Bot Token | `slack.com/api` | Team messaging and channels |
343
+ | **Jira** | OAuth2 / API Token | `api.atlassian.com` | Issue and project tracking |
344
+ | **Gitee** | API Key | `gitee.com/api/v5` | Code hosting (China) |
317
345
 
318
346
  #### 🔥 Priority P1 - High Activity
319
347
 
320
- | App | Auth Type | API Base | Description |
321
- |-----|-----------|----------|-------------|
322
- | **Google Drive** | OAuth2 | `www.googleapis.com/drive` | Cloud storage and files |
323
- | **Google Calendar** | OAuth2 | `www.googleapis.com/calendar` | Calendar and scheduling |
324
- | **Airtable** | API Key / OAuth2 | `api.airtable.com` | Database and spreadsheets |
325
- | **Trello** | API Key + Token | `api.trello.com/1` | Kanban boards |
326
- | **Asana** | API Key / OAuth2 | `app.asana.com/api/1.0` | Project management |
327
- | **Discord** | Bot Token / OAuth2 | `discord.com/api/v10` | Community messaging |
328
- | **GitLab** | API Key / OAuth2 | `gitlab.com/api/v4` | DevOps platform |
329
- | **DingTalk (钉钉)** | App Credential | `api.dingtalk.com/v1.0` | Enterprise messaging (China) |
330
- | **WeCom (企业微信)** | App Credential | `qyapi.weixin.qq.com/cgi-bin` | Enterprise WeChat (China) |
348
+ | App | Auth Type | API Base | Description |
349
+ | -------------------- | ------------------ | ----------------------------- | ---------------------------- |
350
+ | **Google Drive** | OAuth2 | `www.googleapis.com/drive` | Cloud storage and files |
351
+ | **Google Calendar** | OAuth2 | `www.googleapis.com/calendar` | Calendar and scheduling |
352
+ | **Airtable** | API Key / OAuth2 | `api.airtable.com` | Database and spreadsheets |
353
+ | **Trello** | API Key + Token | `api.trello.com/1` | Kanban boards |
354
+ | **Asana** | API Key / OAuth2 | `app.asana.com/api/1.0` | Project management |
355
+ | **Discord** | Bot Token / OAuth2 | `discord.com/api/v10` | Community messaging |
356
+ | **GitLab** | API Key / OAuth2 | `gitlab.com/api/v4` | DevOps platform |
357
+ | **DingTalk (钉钉)** | App Credential | `api.dingtalk.com/v1.0` | Enterprise messaging (China) |
358
+ | **WeCom (企业微信)** | App Credential | `qyapi.weixin.qq.com/cgi-bin` | Enterprise WeChat (China) |
331
359
 
332
360
  #### 📈 Priority P2 - Medium Activity
333
361
 
334
362
  **Project Management & Collaboration:**
335
363
 
336
- | App | Auth Type | Description |
337
- |-----|-----------|-------------|
338
- | Monday.com | API Key | Work management platform |
339
- | ClickUp | API Key | Productivity platform |
340
- | Basecamp | OAuth2 | Project collaboration |
341
- | Bitbucket | API Key / OAuth2 | Git repository hosting |
364
+ | App | Auth Type | Description |
365
+ | ---------- | ---------------- | ------------------------ |
366
+ | Monday.com | API Key | Work management platform |
367
+ | ClickUp | API Key | Productivity platform |
368
+ | Basecamp | OAuth2 | Project collaboration |
369
+ | Bitbucket | API Key / OAuth2 | Git repository hosting |
342
370
 
343
371
  **Communication & Email:**
344
372
 
345
- | App | Auth Type | Description |
346
- |-----|-----------|-------------|
347
- | Gmail | OAuth2 | Email by Google |
348
- | Microsoft Outlook | OAuth2 | Email by Microsoft |
349
- | SendGrid | API Key | Email delivery service |
350
- | Mailgun | API Key | Email API service |
351
- | Twilio | API Key | SMS and voice API |
352
- | Tencent Meeting | OAuth2 / App Credential | Video conferencing (China) |
373
+ | App | Auth Type | Description |
374
+ | ----------------- | ----------------------- | -------------------------- |
375
+ | Gmail | OAuth2 | Email by Google |
376
+ | Microsoft Outlook | OAuth2 | Email by Microsoft |
377
+ | SendGrid | API Key | Email delivery service |
378
+ | Mailgun | API Key | Email API service |
379
+ | Twilio | API Key | SMS and voice API |
380
+ | Tencent Meeting | OAuth2 / App Credential | Video conferencing (China) |
353
381
 
354
382
  **Data & Storage:**
355
383
 
356
- | App | Auth Type | Description |
357
- |-----|-----------|-------------|
358
- | Supabase | API Key | Backend-as-a-Service |
359
- | PlanetScale | API Key | Serverless MySQL |
360
- | Neon | API Key | Serverless PostgreSQL |
361
- | Aliyun Drive | OAuth2 | Cloud storage (China) |
362
- | Baidu Netdisk | OAuth2 | Cloud storage (China) |
384
+ | App | Auth Type | Description |
385
+ | ------------- | --------- | --------------------- |
386
+ | Supabase | API Key | Backend-as-a-Service |
387
+ | PlanetScale | API Key | Serverless MySQL |
388
+ | Neon | API Key | Serverless PostgreSQL |
389
+ | Aliyun Drive | OAuth2 | Cloud storage (China) |
390
+ | Baidu Netdisk | OAuth2 | Cloud storage (China) |
363
391
 
364
392
  **Payments & Commerce:**
365
393
 
366
- | App | Auth Type | Description |
367
- |-----|-----------|-------------|
368
- | PayPal | OAuth2 | Payment platform |
369
- | Square | API Key | Payment processing |
370
- | Shopify | API Key | E-commerce platform |
394
+ | App | Auth Type | Description |
395
+ | ---------- | -------------- | ------------------------ |
396
+ | PayPal | OAuth2 | Payment platform |
397
+ | Square | API Key | Payment processing |
398
+ | Shopify | API Key | E-commerce platform |
371
399
  | WeChat Pay | App Credential | Payment platform (China) |
372
400
 
373
401
  #### 🔍 Priority P3 - Search & AI
374
402
 
375
- | App | Auth Type | API Base | Description |
376
- |-----|-----------|----------|-------------|
377
- | Brave Search | API Key | `api.search.brave.com/res/v1` | Privacy-focused search |
378
- | Perplexity | API Key | `api.perplexity.ai` | AI search engine |
379
- | Exa | API Key | `api.exa.ai` | AI-powered search |
380
- | Tavily | API Key | `api.tavily.com` | Search API for AI |
381
-
382
- #### ❌ Not Suitable for AAI Gateway
383
-
384
- The following MCP server types are **NOT suitable** for AAI Gateway as they require local implementation:
385
-
386
- | Type | Examples | Reason |
387
- |------|----------|--------|
388
- | Local Filesystem | Filesystem, Memory | Requires local file access |
389
- | Version Control | Git | Requires local git commands |
390
- | Browser Automation | Playwright, Puppeteer | Requires browser instance |
391
- | Code Execution | E2B, Riza | Requires sandbox environment |
392
- | Database Drivers | PostgreSQL, MySQL, SQLite | Requires database drivers |
393
- | System Commands | Shell, Terminal | Requires local command execution |
394
-
395
- ---
403
+ | App | Auth Type | API Base | Description |
404
+ | ------------ | --------- | ----------------------------- | ---------------------- |
405
+ | Brave Search | API Key | `api.search.brave.com/res/v1` | Privacy-focused search |
406
+ | Perplexity | API Key | `api.perplexity.ai` | AI search engine |
407
+ | Exa | API Key | `api.exa.ai` | AI-powered search |
408
+ | Tavily | API Key | `api.tavily.com` | Search API for AI |
396
409
 
397
410
  Want to see your app prioritized? [Open an issue](https://github.com/gybob/aai-gateway/issues).
411
+
398
412
  ## Links
399
413
 
400
414
  - **[AAI Protocol Spec](https://github.com/gybob/aai-protocol)** - Protocol specification
package/dist/cli.js CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { b as createDesktopDiscovery, d as createGatewayServer, l as logger } from "./server-BYtx5KIZ.js";
2
+ import { b as createDesktopDiscovery, d as createGatewayServer, l as logger } from "./server-DrBOLU_J.js";
3
3
  import { readFileSync } from "fs";
4
4
  import { fileURLToPath } from "url";
5
5
  import { dirname, join } from "path";
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import { A, a, C, T, c, b, d, e, f, g, h, i, l, p, s } from "./server-BYtx5KIZ.js";
1
+ import { A, a, C, T, c, b, d, e, f, g, h, i, l, p, s } from "./server-DrBOLU_J.js";
2
2
  export {
3
3
  A as AaiError,
4
4
  a as AaiGatewayServer,
@@ -7,7 +7,7 @@ export {
7
7
  c as createConsentDialog,
8
8
  b as createDesktopDiscovery,
9
9
  d as createGatewayServer,
10
- e as createIpcExecutor,
10
+ e as createNativeExecutor,
11
11
  f as createSecureStorage,
12
12
  g as executeWebTool,
13
13
  h as fetchWebDescriptor,