wwise-waapi-mcp 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## [1.0.1] - 2026-03-28
+
+### Added
+
+- **Session domain** (`src/domains/session/tools.ts`): two new discovery tools for managing the WAAPI connection at runtime.
+
+  | Tool | Description |
+  | :-- | :-- |
+  | `session.configure` | Update the WAAPI port used to reach Wwise Authoring. Persists the new URL to `config/runtime.json` and disconnects the active session so the next WAAPI call reconnects automatically. |
+  | `session.getConfig` | Return the currently configured WAAPI URL and whether a session is active. |
+
+- **`setWaapiUrl(url)`** and **`isSessionActive()`** exports in `src/lib/waapiClient.ts`.
+
+### Changed
+
+- `session.configure` and `session.getConfig` are registered as `isDiscoveryTool: true`, meaning they appear directly in the MCP `tools/list` response alongside the `catalog.*` tools — no `catalog.executeTool` wrapper needed.
+- `config/domains.json`: added `session` domain metadata entry.
+- `tests/verify.ts`: updated expected discovery tool count from 4 to 6; added assertions for the two new session tools.
+- `README.md` / `README_ZH.md`: updated exposed tools list; expanded "WAAPI connection" section to explain multi-instance port usage.
+
+### Background
+
+Each Wwise Authoring instance exposes WAAPI on a separately configurable port (default 8080). When multiple Wwise instances run on the same machine, each must use a different port — if the chosen port is already taken, the later instance fails to start its WAAPI server. `session.configure` provides the runtime entry point for switching between those instances without restarting the MCP server.
+
+---
+
+## [1.0.0] - 2026-03-27
+
+Initial release.
+
+- Progressive-disclosure MCP surface: only `catalog.*` discovery tools in `tools/list`.
+- Runtime-backed WAAPI tools across 18 domains.
+- stdio and HTTP/SSE transport modes.
+- Standard response envelope `{ ok, data | error }`.
+- Structured logging with sensitive-field redaction.
+- EXE packaging support via `npm run package:exe`.

package/README.md

@@ -71,6 +71,8 @@ If all probes fail, startup exits with `waapi_schema_not_found`.
 - Progressive-disclosure MCP surface:
   - `tools/list` only exposes discovery tools, not every runtime WAAPI tool
   - currently exposed discovery tools:
+    - `session.configure`
+    - `session.getConfig`
     - `catalog.listDomains`
     - `catalog.listTools`
     - `catalog.getToolSchema`
@@ -86,8 +88,6 @@ If all probes fail, startup exits with `waapi_schema_not_found`.
   - 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)
@@ -183,6 +183,23 @@ Configure in `config/runtime.json`:
 }
 ```
 
+### Connecting to a specific Wwise instance
+
+Each Wwise instance exposes WAAPI on a configurable port (default 8080).
+If multiple Wwise instances are running on the same machine, each must use a different port — Wwise will refuse to start its WAAPI server if the chosen port is already in use.
+
+Use the `session.configure` tool at runtime to switch the target port without restarting the server:
+
+```jsonc
+// Switch to a Wwise instance running on port 8081
+{ "port": 8081 }
+```
+
+The change is persisted to `runtime.json` and the current WAAPI session is disconnected.
+The next WAAPI call automatically reconnects to the new port.
+
+Use `session.getConfig` to check the currently configured URL and connection status.
+
 ## Access filtering
 
 Optional startup filters:

package/README_ZH.md

@@ -71,6 +71,8 @@ npm start
 - 渐进式对外暴露：
   - MCP 的 `tools/list` 只暴露发现工具，不会一次性暴露所有运行时 WAAPI 工具
   - 当前对外暴露的发现工具为：
+    - `session.configure`
+    - `session.getConfig`
     - `catalog.listDomains`
     - `catalog.listTools`
     - `catalog.getToolSchema`
@@ -86,8 +88,6 @@ npm start
   - 失败：`{ ok: false, error: { code, message, details? } }`
 - 结构化工具调用日志，并对敏感字段做脱敏处理。
 
-已实现的 WAAPI 接口覆盖详情见 `docs/implemented-waapi.md`。
-
 ## 传输模式
 
 ### stdio 模式（默认）
@@ -183,6 +183,23 @@ ws://127.0.0.1:8080/waapi
 }
 ```
 
+### 连接到指定的 Wwise 实例
+
+每个 Wwise 实例都有独立可配置的 WAAPI 端口（默认 8080）。  
+同一台机器上如果同时运行多个 Wwise 实例，每个实例必须使用不同的端口——若端口已被占用，后启动的实例将无法初始化其 WAAPI 服务器。
+
+在运行时可通过 `session.configure` 工具切换目标端口，无需重启 MCP 服务器：
+
+```jsonc
+// 切换到运行在 8081 端口的 Wwise 实例
+{ "port": 8081 }
+```
+
+该变更会持久化到 `runtime.json`，同时断开当前 WAAPI 会话。  
+下一次 WAAPI 工具调用时将自动以新端口重新建立连接。
+
+使用 `session.getConfig` 可查看当前配置的连接地址及会话状态。
+
 ## 访问过滤
 
 可选的启动过滤变量：

