wwise-waapi-mcp 1.0.0

package/dist/src/lib/waapiSchemaResolver.js

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWaapiSchemaDirectory = resolveWaapiSchemaDirectory;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_js_1 = require("./errors.js");
+const waapiClient_js_1 = require("./waapiClient.js");
+const runtimePaths_js_1 = require("./runtimePaths.js");
+const WAAPI_SCHEMA_SUBDIR = ["Authoring", "Data", "Schemas", "WAAPI"];
+function readRuntimeConfig() {
+    const filePath = (0, runtimePaths_js_1.getConfigPath)("runtime.json");
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return {};
+    }
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function toNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function toAbsolutePath(root) {
+    return node_path_1.default.isAbsolute(root) ? root : node_path_1.default.resolve(process.cwd(), root);
+}
+function getSchemaDir(wwiseRoot) {
+    return node_path_1.default.join(wwiseRoot, ...WAAPI_SCHEMA_SUBDIR);
+}
+function isValidSchemaDirectory(schemaDir) {
+    if (!node_fs_1.default.existsSync(schemaDir)) {
+        return false;
+    }
+    const stat = node_fs_1.default.statSync(schemaDir);
+    if (!stat.isDirectory()) {
+        return false;
+    }
+    const files = node_fs_1.default.readdirSync(schemaDir);
+    return files.some(file => file.endsWith(".json") && file !== "waapi_definitions.json");
+}
+function resolveFromRoot(source, rootValue) {
+    const root = toNonEmptyString(rootValue);
+    if (!root) {
+        return undefined;
+    }
+    const wwiseRoot = toAbsolutePath(root);
+    const schemaDir = getSchemaDir(wwiseRoot);
+    if (!isValidSchemaDirectory(schemaDir)) {
+        return undefined;
+    }
+    return {
+        source,
+        wwiseRoot,
+        schemaDir
+    };
+}
+function getInstallDirFromGetInfoResult(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const directories = value.directories;
+    if (!directories || typeof directories !== "object") {
+        return undefined;
+    }
+    return toNonEmptyString(directories.install);
+}
+async function resolveFromWaapi() {
+    // 先检查是否有工程打开；若没有，此调用通常会失败或返回无效项目信息。
+    const projectInfo = await (0, waapiClient_js_1.callWaapi)("ak.wwise.core.getProjectInfo", {}, {});
+    if (!projectInfo || typeof projectInfo !== "object") {
+        return undefined;
+    }
+    const projectPath = toNonEmptyString(projectInfo.path);
+    if (!projectPath) {
+        return undefined;
+    }
+    const wwiseInfo = await (0, waapiClient_js_1.callWaapi)("ak.wwise.core.getInfo", {}, {});
+    const installRoot = getInstallDirFromGetInfoResult(wwiseInfo);
+    if (!installRoot) {
+        return undefined;
+    }
+    return resolveFromRoot("waapi", installRoot);
+}
+/**
+ * 解析可用的 WAAPI schema 目录，优先级如下：
+ * 1) config/runtime.json: wwiseRoot
+ * 2) 环境变量 WWISEROOT
+ * 3) 通过 WAAPI 获取当前打开工程的 Wwise install 目录
+ */
+async function resolveWaapiSchemaDirectory() {
+    const checked = [];
+    const config = readRuntimeConfig();
+    const fromConfig = resolveFromRoot("config", config.wwiseRoot);
+    checked.push({ source: "config.runtime.wwiseRoot", value: toNonEmptyString(config.wwiseRoot) });
+    if (fromConfig) {
+        return fromConfig;
+    }
+    const fromEnv = resolveFromRoot("env", process.env.WWISEROOT);
+    checked.push({ source: "env.WWISEROOT", value: toNonEmptyString(process.env.WWISEROOT) });
+    if (fromEnv) {
+        return fromEnv;
+    }
+    try {
+        const fromWaapi = await resolveFromWaapi();
+        if (fromWaapi) {
+            return fromWaapi;
+        }
+    }
+    catch {
+        // WAAPI 不可用或工程未打开时按失败路径继续。
+    }
+    throw new errors_js_1.AppError("waapi_schema_not_found", "Unable to locate WAAPI schema directory. Configure config/runtime.json (wwiseRoot), set WWISEROOT, or open a Wwise project and retry.", {
+        expectedSchemaSubdir: WAAPI_SCHEMA_SUBDIR.join(node_path_1.default.sep),
+        checked
+    });
+}

