aai-gateway 0.3.2 → 0.3.5

package/README.md

@@ -1,121 +1,164 @@
 # AAI Gateway
 
-**One MCP to access all desktop and web applications.**
+## One MCP. All Apps. Zero Code Changes.
 
-A Model Context Protocol (MCP) server that bridges AI agents to desktop and web applications through the [AAI Protocol](https://github.com/gybob/aai-protocol).
+> A single MCP server that connects AI Agents to all Web and Desktop applications.
+> Apps conforming to the **[AAI Protocol](https://github.com/gybob/aai-protocol)** can be **seamlessly integrated** without developing any source code—just provide a descriptor.
 
-## The Innovation: Progressive Disclosure
+[![npm version](https://img.shields.io/npm/v/aai-gateway.svg)](https://www.npmjs.com/package/aai-gateway)
+[![License](https://img.shields.io/npm/l/aai-gateway.svg)](https://github.com/gybob/aai-gateway/blob/main/LICENSE)
 
-**Problem**: Traditional MCP servers load all tools upfront, causing context explosion.
+---
+
+## Why AAI Gateway?
+
+| Traditional Approach                        | AAI Gateway                                       |
+| ------------------------------------------- | ------------------------------------------------- |
+| One MCP Server per App                      | **One MCP for all applications**                  |
+| Requires modifying app code                 | **Zero-code integration, just a descriptor**      |
+| Loads all tools at once (context explosion) | **Progressive disclosure, load on-demand**        |
+| Platform-specific only                      | **Cross-platform: Web + macOS + Windows + Linux** |
+
+---
+
+## Architecture
+
+![AAI Gateway Architecture](./images/architecture.png)
+
+---
+
+## 🚀 Core Innovations
+
+Traditional MCP servers return all tools on `tools/list`, causing:
 
 ```
-Traditional: tools/list returns 1000+ tools from 50 apps
-→ Context window blown
-→ Agent confused
-→ Performance degraded
+50 apps × 20 tools per app = 1000+ tool entries
+→ Context window explosion
+→ Agent performance degradation
+→ Reduced response accuracy
 ```
 
-**Our Solution**: Guide-based progressive disclosure.
+### 1. Progressive Disclosure
+
+AAI Gateway's solution:
 
 ```
-AAI Gateway: tools/list returns 50 app entries + 2 universal tools
-→ O(apps + 2) instead of O(apps × tools)
-→ Agent calls app:<id> to get tool guide on-demand
-→ Context stays minimal
+tools/list returns only lightweight entries:
+├── web:discover         → Discover web apps and get their capabilities
+├── app:<desktop-app-id> → Discovered desktop apps (one entry per app)
+└── aai:exec             → Universal executor for all operations
+
+= 50 apps + 2 tools = 52 entries ✅
+
+Agent calls web:discover or app:<id> on-demand to get detailed operation guides
 ```
 
-This innovation enables agents to discover and use thousands of tools without overwhelming the context window.
+**Result**: **95% reduction** in context usage, faster and more accurate Agent responses.
+
+### 2. Unified Descriptor
+
+Every integration is normalized through the same `aai.json` descriptor model. At a high level, the descriptor defines:
+
+- App identity and metadata
+- Execution binding
+- Tool definitions
+- Parameter schemas
+- Authentication requirements
+
+For the full descriptor format, see the **[AAI Protocol `aai.json` spec](https://github.com/gybob/aai-protocol/blob/main/spec/aai-json.md)**.
+
+---
 
 ## How It Works
 
+### Web App Workflow
+
+```
+1. User: "Search my Notion workspace"
+2. Agent recognizes "Notion" as a web application
+   → Calls web:discover to fetch Notion's capabilities
+3. tools/call("web:discover", {url: "notion.com"})
+   → Returns operation guide: listDatabases(), queryDatabase(id), search(query)
+4. tools/call("aai:exec", {app: "notion.com", tool: "search", args: {...}})
+   → Executes and returns result
+```
+
+### Desktop App Workflow
+
+```
+1. AAI Gateway scans system for AAI-enabled desktop apps
+   → Found apps appear as app:<id> entries in tools/list
+2. User: "Show my work tasks"
+   → Agent finds matching app:guanchen.worklens
+3. tools/call("app:guanchen.worklens")
+   → Returns operation guide: listTasks(), getTaskDetail(id), createTask()
+4. tools/call("aai:exec", {app: "guanchen.worklens", tool: "listTasks", args: {}})
+   → Executes and returns result
+```
+
+### ACP Agent Workflow
+
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                    Desktop App Workflow                         │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  1. tools/list                                                   │
-│     └─→ Returns: ["app:com.apple.mail", "app:com.apple.calendar",
-│                   "web:discover", "aai:exec"]                    │
-│         Only 4 entries! (Not 50+ tools)                          │
-│                                                                  │
-│  2. User: "Send an email to John"                               │
-│     └─→ Agent matches "email" → calls app:com.apple.mail         │
-│                                                                  │
-│  3. tools/call("app:com.apple.mail")                            │
-│     └─→ Returns: Operation guide with available tools            │
-│         - sendEmail(to, subject, body)                           │
-│         - readInbox(folder, limit)                               │
-│         - ...                                                    │
-│                                                                  │
-│  4. tools/call("aai:exec", {app, tool: "sendEmail", args})       │
-│     └─→ Executes operation                                        │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────────┐
-│                      Web App Workflow                            │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  1. User: "Search my Notion workspace"                          │
-│     └─→ Agent matches "Notion" → calls web:discover              │
-│                                                                  │
-│  2. tools/call("web:discover", {url: "notion.com"})              │
-│     └─→ Returns: Operation guide with available tools            │
-│         - listDatabases(), queryDatabase(id), search(query)      │
-│         - ...                                                    │
-│                                                                  │
-│  3. tools/call("aai:exec", {app: "notion.com", tool, args})      │
-│     └─→ Executes operation                                        │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
+1. AAI Gateway scans for installed ACP agents at startup
+   → Found agents appear as app:<agent-id> entries in tools/list
+2. User: "Use OpenCode to refactor this code"
+   → Agent finds matching app:dev.sst.opencode
+3. tools/call("app:dev.sst.opencode")
+   → Returns operation guide: session/new(), session/prompt(message)
+4. tools/call("aai:exec", {app: "dev.sst.opencode", tool: "session/prompt", args: {message: "refactor this code"}})
+   → Executes via ACP (stdio JSON-RPC) and returns result
 ```
 
-**Context Efficiency**:
+## 🔐 Security & Consent
 
-- Traditional: 50 apps × 20 tools = 1000 context entries
-- AAI Gateway: 50 apps + 2 = 52 context entries
+AAI Gateway implements a **caller-aware consent mechanism** to protect user privacy and control:
 
-## Features
+### Per-Caller Authorization
 
-- **Progressive Disclosure**. Apps expose operation guides on-demand, preventing context explosion.
-- **Multi-language Support**. App names support multiple languages for better intent matching.
-- **Native Security**. Leverages OS-level consent (TCC, UAC, Polkit) and secure storage (Keychain).
-- **Cross-platform**. macOS today, Linux and Windows planned.
+- **Client Identification**: When an MCP client (Claude Desktop, Cursor, Windsurf, etc.) requests tool access, AAI Gateway identifies the caller from the MCP protocol metadata
+- **Isolated Consent**: Consent decisions are stored **per caller**, meaning authorization granted to Claude Desktop is NOT automatically granted to Cursor
+- **Clear Dialogs**: Consent dialogs clearly show which client is requesting access: "Claude Desktop wants to use: sendEmail"
+- **Re-authorization Required**: Different MCP clients must obtain their own authorization for the same tools
 
-## Supported Apps
+### Consent Flow
 
-### Desktop Apps (AAI-enabled)
+```
+1. MCP client (e.g., Cursor) calls a tool for the first time
+2. AAI Gateway checks: Has Cursor been authorized for this tool?
+3. If not → Show consent dialog: "Cursor wants to use: sendEmail"
+4. User decision is stored with caller identity: consents["Cursor"]["com.example.mail"]["sendEmail"]
+5. Next call from Cursor → No dialog (already authorized)
+6. Claude Desktop calls same tool → Consent dialog shown (different caller)
+```
 
-Apps shipping `aai.json` descriptor:
+This ensures that each MCP client has explicit user authorization, preventing cross-client authorization leakage.
 
-| App             | Platform | Tools                                           |
-| --------------- | -------- | ----------------------------------------------- |
-| macOS Reminders | macOS    | createReminder, listReminders, completeReminder |
-| Your app here   | -        | -                                               |
+> 💡 **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.).
 
-### Web Apps (Built-in Descriptors)
+---
 
-Pre-configured descriptors for cold-start scenarios when `.well-known/aai.json` is unavailable:
+## 📱 Supported Apps
 
-| App               | Auth Type      | Description              |
-| ----------------- | -------------- | ------------------------ |
-| **Notion**        | API Key        | All-in-one workspace     |
-| **Yuque (语雀)**  | API Key        | Knowledge management     |
-| **Feishu (飞书)** | App Credential | Enterprise collaboration |
+These apps have built-in descriptors and work out of the box:
 
-_More built-in descriptors being added. [Request one](https://github.com/gybob/aai-gateway/issues)_
+| App               | Type      | Auth Type      | Tools | Description                                         |
+| ----------------- | --------- | -------------- | ----- | --------------------------------------------------- |
+| **Notion**        | Web       | API Key        | 11    | Notes, docs, knowledge base, project management     |
+| **Yuque (语雀)**  | Web       | API Key        | 7     | Alibaba Cloud knowledge management platform         |
+| **Feishu / Lark** | Web       | App Credential | 11    | Enterprise collaboration (docs, wiki, IM, calendar) |
+| **OpenCode**      | ACP Agent | None           | 4     | Open-source AI coding agent with terminal UI        |
+| **Claude Code**   | ACP Agent | None           | 4     | Anthropic's official AI coding agent                |
+| **Gemini CLI**    | ACP Agent | None           | 4     | Google's Gemini CLI coding agent                    |
 
-## Requirements
+> 💡 Want to add your app? See [How to Integrate](#how-to-integrate) | [Upcoming Apps](#upcoming-apps)
 
-- Node.js 18 or newer
-- macOS (Linux and Windows support planned)
-- VS Code, Cursor, Windsurf, Claude Desktop, or any MCP client
+> ⚠️ **Note**: AAI Gateway is currently in active development. Bugs may exist. Contributions are welcome!
 
-## Getting Started
+---
 
-Add AAI Gateway to your MCP client configuration.
+## Installation
 
-**Standard config:**
+Add AAI Gateway to your MCP client configuration:
 
 ```json
 {
@@ -140,7 +183,7 @@ claude mcp add aai-gateway npx aai-gateway
 <details>
 <summary>Claude Desktop</summary>
 
-Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above. Config file location: `~/Library/Application Support/Claude/claude_desktop_config.json`
+Follow the [MCP installation guide](https://modelcontextprotocol.io/quickstart/user). Config: `~/Library/Application Support/Claude/claude_desktop_config.json`
 
 </details>
 
@@ -151,22 +194,18 @@ Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user),
 code --add-mcp '{"name":"aai-gateway","command":"npx","args":["aai-gateway"]}'
 ```
 
-Or add manually to your MCP settings.
-
 </details>
 
 <details>
 <summary>Cursor</summary>
 
-Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name: `aai-gateway`, type: `command`, command: `npx aai-gateway`.
+`Cursor Settings` → `MCP` → `Add new MCP Server`. Name: `aai-gateway`, Type: `command`, Command: `npx aai-gateway`
 
 </details>
 
 <details>
 <summary>OpenCode</summary>
 
-Add to `~/.config/opencode/opencode.json`:
-
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
@@ -180,225 +219,202 @@ Add to `~/.config/opencode/opencode.json`:
 }
 ```
 
-With `--dev` flag:
+</details>
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "aai-gateway": {
-      "type": "local",
-      "command": ["npx", "aai-gateway", "--dev"],
-      "enabled": true
-    }
-  }
-}
-```
+---
 
-</details>
+## CLI Options
 
-## Configuration
+| Option      | Description                                     |
+| ----------- | ----------------------------------------------- |
+| `--dev`     | Development mode, scans Xcode build directories |
+| `--scan`    | Scan for AAI-enabled apps and exit              |
+| `--version` | Show version                                    |
+| `--help`    | Show help                                       |
 
-| Option      | Description                                                                    |
-| ----------- | ------------------------------------------------------------------------------ |
-| `--dev`     | Enable development mode. Scans Xcode build directories for apps in development |
-| `--scan`    | Scan for AAI-enabled apps and exit (for debugging)                             |
-| `--version` | Show version                                                                   |
-| `--help`    | Show help                                                                      |
+---
 
-**Development mode example:**
+## Appendix
 
-```json
-{
-  "mcpServers": {
-    "aai-gateway": {
-      "command": "npx",
-      "args": ["aai-gateway", "--dev"]
-    }
-  }
-}
-```
+### How to Integrate
 
-## MCP Interface
+There are two ways to integrate an app with AAI Gateway today:
 
-AAI Gateway exposes **tools only** (no resources). This simplifies the agent workflow.
+#### Method 1: Provide a Descriptor File
 
-### `tools/list`
+Place an `aai.json` descriptor at the standard location:
 
-Returns discovered desktop apps plus universal tools:
+| Platform    | Location                                     |
+| ----------- | -------------------------------------------- |
+| **Web**     | `https://<your-domain>/.well-known/aai.json` |
+| **macOS**   | `<App>.app/Contents/Resources/aai.json`      |
+| **Windows** | `<App>.exe directory/aai.json`               |
+| **Linux**   | `/usr/share/<app>/aai.json`                  |
 
-```json
-{
-  "tools": [
-    {
-      "name": "app:com.apple.reminders",
-      "description": "【Reminders|提醒事项|Rappels】macOS reminders app. Aliases: todo, 待办. Call to get guide.",
-      "inputSchema": { "type": "object", "properties": {} }
-    },
-    {
-      "name": "web:discover",
-      "description": "Discover web app guide. Use when user mentions a web service not in list.",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "url": { "type": "string", "description": "Web app URL, domain, or name" }
-        },
-        "required": ["url"]
-      }
-    },
-    {
-      "name": "aai:exec",
-      "description": "Execute app operation. Use after reading the operation guide.",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "app": { "type": "string", "description": "App ID or URL" },
-          "tool": { "type": "string", "description": "Operation name" },
-          "args": { "type": "object", "description": "Operation parameters" }
-        },
-        "required": ["app", "tool"]
-      }
-    }
-  ]
-}
-```
+AAI Gateway will automatically discover and load the descriptor.
 
-### App Tool (`app:*`)
+#### Method 2: Contribute to Built-in Registry
 
-Call `app:<app-id>` to get an operation guide:
+For apps without a hosted descriptor, you can add a built-in descriptor:
 
-```json
-{
-  "name": "app:com.apple.reminders",
-  "arguments": {}
-}
-```
+- **Web App**: Create `src/discovery/descriptors/<app>.ts`, register in `src/discovery/web-registry.ts`
+- **ACP Agent**: Create `src/discovery/descriptors/<agent>-agent.ts`, register in `src/discovery/agent-registry.ts`
 
-Returns a guide with available operations, parameters, and usage examples.
+Then submit a pull request.
 
-### Web Discovery (`web:discover`)
+> **Note**: ACP agents are auto-discovered by checking if the CLI command exists on the system.
 
-Discover web apps by URL, domain, or name:
+#### Supported Auth Types
 
-```json
-{
-  "name": "web:discover",
-  "arguments": { "url": "notion.com" }
-}
-```
+| Type            | Use Case           | User Flow                  |
+| --------------- | ------------------ | -------------------------- |
+| `oauth2`        | User authorization | Browser OAuth 2.0 + PKCE   |
+| `apiKey`        | Static API tokens  | Dialog prompts for token   |
+| `appCredential` | Enterprise apps    | Dialog for App ID + Secret |
+| `cookie`        | No official API    | Manual cookie extraction   |
 
-Returns the web app's operation guide.
+#### Platform Support
 
-### Tool Execution (`aai:exec`)
+| Platform    | Discovery              | IPC              | Consent        | Storage   |
+| ----------- | ---------------------- | ---------------- | -------------- | --------- |
+| **macOS**   | Supported              | Apple Events     | osascript      | Keychain  |
+| **Linux**   | XDG paths              | DBus (gdbus)     | zenity/kdialog | libsecret |
+| **Windows** | Program Files          | COM (PowerShell) | PowerShell     | CredMan   |
+| **Web**     | `.well-known/aai.json` | HTTP             | N/A            | Platform  |
+| **Stdio**   | Protocol only          | Planned          | N/A            | N/A       |
 
-Execute operations after reading the guide:
+> **Note**: Linux and Windows implementations are functional but may require additional testing and refinement. Contributions are welcome!
 
-```json
-{
-  "name": "aai:exec",
-  "arguments": {
-    "app": "com.apple.reminders",
-    "tool": "createReminder",
-    "args": {
-      "title": "Submit report",
-      "due": "2024-12-31 15:00"
-    }
-  }
-}
-```
+#### Windows Requirements
 
-**Execution flow:**
+- **PowerShell 5.1+** (comes with Windows 10+)
+- **Execution Policy**: Must allow script execution
 
-1. Resolve app descriptor (local, built-in, or web fetch)
-2. Show native consent dialog — user approves/denies
-3. **Auth**:
-   - Desktop apps: Native IPC
-   - Web apps: OAuth 2.1 PKCE, API Key, App Credential, or Cookie
-4. Execute and return result
+  ```powershell
+  # Check current policy
+  Get-ExecutionPolicy
 
-## Authentication Types
+  # Set to allow local scripts (recommended)
+  Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
+  ```
 
-| Auth Type       | Use Case           | User Flow                          |
-| --------------- | ------------------ | ---------------------------------- |
-| `oauth2`        | User authorization | Browser-based OAuth 2.0 with PKCE  |
-| `apiKey`        | Static API tokens  | Dialog prompts for token           |
-| `appCredential` | Enterprise apps    | Dialog prompts for App ID + Secret |
-| `cookie`        | No official API    | Manual cookie extraction           |
+- **Credential Manager**: Built-in Windows feature, no additional setup needed
 
-## Platform Support
+#### Linux Requirements
 
-| Platform | Discovery                 | IPC Executor    | Consent Dialog    | Secure Storage        |
-| -------- | ------------------------- | --------------- | ----------------- | --------------------- |
-| macOS    | ✅                        | ✅ Apple Events | ✅ osascript      | ✅ Keychain           |
-| Linux    | ⚠️ XDG paths              | ⚠️ DBus        | ⚠️ zenity/kdialog | ⚠️ libsecret          |
-| Windows  | ⚠️ Program Files          | ⚠️ COM         | ⚠️ PowerShell     | ⚠️ Credential Manager |
-| Web      | ✅ `.well-known/aai.json` | ✅ HTTP + Auth  | —                 | ✅ (via platform)     |
+- **DBus**: Usually pre-installed on modern Linux distributions
+- **Dialog Tools**: Install one of the following:
 
-**Legend**: ✅ Fully implemented | ⚠️ Stub implementation (throws NOT_IMPLEMENTED) | 🔜 Planned
+  ```bash
+  # Ubuntu/Debian
+  sudo apt install zenity  # or kdialog
 
-## For App Developers
+  # Fedora
+  sudo dnf install zenity  # or kdialog
 
-To make your app discoverable by AAI Gateway, ship an `aai.json` descriptor:
+  # Arch Linux
+  sudo pacman -S zenity  # or kdialog
+  ```
 
-**macOS:** `<App>.app/Contents/Resources/aai.json`
+- **libsecret**: For secure credential storage
 
-**Web:** `https://<your-domain>/.well-known/aai.json`
+  ```bash
+  # Ubuntu/Debian
+  sudo apt install libsecret-tools
 
-**Example:**
+  # Fedora
+  sudo dnf install libsecret
+  ```
 
-```json
-{
-  "schemaVersion": "1.0",
-  "version": "1.0.0",
-  "platform": "web",
-  "app": {
-    "id": "com.example.api",
-    "name": {
-      "en": "Example App",
-      "zh-CN": "示例应用"
-    },
-    "defaultLang": "en",
-    "description": "Brief description",
-    "aliases": ["example", "示例"]
-  },
-  "auth": {
-    "type": "apiKey",
-    "apiKey": {
-      "location": "header",
-      "name": "Authorization",
-      "prefix": "Bearer",
-      "obtainUrl": "https://example.com/settings/tokens"
-    }
-  },
-  "tools": [...]
-}
-```
+---
 
-See the [AAI Protocol Spec](https://github.com/gybob/aai-protocol) for the full schema.
+### Upcoming Apps
 
-## Debugging
+The following apps are planned for future integration, organized by priority:
 
-```bash
-# List discovered AAI-enabled apps
-npx aai-gateway --scan
+#### 🚀 Priority P0 - High Activity + Simple Integration
 
-# Include Xcode build products
-npx aai-gateway --scan --dev
-```
+| App        | Auth Type          | API Base            | Description                             |
+| ---------- | ------------------ | ------------------- | --------------------------------------- |
+| **GitHub** | OAuth2 / API Key   | `api.github.com`    | Code hosting, repositories, issues, PRs |
+| **Linear** | API Key            | `api.linear.app`    | Modern project management               |
+| **Stripe** | API Key            | `api.stripe.com`    | Payment processing                      |
+| **Slack**  | OAuth2 / Bot Token | `slack.com/api`     | Team messaging and channels             |
+| **Jira**   | OAuth2 / API Token | `api.atlassian.com` | Issue and project tracking              |
+| **Gitee**  | API Key            | `gitee.com/api/v5`  | Code hosting (China)                    |
 
-## Development
+#### 🔥 Priority P1 - High Activity
 
-```bash
-npm install
-npm run typecheck
-npm test
-npm run build
-```
+| App                  | Auth Type          | API Base                      | Description                  |
+| -------------------- | ------------------ | ----------------------------- | ---------------------------- |
+| **Google Drive**     | OAuth2             | `www.googleapis.com/drive`    | Cloud storage and files      |
+| **Google Calendar**  | OAuth2             | `www.googleapis.com/calendar` | Calendar and scheduling      |
+| **Airtable**         | API Key / OAuth2   | `api.airtable.com`            | Database and spreadsheets    |
+| **Trello**           | API Key + Token    | `api.trello.com/1`            | Kanban boards                |
+| **Asana**            | API Key / OAuth2   | `app.asana.com/api/1.0`       | Project management           |
+| **Discord**          | Bot Token / OAuth2 | `discord.com/api/v10`         | Community messaging          |
+| **GitLab**           | API Key / OAuth2   | `gitlab.com/api/v4`           | DevOps platform              |
+| **DingTalk (钉钉)**  | App Credential     | `api.dingtalk.com/v1.0`       | Enterprise messaging (China) |
+| **WeCom (企业微信)** | App Credential     | `qyapi.weixin.qq.com/cgi-bin` | Enterprise WeChat (China)    |
+
+#### 📈 Priority P2 - Medium Activity
+
+**Project Management & Collaboration:**
+
+| App        | Auth Type        | Description              |
+| ---------- | ---------------- | ------------------------ |
+| Monday.com | API Key          | Work management platform |
+| ClickUp    | API Key          | Productivity platform    |
+| Basecamp   | OAuth2           | Project collaboration    |
+| Bitbucket  | API Key / OAuth2 | Git repository hosting   |
+
+**Communication & Email:**
+
+| App               | Auth Type               | Description                |
+| ----------------- | ----------------------- | -------------------------- |
+| Gmail             | OAuth2                  | Email by Google            |
+| Microsoft Outlook | OAuth2                  | Email by Microsoft         |
+| SendGrid          | API Key                 | Email delivery service     |
+| Mailgun           | API Key                 | Email API service          |
+| Twilio            | API Key                 | SMS and voice API          |
+| Tencent Meeting   | OAuth2 / App Credential | Video conferencing (China) |
+
+**Data & Storage:**
+
+| App           | Auth Type | Description           |
+| ------------- | --------- | --------------------- |
+| Supabase      | API Key   | Backend-as-a-Service  |
+| PlanetScale   | API Key   | Serverless MySQL      |
+| Neon          | API Key   | Serverless PostgreSQL |
+| Aliyun Drive  | OAuth2    | Cloud storage (China) |
+| Baidu Netdisk | OAuth2    | Cloud storage (China) |
+
+**Payments & Commerce:**
+
+| App        | Auth Type      | Description              |
+| ---------- | -------------- | ------------------------ |
+| PayPal     | OAuth2         | Payment platform         |
+| Square     | API Key        | Payment processing       |
+| Shopify    | API Key        | E-commerce platform      |
+| WeChat Pay | App Credential | Payment platform (China) |
+
+#### 🔍 Priority P3 - Search & AI
+
+| App          | Auth Type | API Base                      | Description            |
+| ------------ | --------- | ----------------------------- | ---------------------- |
+| Brave Search | API Key   | `api.search.brave.com/res/v1` | Privacy-focused search |
+| Perplexity   | API Key   | `api.perplexity.ai`           | AI search engine       |
+| Exa          | API Key   | `api.exa.ai`                  | AI-powered search      |
+| Tavily       | API Key   | `api.tavily.com`              | Search API for AI      |
+
+Want to see your app prioritized? [Open an issue](https://github.com/gybob/aai-gateway/issues).
 
 ## Links
 
-- [AAI Protocol Spec](https://github.com/gybob/aai-protocol)
-- [Report Issues](https://github.com/gybob/aai-gateway/issues)
+- **[AAI Protocol Spec](https://github.com/gybob/aai-protocol)** - Protocol specification
+- [Report Issues](https://github.com/gybob/aai-gateway/issues) - Bug reports and feature requests
+
+---
 
 ## License