wwise-waapi-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright 2026 Li Major
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# Wwise MCP Server
+
+[中文文档](README_ZH.md)
+
+Lightweight Node.js + TypeScript MCP server for Wwise WAAPI.
+
+⭐ Uses progressive tool discovery. Avoiding consuming large tokens by exposing the full WAAPI tool surface at once.
+
+⭐ Use locally installed Wwise's WAAPI Json Schema for full WAAPI capabilities.
+
+## Quick start
+
+### Install dependencies
+
+```bash
+npm i
+```
+
+### Configure Wwise install ROOT and WAAPI connection
+
+   Configurations are stored in `config/runtime.json`
+
+   If you leave the `wwiseRoot` configuration empty, or the path is invalid, the tool will use `%WWISEROOT%` to try finding the path.
+
+   The `waapiUrl` defaults to `ws://127.0.0.1:8080/waapi` if not specified.
+
+```json
+// Example
+{
+  "wwiseRoot": "C:/Program Files (x86)/Audiokinetic/Wwise 2024.1.0.8669",
+  "waapiUrl": "ws://127.0.0.1:8080/waapi"
+}
+```
+
+### Run in development (stdio default)
+
+```bash
+npm run dev
+```
+
+### Or build and run
+
+```bash
+npm run build
+npm start
+```
+
+## Schema source and startup requirements
+
+This project does not redistribute Audiokinetic WAAPI schema JSON files.
+
+At startup, the server resolves WAAPI schema directory using this priority:
+
+1. `config/runtime.json` -> `wwiseRoot`
+2. `WWISEROOT` environment variable
+3. Live WAAPI probe:
+   - call `ak.wwise.core.getProjectInfo` to confirm a project is open
+   - call `ak.wwise.core.getInfo` and read `directories.install`
+
+Expected schema path under root:
+
+```text
+<WwiseRoot>/Authoring/Data/Schemas/WAAPI
+```
+
+If all probes fail, startup exits with `waapi_schema_not_found`.
+
+## Core capabilities
+
+- Layered architecture: `core` + `registry` + `domains` + `lib`.
+- Progressive-disclosure MCP surface:
+  - `tools/list` only exposes discovery tools, not every runtime WAAPI tool
+  - currently exposed discovery tools:
+    - `catalog.listDomains`
+    - `catalog.listTools`
+    - `catalog.getToolSchema`
+    - `catalog.executeTool`
+- Discovery and execution flow:
+  - `catalog.listDomains`
+  - `catalog.listTools`
+  - `catalog.getToolSchema`
+  - `catalog.executeTool`
+- Runtime-backed WAAPI tools across major domains.
+- Standard response envelope:
+  - success: `{ ok: true, data: ... }`
+  - failure: `{ ok: false, error: { code, message, details? } }`
+- Structured tool call logs with sensitive-field redaction.
+
+Implemented WAAPI surface details are tracked in `docs/implemented-waapi.md`.
+
+## Transport modes
+
+### stdio mode (default)
+
+Use for standard MCP clients that spawn the server as a subprocess.
+
+```bash
+npm run dev
+```
+
+```bash
+npm start
+# equivalent to: node dist/src/index.js
+```
+
+Example MCP client config:
+
+```json
+{
+  "servers": {
+    "wwise-mcp": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["dist/src/index.js"]
+    }
+  }
+}
+```
+
+### HTTP/SSE mode
+
+Use when you want a long-running MCP endpoint over HTTP.
+
+```bash
+node dist/src/index.js --http
+```
+
+```bash
+node dist/src/index.js --http --port 8080
+```
+
+```bash
+MCP_TRANSPORT=http PORT=8080 node dist/src/index.js
+```
+
+HTTP endpoint summary:
+
+| Method | Path | Purpose |
+| :-- | :-- | :-- |
+| `POST` | `/mcp` | Send JSON-RPC requests. Omit `mcp-session-id` on first `initialize` to create session. |
+| `GET` | `/mcp` | Open standalone SSE stream for server notifications. Requires `mcp-session-id`. |
+| `DELETE` | `/mcp` | Close session. Requires `mcp-session-id`. |
+
+Port selection priority:
+
+1. `--port <n>`
+2. `PORT` env var
+3. default `3000`
+
+The HTTP server binds to `127.0.0.1` by default.
+
+## Verify
+
+```bash
+npm run build
+npm run verify
+```
+
+Verification checks:
+
+- only discovery tools are registered through MCP `tools/list`
+- domains can be enumerated through `catalog.listDomains`
+- domain-local tools can be discovered through `catalog.listTools`
+- one tool schema can be queried through `catalog.getToolSchema`
+- one runtime WAAPI call can be executed through `catalog.executeTool`
+- WAAPI failure is still returned as a structured error when WAAPI is unavailable
+
+Note: verify requires schema path resolution to succeed first.
+
+## WAAPI connection
+
+Default WAAPI URL:
+
+```bash
+ws://127.0.0.1:8080/waapi
+```
+
+Configure in `config/runtime.json`:
+
+```json
+{
+  "waapiUrl": "ws://host:port/waapi"
+}
+```
+
+## Access filtering
+
+Optional startup filters:
+
+- `WWISE_MCP_ALLOWED_DOMAINS=object,soundengine`
+- `WWISE_MCP_ALLOWED_RISKS=low,medium`
+- `WWISE_MCP_ALLOWED_PERMISSIONS=waapi:authoring:read,waapi:runtime`
+
+## Package as EXE
+
+```bash
+npm run package:exe
+```
+
+Output file: `bin/wwise-mcp.exe`
+
+## Manual validation
+
+After startup, call tools in this order:
+
+1. `catalog.listDomains`
+2. `catalog.listTools` with `{ "domain": "object", "includePlanned": true }`
+3. `catalog.getToolSchema` with `{ "toolName": "ak.wwise.core.object.get" }`
+4. `catalog.executeTool` with `{ "toolName": "ak.wwise.core.object.get", "arguments": { ... } }`
+
+This is the intended progressive-disclosure path: domain summary -> tool summary -> schema details -> execution.
+
+The practical implication is that MCP clients no longer receive the full callable WAAPI surface during `tools/list`. They first discover available domains and tools, then request schema details for one tool, and only then execute that tool through the unified `catalog.executeTool` entrypoint.
+
+## Extend with new domains
+
+1. Copy `src/domains/example/tools.ts` to a new domain folder.
+2. Export `getYourDomainTools()` returning `ToolDefinition[]`.
+3. Add domain metadata to `config/domains.json`.
+4. Import/register tools in `src/index.ts`.
+5. Extend `src/lib/referenceCatalog.ts` mapping when needed.