package/dist/src/registry/toolRegistry.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRegistry = void 0;
+/**
+ * 工具注册表：集中管理领域元数据、可调用工具和参考目录条目。
+ * 为 MCP 服务器提供进展式揭露（列展领域→列展工具→获取 schema）所需的所有查询接口。
+ * 工具访问可通过 ToolAccessPolicy 按领域、风险等级或权限进行过滤。
+ */
+class ToolRegistry {
+    constructor(domainList, referenceCatalog) {
+        this.domains = new Map();
+        this.callableTools = new Map();
+        this.referenceCatalog = new Map();
+        for (const domain of domainList) {
+            this.domains.set(domain.name, domain);
+        }
+        for (const [name, entry] of referenceCatalog.entries()) {
+            this.referenceCatalog.set(name, entry);
+        }
+    }
+    /** 注册一组工具定义。已存在同名工具将被视为更新。 */
+    registerTools(tools) {
+        for (const tool of tools) {
+            this.callableTools.set(tool.name, tool);
+        }
+    }
+    /** 按名称获取领域元数据。 */
+    getDomain(name) {
+        return this.domains.get(name);
+    }
+    /** 返回符合策略过滤的所有可调用工具列表。 */
+    getCallableTools(policy) {
+        return [...this.callableTools.values()].filter(tool => this.matchesPolicy(tool, policy));
+    }
+    /** 按名称获取单个可调用工具定义。 */
+    getCallableTool(name) {
+        return this.callableTools.get(name);
+    }
+    /** 按名称获取单个参考目录条目。 */
+    getReferenceEntry(name) {
+        return this.referenceCatalog.get(name);
+    }
+    /**
+     * 返回所有领域的摘要列表，附加工具数量统计。
+     * 用于 catalog.listDomains 进展式揭露的第一步。
+     */
+    listDomains(policy) {
+        return [...this.domains.values()]
+            .map(domain => {
+            const callableTools = this.getCallableTools(policy).filter(tool => tool.domain === domain.name);
+            const discoveredReferenceCount = [...this.referenceCatalog.values()].filter(entry => entry.domain === domain.name).length;
+            return {
+                ...domain,
+                callableToolCount: callableTools.length,
+                implementedToolCount: callableTools.filter(tool => tool.implementationStatus === "implemented").length,
+                discoveredReferenceCount
+            };
+        })
+            .sort((left, right) => left.name.localeCompare(right.name));
+    }
+    /**
+     * 返回指定领域下的工具摘要列表。
+     * includePlanned=true 时还会包含仅在参考目录中发现而未实现的工具（标记为 planned）。
+     * 用于 catalog.listTools 进展式揭露的第二步。
+     */
+    listTools(domainName, policy, includePlanned = true) {
+        const byName = new Map();
+        for (const tool of this.getCallableTools(policy)) {
+            if (tool.domain !== domainName) {
+                continue;
+            }
+            byName.set(tool.name, this.toDiscovery(tool));
+        }
+        if (includePlanned) {
+            for (const reference of this.referenceCatalog.values()) {
+                if (reference.domain !== domainName || byName.has(reference.name)) {
+                    continue;
+                }
+                byName.set(reference.name, {
+                    name: reference.name,
+                    title: reference.summary,
+                    description: `Reference-discovered WAAPI interface for ${reference.name}.`,
+                    domain: reference.domain,
+                    risk: this.domains.get(reference.domain)?.risk ?? "medium",
+                    permissions: [],
+                    tags: ["reference", "planned"],
+                    examples: [],
+                    implementationStatus: "planned",
+                    callable: false,
+                    referenceFile: reference.referenceFile
+                });
+            }
+        }
+        return [...byName.values()].sort((left, right) => left.name.localeCompare(right.name));
+    }
+    /**
+     * 获取单个工具的摘要信息。
+     * 首先查找可调用工具，如果不存在则回退到参考目录条目。
+     * 用于 catalog.getToolSchema 进展式揭露的第三步。
+     */
+    getToolDiscovery(name) {
+        const callable = this.callableTools.get(name);
+        if (callable) {
+            return this.toDiscovery(callable);
+        }
+        const reference = this.referenceCatalog.get(name);
+        if (!reference) {
+            return undefined;
+        }
+        return {
+            name: reference.name,
+            title: reference.summary,
+            description: `Reference-discovered WAAPI interface for ${reference.name}.`,
+            domain: reference.domain,
+            risk: this.domains.get(reference.domain)?.risk ?? "medium",
+            permissions: [],
+            tags: ["reference", "planned"],
+            examples: [],
+            implementationStatus: "planned",
+            callable: false,
+            referenceFile: reference.referenceFile
+        };
+    }
+    /**
+     * 从环境变量读取访问控制策略。
+     * - WWISE_MCP_ALLOWED_DOMAINS: 逗号分隔的允许领域列表
+     * - WWISE_MCP_ALLOWED_RISKS: 逗号分隔的允许风险等级列表
+     * - WWISE_MCP_ALLOWED_PERMISSIONS: 逗号分隔的允许权限列表
+     */
+    static policyFromEnv(env) {
+        return {
+            allowedDomains: parseCsvSet(env.WWISE_MCP_ALLOWED_DOMAINS),
+            allowedRisks: parseCsvSet(env.WWISE_MCP_ALLOWED_RISKS),
+            allowedPermissions: parseCsvSet(env.WWISE_MCP_ALLOWED_PERMISSIONS)
+        };
+    }
+    /** 检查工具是否符合特定策略，undefined 策略表示允许一切。 */
+    matchesPolicy(tool, policy) {
+        if (!policy) {
+            return true;
+        }
+        if (policy.allowedDomains && !policy.allowedDomains.has(tool.domain)) {
+            return false;
+        }
+        if (policy.allowedRisks && !policy.allowedRisks.has(tool.risk)) {
+            return false;
+        }
+        if (policy.allowedPermissions && tool.permissions.length > 0) {
+            return tool.permissions.every(permission => policy.allowedPermissions?.has(permission));
+        }
+        return true;
+    }
+    /** 将 ToolDefinition 转换为进展式揭露用的公开字段子集。 */
+    toDiscovery(tool) {
+        return {
+            name: tool.name,
+            title: tool.title,
+            description: tool.description,
+            domain: tool.domain,
+            risk: tool.risk,
+            permissions: tool.permissions,
+            tags: tool.tags,
+            examples: tool.examples,
+            implementationStatus: tool.implementationStatus,
+            callable: tool.callable,
+            referenceFile: tool.referenceFile
+        };
+    }
+}
+exports.ToolRegistry = ToolRegistry;
+/** 将逗号分隔的环境变量字符串解析为字符串集合。如果值为空则返回 undefined。 */
+function parseCsvSet(value) {
+    if (!value) {
+        return undefined;
+    }
+    return new Set(value
+        .split(",")
+        .map(entry => entry.trim())
+        .filter(Boolean));
+}

