npm - aai-gateway - Versions diffs - 0.3.5 → 0.4.0 - Mend

aai-gateway 0.3.5 → 0.4.0

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 (9) hide show

package/README.md +190 -310
package/dist/cli.js +386 -74
package/dist/cli.js.map +1 -1
package/dist/index.js +465 -15
package/dist/index.js.map +1 -1
package/dist/{server-DrBOLU_J.js → server-C2Hyt-lR.js} +7361 -3031
package/dist/server-C2Hyt-lR.js.map +1 -0
package/package.json +1 -1
package/dist/server-DrBOLU_J.js.map +0 -1

package/README.md CHANGED Viewed

@@ -1,421 +1,301 @@
 # AAI Gateway
-## One MCP. All Apps. Zero Code Changes.
+## One MCP. Many Apps. Less Context.
-> 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.
+AAI Gateway turns many apps, agents, skills, and MCP servers into one MCP server.
-[![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)
+You connect your AI tool once. AAI Gateway handles discovery, import, routing, and exposure control behind that single entrypoint.
----
+Why this matters:
-## Why AAI Gateway?
+- One MCP connection instead of one MCP per app
+- Smaller context because tools are exposed at the app level first, not dumped all at once
+- A cleaner path to mix MCP servers, skills, ACP agents, and CLI-backed apps
-| 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** |
+AAI Gateway is for one goal: make tool ecosystems feel smaller, sharper, and easier for agents to use.
----
+## How To Use
-## Architecture
+### 1. Connect Your AI Tool To AAI Gateway
-![AAI Gateway Architecture](./images/architecture.png)
+You do not need to preinstall `aai-gateway`.
----
+Use the same style users already know from mainstream MCP setups: launch it through `npx`.
-## 🚀 Core Innovations
+### Claude Code
-Traditional MCP servers return all tools on `tools/list`, causing:
+Official docs: <https://code.claude.com/docs/en/mcp>
+```bash
+claude mcp add --transport stdio aai-gateway -- npx -y aai-gateway
 ```
-50 apps × 20 tools per app = 1000+ tool entries
-→ Context window explosion
-→ Agent performance degradation
-→ Reduced response accuracy
-```
-### 1. Progressive Disclosure
-AAI Gateway's solution:
-```
-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
-```
-**Result**: **95% reduction** in context usage, faster and more accurate Agent responses.
-### 2. Unified Descriptor
+### Codex
-Every integration is normalized through the same `aai.json` descriptor model. At a high level, the descriptor defines:
+Official docs: <https://developers.openai.com/learn/docs-mcp>
-- 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
+```bash
+codex mcp add aai-gateway -- npx -y aai-gateway
 ```
-### Desktop App Workflow
+### OpenCode
-```
-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
-```
+Official docs: <https://opencode.ai/docs/config> and <https://opencode.ai/docs/mcp-servers/>
-### ACP Agent Workflow
+Add this to `~/.config/opencode/opencode.json` or your project `opencode.json`:
-```
-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
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "aai-gateway": {
+      "type": "local",
+      "command": ["npx", "-y", "aai-gateway"],
+      "enabled": true
+    }
+  }
+}
 ```
-## 🔐 Security & Consent
+### What You Get After Connecting
-AAI Gateway implements a **caller-aware consent mechanism** to protect user privacy and control:
+Once connected, your AI tool can use AAI Gateway tools such as:
-### Per-Caller Authorization
+- `remote:discover`
+- `aai:exec`
+- `mcp:import`
+- `skill:import`
+- `mcp:refresh`
+- `import:config`
-- **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
+### 2. Import An MCP Server
-### Consent Flow
+The main workflow is: copy a mainstream MCP config snippet into your AI tool and ask it to import that server through AAI Gateway.
-```
-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)
-```
-This ensures that each MCP client has explicit user authorization, preventing cross-client authorization leakage.
-> 💡 **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.).
----
+The AI tool should:
-## 📱 Supported Apps
+1. read the MCP config you pasted
+2. ask you to choose an exposure mode
+3. call `mcp:import`
-These apps have built-in descriptors and work out of the box:
+AAI Gateway keeps the import parameters close to normal MCP config shapes:
-| 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                    |
+- stdio MCP: `command`, `args`, `env`, `cwd`
+- remote MCP: `url`, optional `transport`, optional `headers`
-> 💡 Want to add your app? See [How to Integrate](#how-to-integrate) | [Upcoming Apps](#upcoming-apps)
+Before import, the AI tool should ask you to choose:
-> ⚠️ **Note**: AAI Gateway is currently in active development. Bugs may exist. Contributions are welcome!
+- `summary`: easier automatic triggering
+- `keywords`: leaves room for more tools, but usually needs more explicit keyword mentions
----
-## Installation
-Add AAI Gateway to your MCP client configuration:
+Example: import a normal stdio MCP config
 ```json
 {
-  "mcpServers": {
-    "aai-gateway": {
-      "command": "npx",
-      "args": ["aai-gateway"]
-    }
-  }
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
 }
 ```
-<details>
-<summary>Claude Code</summary>
+Example: import a normal remote Streamable HTTP MCP config
-```bash
-claude mcp add aai-gateway npx aai-gateway
+```json
+{
+  "url": "https://example.com/mcp"
+}
 ```