package/README_ZH.md

@@ -0,0 +1,221 @@
+# Wwise MCP 服务器
+
+[English Doc](README.md)
+
+一个轻量级的 Node.js + TypeScript Wwise WAAPI MCP 服务器
+
+⭐ 使用渐进式工具发现，避免同时给出大量 MCP 工具而消耗大量 Tokens
+
+⭐ 该工具依赖本地安装的 Wwise 中附带的 WAAPI Json Schema，因此可以提供完全的 WAAPI 能力。
+
+## 快速开始
+
+### 安装依赖
+
+```bash
+npm i
+```
+
+### 配置 Wwise 安装目录和 WAAPI 连接地址
+
+在 `config/runtime.json` 中进行配置
+
+   如果 `wwiseRoot` 配置留空，或路径无效，工具会尝试使用 `%WWISEROOT%` 查找路径
+
+   若未指定 `waapiUrl`，则默认使用 `ws://127.0.0.1:8080/waapi`
+
+```json
+// 示例
+{
+  "wwiseRoot": "C:/Program Files (x86)/Audiokinetic/Wwise 2024.1.0.8669",
+  "waapiUrl": "ws://127.0.0.1:8080/waapi"
+}
+```
+
+### 开发模式运行（默认 stdio）
+
+```bash
+npm run dev
+```
+
+### 或者先构建再运行
+
+```bash
+npm run build
+npm start
+```
+
+## Schema 来源与启动要求
+
+本项目不会重新分发 Audiokinetic 的 WAAPI schema JSON 文件。
+
+启动时，服务器会按以下优先级解析 WAAPI schema 目录：
+
+1. `config/runtime.json` -> `wwiseRoot`
+2. `WWISEROOT` 环境变量
+3. 在线 WAAPI 探测：
+   - 调用 `ak.wwise.core.getProjectInfo` 确认当前有已打开工程
+   - 调用 `ak.wwise.core.getInfo` 并读取 `directories.install`
+
+期望的 schema 子目录为：
+
+```text
+<WwiseRoot>/Authoring/Data/Schemas/WAAPI
+```
+
+如果以上探测都失败，启动会以 `waapi_schema_not_found` 退出。
+
+## 核心能力
+
+- 分层架构：`core` + `registry` + `domains` + `lib`。
+- 渐进式对外暴露：
+  - MCP 的 `tools/list` 只暴露发现工具，不会一次性暴露所有运行时 WAAPI 工具
+  - 当前对外暴露的发现工具为：
+    - `catalog.listDomains`
+    - `catalog.listTools`
+    - `catalog.getToolSchema`
+    - `catalog.executeTool`
+- 渐进式发现与执行流程：
+  - `catalog.listDomains`
+  - `catalog.listTools`
+  - `catalog.getToolSchema`
+  - `catalog.executeTool`
+- 覆盖主要 Domain 的 WAAPI 运行时工具。
+- 统一响应封装：
+  - 成功：`{ ok: true, data: ... }`
+  - 失败：`{ ok: false, error: { code, message, details? } }`
+- 结构化工具调用日志，并对敏感字段做脱敏处理。
+
+已实现的 WAAPI 接口覆盖详情见 `docs/implemented-waapi.md`。
+
+## 传输模式
+
+### stdio 模式（默认）
+
+用于标准 MCP 客户端以子进程方式拉起服务器的场景。
+
+```bash
+npm run dev
+```
+
+```bash
+npm start
+# 等价于: node dist/src/index.js
+```
+
+MCP 客户端配置示例：
+
+```json
+{
+  "servers": {
+    "wwise-mcp": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["dist/src/index.js"]
+    }
+  }
+}
+```
+
+### HTTP/SSE 模式
+
+用于以 HTTP 形式长期运行 MCP 端点的场景。
+
+```bash
+node dist/src/index.js --http
+```
+
+```bash
+node dist/src/index.js --http --port 8080
+```
+
+```bash
+MCP_TRANSPORT=http PORT=8080 node dist/src/index.js
+```
+
+HTTP 端点说明：
+
+| Method | Path | Purpose |
+| :-- | :-- | :-- |
+| `POST` | `/mcp` | 发送 JSON-RPC 请求。首次 `initialize` 不带 `mcp-session-id` 以创建会话。 |
+| `GET` | `/mcp` | 打开独立 SSE 通道用于服务端通知。需要 `mcp-session-id`。 |
+| `DELETE` | `/mcp` | 关闭会话。需要 `mcp-session-id`。 |
+
+端口选择优先级：
+
+1. `--port <n>`
+2. `PORT` 环境变量
+3. 默认 `3000`
+
+HTTP 服务器默认绑定 `127.0.0.1`。
+
+## 验证
+
+```bash
+npm run build
+npm run verify
+```
+
+验证脚本会检查：
+
+- MCP `tools/list` 是否只注册了发现工具
+- 是否可以通过 `catalog.listDomains` 枚举 Domain
+- 是否可以通过 `catalog.listTools` 发现 Domain 下的工具
+- 是否可以通过 `catalog.getToolSchema` 查询某个工具的 schema
+- 是否可以通过 `catalog.executeTool` 执行某个运行时工具
+- WAAPI 不可用时，运行时 WAAPI 调用是否仍会结构化失败
+
+注意：执行 verify 前需要先确保 schema 路径解析成功。
+
+## WAAPI 连接
+
+默认 WAAPI URL：
+
+```bash
+ws://127.0.0.1:8080/waapi
+```
+
+在 `config/runtime.json` 中配置：
+
+```json
+{
+  "waapiUrl": "ws://host:port/waapi"
+}
+```
+
+## 访问过滤
+
+可选的启动过滤变量：
+
+- `WWISE_MCP_ALLOWED_DOMAINS=object,soundengine`
+- `WWISE_MCP_ALLOWED_RISKS=low,medium`
+- `WWISE_MCP_ALLOWED_PERMISSIONS=waapi:authoring:read,waapi:runtime`
+
+## 打包为 EXE
+
+```bash
+npm run package:exe
+```
+
+输出文件：`bin/wwise-mcp.exe`
+
+## 手动验证
+
+服务启动后，按以下顺序调用工具：
+
+1. `catalog.listDomains`
+2. `catalog.listTools`，参数 `{ "domain": "object", "includePlanned": true }`
+3. `catalog.getToolSchema`，参数 `{ "toolName": "ak.wwise.core.object.get" }`
+4. `catalog.executeTool`，参数 `{ "toolName": "ak.wwise.core.object.get", "arguments": { ... } }`
+
+这是预期的渐进式发现路径：Domain 摘要 -> 工具摘要 -> schema 详情 -> 工具执行。
+
+这意味着 MCP 客户端在调用 `tools/list` 时，不会再直接拿到全部 callable WAAPI 工具，而是先发现 Domain 和工具，再按需请求某个工具的 schema，最后通过统一入口 `catalog.executeTool` 执行该工具。
+
+## 扩展新 Domain
+
+1. 复制 `src/domains/example/tools.ts` 到新的 Domain 目录。
+2. 导出 `getYourDomainTools()` 并返回 `ToolDefinition[]`。
+3. 在 `config/domains.json` 添加 Domain 元数据。
+4. 在 `src/index.ts` 中导入并注册该 Domain 工具。
+5. 如有需要，扩展 `src/lib/referenceCatalog.ts` 中的 Domain 映射。