package/config/domains.json

@@ -125,6 +125,13 @@
       "description": "Sound object authoring operations such as active audio source selection.",
       "risk": "high",
       "tags": ["authoring", "sound", "source"]
+    },
+    {
+      "name": "session",
+      "title": "Session",
+      "description": "WAAPI connection configuration. Controls which Wwise instance the server connects to by setting the WAAPI port.",
+      "risk": "low",
+      "tags": ["session", "connection", "config"]
     }
   ]
 }

package/dist/src/domains/session/tools.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSessionTools = getSessionTools;
+const v4_1 = require("zod/v4");
+const fs_1 = require("fs");
+const response_js_1 = require("../../lib/response.js");
+const waapiClient_js_1 = require("../../lib/waapiClient.js");
+const runtimePaths_js_1 = require("../../lib/runtimePaths.js");
+const errors_js_1 = require("../../lib/errors.js");
+/** 从 runtime.json 读取当前配置的 WAAPI URL。 */
+function getCurrentWaapiUrl() {
+    try {
+        const configPath = (0, runtimePaths_js_1.getConfigPath)("runtime.json");
+        const config = JSON.parse((0, fs_1.readFileSync)(configPath, "utf-8"));
+        return config.waapiUrl?.trim() || "ws://127.0.0.1:8080/waapi";
+    }
+    catch {
+        return "ws://127.0.0.1:8080/waapi";
+    }
+}
+/**
+ * Session 域工具：管理 MCP 服务器与 Wwise Authoring 实例之间的连接配置。
+ * 每个 Wwise 实例可以设置独立的 WAAPI 端口号（默认 8080）。
+ * 同一台机器上同时运行多个 Wwise 实例时，每个实例须使用不同端口。
+ */
+function getSessionTools() {
+    return [
+        {
+            name: "session.configure",
+            title: "Configure WAAPI Connection",
+            description: "Update the WAAPI port used to connect to Wwise Authoring. " +
+                "Each Wwise instance exposes WAAPI on a configurable port (default 8080). " +
+                "When multiple Wwise instances run on the same machine, each must use a different port. " +
+                "Calling this tool persists the new port to runtime.json and disconnects the current session. " +
+                "The next WAAPI call will automatically reconnect to the new port. " +
+                "After calling this tool, ask the user whether to verify the new connection immediately.",
+            domain: "session",
+            risk: "low",
+            permissions: [],
+            tags: ["session", "connection", "config"],
+            examples: [
+                {
+                    title: "Switch to Wwise instance on port 8081",
+                    input: { port: 8081 }
+                },
+                {
+                    title: "Reset back to the default port 8080",
+                    input: { port: 8080 }
+                }
+            ],
+            implementationStatus: "implemented",
+            callable: true,
+            isDiscoveryTool: true,
+            inputSchema: {
+                port: v4_1.z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(65535)
+                    .describe("WAAPI port number of the target Wwise instance (default: 8080).")
+            },
+            inputSchemaJson: {
+                type: "object",
+                properties: {
+                    port: {
+                        type: "integer",
+                        minimum: 1,
+                        maximum: 65535,
+                        description: "WAAPI port number of the target Wwise instance (default: 8080)."
+                    }
+                },
+                required: ["port"],
+                additionalProperties: false
+            },
+            outputSchemaJson: response_js_1.standardResponseJsonSchema,
+            handler: async (rawArgs) => {
+                try {
+                    const args = rawArgs;
+                    const previousUrl = getCurrentWaapiUrl();
+                    const newUrl = `ws://127.0.0.1:${args.port}/waapi`;
+                    (0, waapiClient_js_1.setWaapiUrl)(newUrl);
+                    await (0, waapiClient_js_1.disconnectWaapi)();
+                    return (0, response_js_1.ok)({
+                        previousUrl,
+                        newUrl,
+                        message: "WAAPI port updated and current session disconnected. " +
+                            "The next WAAPI call will connect to the new port automatically."
+                    });
+                }
+                catch (error) {
+                    return (0, errors_js_1.toFailureResponse)(error);
+                }
+            }
+        },
+        {
+            name: "session.getConfig",
+            title: "Get Connection Config",
+            description: "Return the current WAAPI connection URL and whether a session is currently active. " +
+                "Use this to check which Wwise instance the server is configured to connect to.",
+            domain: "session",
+            risk: "low",
+            permissions: [],
+            tags: ["session", "connection", "config"],
+            examples: [
+                {
+                    title: "Check current WAAPI connection config"
+                }
+            ],
+            implementationStatus: "implemented",
+            callable: true,
+            isDiscoveryTool: true,
+            outputSchemaJson: response_js_1.standardResponseJsonSchema,
+            handler: async () => {
+                return (0, response_js_1.ok)({
+                    url: getCurrentWaapiUrl(),
+                    isConnected: (0, waapiClient_js_1.isSessionActive)()
+                });
+            }
+        }
+    ];
+}

package/dist/src/index.js

