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

aai-gateway 0.3.5 → 0.4.2

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

package/README.md +195 -305
package/dist/cli.js +372 -83
package/dist/cli.js.map +1 -1
package/dist/index.js +471 -18
package/dist/index.js.map +1 -1
package/dist/server-TmWCZmyU.js +14678 -0
package/dist/server-TmWCZmyU.js.map +1 -0
package/package.json +23 -11
package/dist/server-DrBOLU_J.js +0 -11114
package/dist/server-DrBOLU_J.js.map +0 -1

package/README.md CHANGED Viewed

@@ -1,421 +1,311 @@
 # 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 through progressive disclosure — AAI Gateway never exposes raw tool definitions upfront
-| 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** |
+  **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.
----
+  **Two app interfaces, user chooses:**
-## Architecture
+  - `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 Architecture](./images/architecture.png)
+  Both modes keep the full tool capability available downstream — it just stays hidden until actually needed.
----
+- A cleaner path to mix MCP servers, skills, ACP agents, and CLI-backed apps
-## 🚀 Core Innovations
+AAI Gateway is for one goal: make tool ecosystems feel smaller, sharper, and easier for agents to use.
-Traditional MCP servers return all tools on `tools/list`, causing:
+## How To Use
-```
-50 apps × 20 tools per app = 1000+ tool entries
-→ Context window explosion
-→ Agent performance degradation
-→ Reduced response accuracy
-```
+### 1. Connect Your AI Tool To AAI Gateway
-### 1. Progressive Disclosure
+You do not need to preinstall `aai-gateway`.
-AAI Gateway's solution:
+Use the same style users already know from mainstream MCP setups: launch it through `npx`.
-```
-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
+### Claude Code
-= 50 apps + 2 tools = 52 entries ✅
+Official docs: <https://code.claude.com/docs/en/mcp>
-Agent calls web:discover or app:<id> on-demand to get detailed operation guides
+```bash
+claude mcp add --transport stdio aai-gateway -- npx -y aai-gateway
 ```
-**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)**.
----
+### Codex
-## How It Works
+Official docs: <https://developers.openai.com/learn/docs-mcp>
-### 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`:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "aai-gateway": {
+      "type": "local",
+      "command": ["npx", "-y", "aai-gateway"],
+      "enabled": true
+    }
+  }
+}
 ```
-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
-```
-## 🔐 Security & Consent
-AAI Gateway implements a **caller-aware consent mechanism** to protect user privacy and control:
-### Per-Caller Authorization
+### What You Get After Connecting
-- **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
+Once connected, your AI tool can use AAI Gateway tools such as:
-### Consent Flow
+- `remote:discover`
+- `aai:exec`
+- `mcp:import`
+- `skill:import`
+- `mcp:refresh`
+- `import:config`
-```
-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.).
----
+### 2. Import An MCP Server
-## 📱 Supported Apps
+The main workflow is: copy a mainstream MCP config snippet into your AI tool and ask it to import that server through AAI Gateway.
-These apps have built-in descriptors and work out of the box:
+The AI tool should:
-| 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                    |
+1. read the MCP config you pasted
+2. ask you to choose an exposure mode
+3. call `mcp:import`
-> 💡 Want to add your app? See [How to Integrate](#how-to-integrate) | [Upcoming Apps](#upcoming-apps)
+AAI Gateway keeps the import parameters close to normal MCP config shapes:
-> ⚠️ **Note**: AAI Gateway is currently in active development. Bugs may exist. Contributions are welcome!
+- stdio MCP: `command`, `args`, `env`, `cwd`
+- remote MCP: `url`, optional `transport`, optional `headers`
----
+Before import, the AI tool should ask you to choose:
-## Installation
+- `summary`: easier automatic triggering
+- `keywords`: leaves room for more tools, but usually needs more explicit keyword mentions
-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.