-</details>
+Example: import a normal remote SSE MCP config
-<details>
-<summary>Claude Desktop</summary>
+```json
+{
+  "url": "https://example.com/sse",
+  "transport": "sse"
+}
+```
-Follow the [MCP installation guide](https://modelcontextprotocol.io/quickstart/user). Config: `~/Library/Application Support/Claude/claude_desktop_config.json`
+After import, AAI Gateway returns:
-</details>
+- the generated app id
+- the generated `keywords`
+- the generated `summary`
+- the guide tool name: `app:<id>`
-<details>
-<summary>Copilot / VS Code</summary>
+Important:
-```bash
-code --add-mcp '{"name":"aai-gateway","command":"npx","args":["aai-gateway"]}'
-```
+- 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.
-</details>
+### 3. Import A Skill
-<details>
-<summary>Cursor</summary>
+Skills are imported through the AI tool as well.
-`Cursor Settings` → `MCP` → `Add new MCP Server`. Name: `aai-gateway`, Type: `command`, Command: `npx aai-gateway`
+Ask the AI tool to call `skill:import`, then give it either:
-</details>
+- a local skill path
+- a remote skill root URL that exposes `SKILL.md`
-<details>
-<summary>OpenCode</summary>
+Examples:
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "aai-gateway": {
-      "type": "local",
-      "command": ["npx", "aai-gateway"],
-      "enabled": true
-    }
-  }
+  "path": "/absolute/path/to/skill"
 }
 ```
-</details>
----
-## CLI Options
-| Option      | Description                                     |
-| ----------- | ----------------------------------------------- |
-| `--dev`     | Development mode, scans Xcode build directories |
-| `--scan`    | Scan for AAI-enabled apps and exit              |
-| `--version` | Show version                                    |
-| `--help`    | Show help                                       |
----
-## Appendix
-### How to Integrate
-There are two ways to integrate an app with AAI Gateway today:
-#### Method 1: Provide a Descriptor File
+```json
+{
+  "url": "https://example.com/skill"
+}
+```
-Place an `aai.json` descriptor at the standard location:
+Just like MCP import, skill import returns:
-| 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`                  |
+- the generated app id
+- generated `keywords`
+- generated `summary`
+- the guide tool name: `app:<id>`
-AAI Gateway will automatically discover and load the descriptor.
+Then restart your AI tool before using the imported skill.
-#### Method 2: Contribute to Built-in Registry
+### 4. Supported ACP Agents
-For apps without a hosted descriptor, you can add a built-in descriptor:
+AAI Gateway can also control app-like agents through ACP.
-- **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`
+Currently supported ACP agent types:
-Then submit a pull request.
+- OpenCode
+- Claude Code
+- Codex
-> **Note**: ACP agents are auto-discovered by checking if the CLI command exists on the system.
+## App Auto Discovery
-#### Supported Auth Types
+AAI Gateway discovers apps from four places:
-| 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   |
+- desktop descriptors
+- web descriptors
+- gateway-managed imports
+- built-in ACP agent descriptors
-#### Platform Support
+### The AAI Descriptor
-| 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       |
+The descriptor is a small `aai.json` file. It tells AAI Gateway:
-> **Note**: Linux and Windows implementations are functional but may require additional testing and refinement. Contributions are welcome!
+- what the app is
+- how to connect to it
+- how to expose it at low context cost
-#### Windows Requirements
+Minimal example:
-- **PowerShell 5.1+** (comes with Windows 10+)
-- **Execution Policy**: Must allow script execution
+```json
+{
+  "schemaVersion": "2.0",
+  "version": "1.0.0",
+  "app": {
+    "name": {
+      "default": "Example App"
+    }
+  },
+  "access": {
+    "protocol": "cli",
+    "config": {
+      "command": "example-app"
+    }
+  },
+  "exposure": {
+    "keywords": ["example", "utility"],
+    "summary": "Use this app when the user wants to work with Example App."
+  }
+}
+```
-  ```powershell
-  # Check current policy
-  Get-ExecutionPolicy
+Supported `access.protocol` values today:
-  # Set to allow local scripts (recommended)
-  Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
-  ```
+- `mcp`
+- `skill`
+- `acp-agent`
+- `cli`
-- **Credential Manager**: Built-in Windows feature, no additional setup needed
+### Where To Put `aai.json`
-#### Linux Requirements
+#### Web Apps
-- **DBus**: Usually pre-installed on modern Linux distributions
-- **Dialog Tools**: Install one of the following:
+Publish it at:
-  ```bash
-  # Ubuntu/Debian
-  sudo apt install zenity  # or kdialog
+```text
+https://<your-host>/.well-known/aai.json
+```
-  # Fedora
-  sudo dnf install zenity  # or kdialog
+AAI Gateway fetches that path when the user calls `remote:discover`.
-  # Arch Linux
-  sudo pacman -S zenity  # or kdialog
-  ```
+#### macOS Apps
-- **libsecret**: For secure credential storage
+Recommended locations scanned by the gateway:
-  ```bash
-  # Ubuntu/Debian
-  sudo apt install libsecret-tools
+- `<YourApp>.app/Contents/Resources/aai.json`
+- `~/Library/Containers/<container>/Data/Library/Application Support/aai.json`
+- `~/Library/Containers/<container>/Data/Library/Application Support/aai-gateway/aai.json`
-  # Fedora
-  sudo dnf install libsecret
-  ```
+#### Linux Apps
----
+The gateway scans for `aai.json` under:
-### Upcoming Apps
+- `/usr/share`
+- `/usr/local/share`
+- `~/.local/share`
-The following apps are planned for future integration, organized by priority:
+#### Windows Apps
-#### 🚀 Priority P0 - High Activity + Simple Integration
+The gateway scans for `aai.json` under:
-| 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)                    |
+- `C:\Program Files`
+- `C:\Program Files (x86)`
+- `%LOCALAPPDATA%`
-#### 🔥 Priority P1 - High Activity
+### Descriptor Guidelines
-| 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)    |
+Keep descriptors small and practical:
-#### 📈 Priority P2 - Medium Activity
+- 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
-**Project Management & Collaboration:**
+If your app already speaks MCP, keep the descriptor minimal and let MCP provide tool detail lazily.
-| 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   |
+## Submit A Pull Request To Preload A Descriptor
-**Communication & Email:**
+If you want AAI Gateway to ship with a descriptor by default, open a PR.
-| 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) |
+What to include:
-**Data & Storage:**
+- 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
-| 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) |
+Today, built-in ACP agent descriptors live in:
-**Payments & Commerce:**
+- `src/discovery/descriptors/`
-| 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) |
+And they are registered in:
-#### 🔍 Priority P3 - Search & AI
+- `src/discovery/agent-registry.ts`
-| 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      |
+For a typical PR:
-Want to see your app prioritized? [Open an issue](https://github.com/gybob/aai-gateway/issues).
+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.
-## Links
+If you are unsure whether an integration should be bundled, open an issue first.
-- **[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
+## Disclaimer
----
+AAI Gateway is still under active development.
-## License
+You should expect rough edges, missing pieces, and bugs.
-Apache-2.0
+Contributions are welcome.