package/dist/src/registry/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/tests/verify.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_path_1 = __importDefault(require("node:path"));
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/client/stdio.js");
+/**
+ * 将 callTool 的返回值解析为标准 JSON 响应包。
+ * 兼容两种 SDK 版本的返回格式：content 直接返回和 toolResult 嵌套返回。
+ */
+function parseStructuredContent(result) {
+    const normalized = (result.content ? result : result.toolResult);
+    if (!normalized?.content) {
+        throw new Error("Tool result does not contain content.");
+    }
+    const textContent = normalized.content.find(item => item.type === "text" && typeof item.text === "string");
+    if (!textContent?.text) {
+        throw new Error("Tool did not return JSON text content.");
+    }
+    return JSON.parse(textContent.text);
+}
+/**
+ * 端到端验证脚本：启动 stdio MCP 服务器，演示渐进式披露工作流程：
+ * 1. 连接并检查只有4个发现工具暴露到MCP
+ * 2. 调用 catalog.listDomains 获取所有域的摘要
+ * 3. 调用 catalog.listTools 找到特定域的工具
+ * 4. 调用 catalog.getToolSchema 获取工具的详细schema
+ * 5. 调用 catalog.executeTool 动态执行任何已注册的工具
+ */
+async function main() {
+    const client = new index_js_1.Client({
+        name: "wwise-mcp-verify",
+        version: "0.1.0"
+    });
+    const transport = new stdio_js_1.StdioClientTransport({
+        command: process.execPath,
+        args: [node_path_1.default.join(process.cwd(), "dist", "src", "index.js")],
+        cwd: process.cwd(),
+        stderr: "pipe"
+    });
+    const stderr = transport.stderr;
+    if (stderr) {
+        stderr.on("data", chunk => {
+            process.stderr.write(chunk);
+        });
+    }
+    await client.connect(transport);
+    // Step 1: Verify only discovery tools are exposed to MCP
+    const toolsResult = await client.listTools();
+    const toolNames = toolsResult.tools.map(tool => tool.name);
+    console.log("\n=== Progressive Disclosure Verification ===");
+    console.log(`Step 1: MCP tools/list includes ${toolNames.length} discovery tools:`, toolNames);
+    strict_1.default.equal(toolNames.length, 4, "Should have exactly 4 discovery tools");
+    (0, strict_1.default)(toolNames.includes("catalog.listDomains"));
+    (0, strict_1.default)(toolNames.includes("catalog.listTools"));
+    (0, strict_1.default)(toolNames.includes("catalog.getToolSchema"));
+    (0, strict_1.default)(toolNames.includes("catalog.executeTool"));
+    // Step 2: List all domains
+    console.log("\nStep 2: Call catalog.listDomains");
+    const domainsResult = await client.callTool({
+        name: "catalog.listDomains",
+        arguments: {}
+    });
+    const parsedDomains = parseStructuredContent(domainsResult);
+    strict_1.default.equal(parsedDomains.ok, true);
+    const domains = parsedDomains.data?.domains ?? [];
+    console.log(`  Found ${domains.length} domains`);
+    // Step 3: List tools in soundengine domain
+    console.log("\nStep 3: Call catalog.listTools for 'soundengine' domain");
+    const toolsListResult = await client.callTool({
+        name: "catalog.listTools",
+        arguments: {
+            domain: "soundengine",
+            includePlanned: false
+        }
+    });
+    const parsedToolsList = parseStructuredContent(toolsListResult);
+    strict_1.default.equal(parsedToolsList.ok, true);
+    const seTools = parsedToolsList.data?.tools ?? [];
+    const hasPostEvent = seTools.some((t) => t.name === "ak.soundengine.postEvent");
+    console.log(`  Found ${seTools.length} soundengine tools (including postEvent: ${hasPostEvent})`);
+    (0, strict_1.default)(hasPostEvent, "ak.soundengine.postEvent should be discoverable");
+    // Step 4: Get detailed schema
+    console.log("\nStep 4: Call catalog.getToolSchema for 'ak.soundengine.postEvent'");
+    const schemaResult = await client.callTool({
+        name: "catalog.getToolSchema",
+        arguments: {
+            toolName: "ak.soundengine.postEvent"
+        }
+    });
+    const parsedSchema = parseStructuredContent(schemaResult);
+    strict_1.default.equal(parsedSchema.ok, true);
+    console.log("  Schema retrieved successfully");
+    // Step 5: Execute tool via catalog.executeTool
+    console.log("\nStep 5: Call catalog.executeTool to execute 'ak.soundengine.postEvent'");
+    const executeResult = await client.callTool({
+        name: "catalog.executeTool",
+        arguments: {
+            toolName: "ak.soundengine.postEvent",
+            arguments: {
+                event: "Play_Footstep",
+                gameObject: "Player"
+            }
+        }
+    });
+    const parsedExecute = parseStructuredContent(executeResult);
+    strict_1.default.equal(parsedExecute.ok, false);
+    (0, strict_1.default)(["waapi_unavailable", "waapi_call_failed"].includes(parsedExecute.error?.code ?? ""));
+    console.log(`  Tool executed (expected failure due to no Wwise running): ${parsedExecute.error?.code}`);
+    await transport.close();
+    console.log("\n✓ Verification passed - Progressive disclosure working correctly.\n");
+}
+void main().catch(error => {
+    console.error("Verification failed.", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,56 @@
+{
+  "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"
+  }
+}