AI导哈

WAAPI MCP服务器

一个基于Node.js和TypeScript的轻量级Wwise WAAPI MCP服务器，提供渐进式工具发现和全功能WAAPI支持。

  • by Li-Major
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Li-Major/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

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

<WwiseRoot>/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 <n>
  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 必要时绘制地图。

相关 MCP