package/config/domains.json

@@ -0,0 +1,130 @@
+{
+  "domains": [
+    {
+      "name": "catalog",
+      "title": "Catalog",
+      "description": "System discovery tools for progressive domain and schema disclosure.",
+      "risk": "low",
+      "tags": ["system", "discovery", "metadata"]
+    },
+    {
+      "name": "example",
+      "title": "Example",
+      "description": "Sample business domain showing how to add a non-WAAPI tool module.",
+      "risk": "low",
+      "tags": ["example", "sample"]
+    },
+    {
+      "name": "soundengine",
+      "title": "SoundEngine",
+      "description": "Runtime game-audio control for events, RTPCs, switches, listeners, and banks.",
+      "risk": "high",
+      "tags": ["runtime", "audio", "game"]
+    },
+    {
+      "name": "object",
+      "title": "Object",
+      "description": "Wwise authoring object queries, creation, property mutation, and hierarchy operations.",
+      "risk": "high",
+      "tags": ["authoring", "objects", "waql"]
+    },
+    {
+      "name": "audio",
+      "title": "Audio",
+      "description": "Audio import, solo or mute actions, and source peak analysis.",
+      "risk": "medium",
+      "tags": ["audio", "import", "analysis"]
+    },
+    {
+      "name": "soundbank",
+      "title": "SoundBank",
+      "description": "SoundBank generation, inclusion management, and external source conversion.",
+      "risk": "high",
+      "tags": ["build", "banks", "packaging"]
+    },
+    {
+      "name": "transport",
+      "title": "Transport",
+      "description": "Editor transport lifecycle and playback control.",
+      "risk": "medium",
+      "tags": ["transport", "playback"]
+    },
+    {
+      "name": "profiler",
+      "title": "Profiler",
+      "description": "Capture, performance telemetry, voice inspection, and profiler state.",
+      "risk": "medium",
+      "tags": ["profiling", "telemetry", "capture"]
+    },
+    {
+      "name": "project",
+      "title": "Project",
+      "description": "Project open, create, close, and save workflows across console, core, and UI APIs.",
+      "risk": "high",
+      "tags": ["project", "lifecycle"]
+    },
+    {
+      "name": "remote",
+      "title": "Remote",
+      "description": "Remote console discovery and connection management.",
+      "risk": "medium",
+      "tags": ["remote", "connection"]
+    },
+    {
+      "name": "ui",
+      "title": "UI",
+      "description": "Editor UI commands, selections, screenshots, and command registration.",
+      "risk": "medium",
+      "tags": ["ui", "editor"]
+    },
+    {
+      "name": "debug",
+      "title": "Debug",
+      "description": "Debug, CLI automation, logging, assertions, and Lua execution surfaces.",
+      "risk": "high",
+      "tags": ["debug", "cli", "automation"]
+    },
+    {
+      "name": "switchContainer",
+      "title": "Switch Container",
+      "description": "Switch Container child-to-state/switch assignment management.",
+      "risk": "medium",
+      "tags": ["authoring", "switch", "assignment"]
+    },
+    {
+      "name": "undo",
+      "title": "Undo",
+      "description": "Undo group management and redo operations for batched authoring changes.",
+      "risk": "high",
+      "tags": ["authoring", "undo", "redo"]
+    },
+    {
+      "name": "log",
+      "title": "Log",
+      "description": "Wwise log channel read, write, and clear operations.",
+      "risk": "low",
+      "tags": ["log", "diagnostics"]
+    },
+    {
+      "name": "plugin",
+      "title": "Plugin",
+      "description": "Wwise plug-in discovery and property schema inspection.",
+      "risk": "low",
+      "tags": ["plugin", "metadata", "discovery"]
+    },
+    {
+      "name": "sourceControl",
+      "title": "Source Control",
+      "description": "Source control file operations: add, check out, commit, revert, status, and provider configuration.",
+      "risk": "high",
+      "tags": ["vcs", "files", "sourceControl"]
+    },
+    {
+      "name": "sound",
+      "title": "Sound",
+      "description": "Sound object authoring operations such as active audio source selection.",
+      "risk": "high",
+      "tags": ["authoring", "sound", "source"]
+    }
+  ]
+}