@@ -29,6 +29,7 @@ const tools_js_15 = require("./domains/log/tools.js");
 const tools_js_16 = require("./domains/plugin/tools.js");
 const tools_js_17 = require("./domains/sourceControl/tools.js");
 const tools_js_18 = require("./domains/sound/tools.js");
+const tools_js_19 = require("./domains/session/tools.js");
 /** 从 config/domains.json 加载领域元数据列表。 */
 function loadDomainsConfig() {
     const document = JSON.parse(node_fs_1.default.readFileSync((0, runtimePaths_js_1.getConfigPath)("domains.json"), "utf8"));
@@ -69,6 +70,7 @@ async function main() {
     registry.registerTools((0, tools_js_16.getPluginTools)());
     registry.registerTools((0, tools_js_17.getSourceControlTools)());
     registry.registerTools((0, tools_js_18.getSoundTools)());
+    registry.registerTools((0, tools_js_19.getSessionTools)());
     registry.registerTools((0, tools_js_1.getCatalogTools)(registry));
     const policy = toolRegistry_js_1.ToolRegistry.policyFromEnv(process.env);
     // --- 传输层模式检测 ---

package/dist/src/lib/waapiClient.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.setWaapiUrl = setWaapiUrl;
+exports.isSessionActive = isSessionActive;
 exports.getWaapiSession = getWaapiSession;
 exports.callWaapi = callWaapi;
 exports.disconnectWaapi = disconnectWaapi;
@@ -19,6 +21,27 @@ function getWaapiUrl() {
         return "ws://127.0.0.1:8080/waapi";
     }
 }
+/**
+ * 将新的 WAAPI URL 写入 runtime.json，并不会立即重连。
+ * 调用方应在此之后调用 disconnectWaapi()，下次工具调用时将自动以新 URL 重连。
+ */
+function setWaapiUrl(url) {
+    try {
+        const configPath = (0, runtimePaths_js_1.getConfigPath)("runtime.json");
+        const config = JSON.parse((0, fs_1.readFileSync)(configPath, "utf-8"));
+        config.waapiUrl = url;
+        (0, fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    }
+    catch (error) {
+        throw new errors_js_1.AppError("config_write_failed", "Failed to update waapiUrl in runtime.json.", {
+            cause: error instanceof Error ? error.message : error
+        });
+    }
+}
+/** 返回当前 WAAPI 会话是否处于活跃状态。 */
+function isSessionActive() {
+    return !!activeSession;
+}
 /** 应用内共享的单例 WAAPI 会话对象。 */
 let activeSession;
 /** 连接过程中的 Promise，用于防止并发请求触发多次连接。 */

package/package.json

@@ -1,56 +1,57 @@
-{
-  "name": "wwise-waapi-mcp",
-  "version": "1.0.0",
-  "description": "Progressive-disclosure MCP server scaffold for Wwise WAAPI",
-  "main": "dist/src/index.js",
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsx src/index.ts",
-    "start": "node dist/src/index.js",
-    "verify": "tsx tests/verify.ts",
-    "package:exe": "npm run build && pkg package.json --targets node18-win-x64 --output bin/wwise-mcp.exe"
-  },
-  "keywords": [
-    "mcp",
-    "wwise",
-    "waapi",
-    "audio",
-    "game",
-    "typescript"
-  ],
-  "author": "majorli",
-  "license": "MIT",
-  "type": "commonjs",
-  "bin": {
-    "wwise-waapi-mcp": "dist/src/index.js"
-  },
-  "files": [
-    "dist/**/*",
-    "config/**/*",
-    "README.md",
-    "README_ZH.md"
-  ],
-  "pkg": {
-    "assets": [
-      "config/**/*.json"
-    ],
-    "scripts": [
-      "dist/**/*.js"
-    ]
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.28.0",
-    "waapi-client": "^2017.2.1",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@types/node": "^25.5.0",
-    "pkg": "^5.8.1",
-    "tsx": "^4.21.0",
-    "typescript": "^6.0.2"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Li-Major/wwise-waapi-mcp.git"
-  }
-}
+{
+  "name": "wwise-waapi-mcp",
+  "version": "1.0.1",
+  "description": "Progressive-disclosure MCP server scaffold for Wwise WAAPI",
+  "main": "dist/src/index.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/src/index.js",
+    "verify": "tsx tests/verify.ts",
+    "package:exe": "npm run build && pkg package.json --targets node18-win-x64 --output bin/wwise-mcp.exe"
+  },
+  "keywords": [
+    "mcp",
+    "wwise",
+    "waapi",
+    "audio",
+    "game",
+    "typescript"
+  ],
+  "author": "majorli",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "wwise-waapi-mcp": "dist/src/index.js"
+  },
+  "files": [
+    "dist/**/*",
+    "config/**/*",
+    "README.md",
+    "README_ZH.md",
+    "CHANGELOG.md"
+  ],
+  "pkg": {
+    "assets": [
+      "config/**/*.json"
+    ],
+    "scripts": [
+      "dist/**/*.js"
+    ]
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "waapi-client": "^2017.2.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "pkg": "^5.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Li-Major/wwise-waapi-mcp.git"
+  }
+}