Wwise Waapi MCP

Wwise MCP服务器

中文文档

用于Wwise WAAPI的轻量级Node.js+TypeScript MCP服务器。

⭐ 使用渐进式工具发现。通过一次公开完整的WAAPI工具界面来避免消耗大量令牌。

⭐ 使用本地安装的Wwise的WAAPI JsonSchema实现完整的WAAPI功能。

快速开始

安装依赖项

npm i

配置Wwise安装ROOT和WAAPI连接

配置存储在 config/runtime.json

如果你离开 wwiseRoot 配置为空，或路径无效，工具将使用 %WWISEROOT% 试着找到路。

这 waapiUrl 默认为 ws://127.0.0.1:8080/waapi 如果没有指定。

// Example
{
  "wwiseRoot": "C:/Program Files (x86)/Audiokinetic/Wwise 2024.1.0.8669",
  "waapiUrl": "ws://127.0.0.1:8080/waapi"
}

在开发中运行（stdio默认）

npm run dev

或者构建并运行

npm run build
npm start

模式源和启动要求

此项目不会重新分发Audiokinetic WAAPI架构JSON文件。

启动时，服务器使用以下优先级解析WAAPI架构目录：

1. config/runtime.json -> wwiseRoot
2. WWISEROOT 环境变量
3. 实时WAAPI探测：

- 呼叫 ak.wwise.core.getProjectInfo 确认项目已打开 - 呼叫 ak.wwise.core.getInfo 并阅读 directories.install

根目录下的预期架构路径：

/Authoring/Data/Schemas/WAAPI

如果所有探测器都失败，启动将退出 waapi_schema_not_found.

核心能力

• 分层架构： core + registry + domains + lib.
• 渐进式披露MCP表面：

- tools/list 仅公开发现工具，而不是每个运行时WAAPI工具 - 当前公开的发现工具： - session.configure - session.getConfig - catalog.listDomains - catalog.listTools - catalog.getToolSchema - catalog.executeTool

• 发现和执行流程：

- catalog.listDomains - catalog.listTools - catalog.getToolSchema - catalog.executeTool

• 跨主要域的运行时支持的WAAPI工具。
• 标准响应信封：

- 成功： { ok: true, data: ... } - 故障： { ok: false, error: { code, message, details? } }

• 带有敏感字段编辑的结构化工具调用日志。

运输方式

stdio模式（默认）

用于将服务器作为子进程生成的标准MCP客户端。

npm run dev

npm start
# equivalent to: node dist/src/index.js

MCP客户端配置示例：

{
  "servers": {
    "wwise-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/src/index.js"]
    }
  }
}

HTTP/SSE模式

当您希望通过HTTP实现长时间运行的MCP端点时使用。

node dist/src/index.js --http

node dist/src/index.js --http --port 8080

MCP_TRANSPORT=http PORT=8080 node dist/src/index.js

HTTP端点摘要：

|方法|路径|目的| | :-- | :-- | :-- | | POST | /mcp |发送JSON-RPC请求。省略 mcp-session-id 首先 initialize 创建会话。 | | GET | /mcp |打开独立的SSE流以接收服务器通知。需要 mcp-session-id. | | DELETE | /mcp |结束会话。需要 mcp-session-id. |

端口选择优先级：

1. --port
2. PORT env 是
3. 默认 3000

HTTP服务器绑定到 127.0.0.1 默认情况下。

验证

npm run build
npm run verify

验证检查：

• 只有发现工具通过MCP注册 tools/list
• 域可以通过以下方式枚举 catalog.listDomains
• 可以通过以下方式发现域本地工具 catalog.listTools
• 可以通过以下方式查询一个工具模式 catalog.getToolSchema
• 一个运行时WAAPI调用可以通过以下方式执行 catalog.executeTool
• 当WAAPI不可用时，WAAPI失败仍将作为结构化错误返回

注意：验证需要先解析模式路径才能成功。

WAAPI连接

默认WAAPI URL：

ws://127.0.0.1:8080/waapi

在中配置 config/runtime.json:

{
  "waapiUrl": "ws://host:port/waapi"
}

连接到特定的Wwise实例

每个Wwise实例在可配置端口（默认8080）上公开WAAPI。 如果多个Wwise实例在同一台机器上运行，则每个实例都必须使用不同的端口——如果所选端口已在使用中，Wwise将拒绝启动其WAAPI服务器。

使用 session.configure 运行时切换目标端口而不重新启动服务器的工具：

// Switch to a Wwise instance running on port 8081
{ "port": 8081 }

变更持续到 runtime.json 当前WAAPI会话已断开连接。 下一个WAAPI调用会自动重新连接到新端口。

使用 session.getConfig 检查当前配置的URL。

访问过滤

可选启动筛选器：

• WWISE_MCP_ALLOWED_DOMAINS=object,soundengine
• WWISE_MCP_ALLOWED_RISKS=low,medium
• WWISE_MCP_ALLOWED_PERMISSIONS=waapi:authoring:read,waapi:runtime

打包为EXE

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": { ... } }

这是预期的渐进式披露路径：域摘要->工具摘要->模式详细信息->执行。

实际含义是，MCP客户端在以下期间不再接收完整的可调用WAAPI表面 tools/list。他们首先发现可用的域和工具，然后请求一个工具的模式详细信息，然后通过统一的 catalog.executeTool 入口点。

使用新域进行扩展

1. 复制 src/domains/example/tools.ts 转到新的域文件夹。
2. 出口 getYourDomainTools() 返回 ToolDefinition[].
3. 将域元数据添加到 config/domains.json.
4. 在中导入/注册工具 src/index.ts.
5. 扩展 src/lib/referenceCatalog.ts 必要时绘制地图。