package/config/runtime.json

@@ -0,0 +1,4 @@
+{
+  "wwiseRoot": "",
+  "waapiUrl": "ws://127.0.0.1:8080/waapi"
+}

package/dist/src/core/server.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServer = createServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const logger_js_1 = require("../lib/logger.js");
+const errors_js_1 = require("../lib/errors.js");
+const response_js_1 = require("../lib/response.js");
+/**
+ * 判断一个值是否为失败响应包结构。
+ * 用于工具处理器返回响应包（而非抛出异常）时的业务层失败检测。
+ */
+function isFailureResponse(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        "ok" in value &&
+        value.ok === false &&
+        "error" in value);
+}
+/**
+ * 创建 MCP 服务器实例，只注册标记为发现工具（isDiscoveryTool=true）的工具到MCP。
+ * 其他工具存活在注册表中，客户端通过catalog.executeTool动态执行。
+ *
+ * 这实现了渐进式披露设计：
+ * 1. 客户端只在 tools/list 中看到发现工具
+ * 2. 通过 catalog.listDomains → catalog.listTools → catalog.getToolSchema 逐步探索
+ * 3. 通过 catalog.executeTool 执行发现到的任何工具
+ *
+ * 每个工具被包装了统一的错误处理和日志记录逻辑。
+ * 错误和业务层失败均会序列化为标准 JSON 包并通过 MCP 文本内容返回。
+ */
+function createServer(registry, policy) {
+    const server = new mcp_js_1.McpServer({
+        name: "wwise-mcp",
+        version: "0.1.0"
+    }, {
+        capabilities: {
+            logging: {}
+        }
+    });
+    // 只注册发现工具到 MCP（实现渐进式披露）
+    for (const tool of registry.getCallableTools(policy)) {
+        if (!tool.isDiscoveryTool) {
+            continue;
+        }
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema
+        }, async (args, extra) => {
+            const startedAt = Date.now();
+            try {
+                if (!tool.handler) {
+                    throw new Error(`Tool ${tool.name} does not have a handler.`);
+                }
+                const response = await tool.handler(args, extra);
+                const failure = isFailureResponse(response) ? response : undefined;
+                (0, logger_js_1.logToolCall)({
+                    toolName: tool.name,
+                    durationMs: Date.now() - startedAt,
+                    success: !failure,
+                    errorCode: failure?.error.code,
+                    args: args
+                });
+                return (0, response_js_1.toMcpToolResult)(response);
+            }
+            catch (error) {
+                const failure = (0, errors_js_1.toFailureResponse)(error);
+                (0, logger_js_1.logToolCall)({
+                    toolName: tool.name,
+                    durationMs: Date.now() - startedAt,
+                    success: false,
+                    errorCode: failure.error.code,
+                    args: args
+                });
+                return (0, response_js_1.toMcpToolResult)(failure);
+            }
+        });
+    }
+    return server;
+}