@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/mcp-schema-audit.js

@@ -0,0 +1,772 @@
+import * as fs from 'fs';
+import * as path from 'path';
+export const DEPLOYED_TOOLS_DIR = 'c:\\Users\\zhou\\.trae-cn\\mcps\\s_wowok-7838e181\\solo_agent\\mcp_wagent\\tools';
+export const GENERATED_SCHEMAS_DIR = 'd:\\wowok\\agent\\mcp\\dist\\schemas';
+export const MCP_SRC_SCHEMA_DIR = 'd:\\wowok\\agent\\mcp\\src\\schema';
+export const MCP_SRC_TOOLS_DIR = 'd:\\wowok\\agent\\mcp\\src\\tools';
+export const GENERATION_SCRIPT = 'd:\\wowok\\agent\\mcp\\scripts\\generate-json-schemas.ts';
+export const TOOLS_INDEX_FILE = 'd:\\wowok\\agent\\mcp\\src\\tools\\index.ts';
+export const MCP_SCHEMA_AUDIT_VERSION = '1.0.0';
+export const TOOLS_17 = [
+    { name: 'onchain_operations', input_schema_export: 'OnchainOperationsSchema', output_schema_export: 'CallOutputSchema' },
+    { name: 'account_operation', input_schema_export: 'AccountOperationSchema', output_schema_export: 'AccountOperationOutputWrappedSchema' },
+    { name: 'local_mark_operation', input_schema_export: 'LocalMarkOperationSchema', output_schema_export: 'LocalMarkOperationOutputWrappedSchema' },
+    { name: 'local_info_operation', input_schema_export: 'LocalInfoOperationSchema', output_schema_export: 'LocalInfoOperationOutputWrappedSchema' },
+    { name: 'wip_file', input_schema_export: 'WipOperationsSchema', output_schema_export: 'WipOperationOutputSchema' },
+    { name: 'messenger_operation', input_schema_export: 'MessengerOperationInputSchema', output_schema_export: 'MessengerOperationOutputSchema' },
+    { name: 'guard2file', input_schema_export: 'Guard2File_InputSchema', output_schema_export: 'Guard2File_OutputWrappedSchema' },
+    { name: 'machineNode2file', input_schema_export: 'MachineNode2File_InputSchema', output_schema_export: 'MachineNode2File_OutputWrappedSchema' },
+    { name: 'query_toolkit', input_schema_export: 'WatchQueryOperationsSchema', output_schema_export: 'WatchQueryOperationsResultSchema' },
+    { name: 'onchain_table_data', input_schema_export: 'OnchainTableDataSchema', output_schema_export: 'OnchainTableDataResultSchema' },
+    { name: 'onchain_events', input_schema_export: 'OnchainEventsInputSchema', output_schema_export: 'OnchainEventsResultSchema' },
+    { name: 'wowok_buildin_info', input_schema_export: 'ProtocolInfoQuerySchema', output_schema_export: 'ProtocolInfoResultSchema' },
+    { name: 'schema_query', input_schema_export: 'SchemaQueryInputSchema', output_schema_export: 'SchemaQueryOutputSchema' },
+    { name: 'bridge_operation', input_schema_export: 'BridgeOperationsSchema', output_schema_export: 'BridgeCallOutputSchema' },
+    { name: 'project_operation', input_schema_export: 'ProjectOperationInputSchema', output_schema_export: 'ProjectOperationOutputSchema' },
+    { name: 'config_operation', input_schema_export: 'ConfigOperationInputSchema', output_schema_export: 'ConfigOperationOutputSchema' },
+    { name: 'trust_score', input_schema_export: 'TrustScoreInputSchema', output_schema_export: 'TrustScoreOutputSchema' },
+];
+export function loadLayer4Deployed(toolName) {
+    const filePath = path.join(DEPLOYED_TOOLS_DIR, `${toolName}.json`);
+    const fallback = {
+        tool_descriptor_file: filePath,
+        file_exists: false,
+        is_stub: true,
+        properties_count: 0,
+        required_count: 0,
+        has_schema_hint: false,
+        has_additional_properties_false: false,
+        has_dollar_schema: false,
+        has_oneof: false,
+        has_anyof: false,
+        has_allof: false,
+        union_count: 0,
+    };
+    if (!fs.existsSync(filePath))
+        return fallback;
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        const args = data.arguments ?? {};
+        const props = args.properties ?? {};
+        const required = args.required ?? [];
+        const propKeys = Object.keys(props);
+        const oneOfArr = args.oneOf ?? [];
+        const anyOfArr = args.anyOf ?? [];
+        const allOfArr = args.allOf ?? [];
+        const hasOneOf = oneOfArr.length > 0;
+        const hasAnyOf = anyOfArr.length > 0;
+        const hasAllOf = allOfArr.length > 0;
+        const unionCount = oneOfArr.length + anyOfArr.length + allOfArr.length;
+        const isStub = propKeys.length === 0 && unionCount === 0;
+        const description = data.description ?? '';
+        const hasSchemaHint = description.includes('schema_query');
+        return {
+            tool_descriptor_file: filePath,
+            file_exists: true,
+            is_stub: isStub,
+            properties_count: propKeys.length,
+            required_count: required.length,
+            has_schema_hint: hasSchemaHint,
+            has_additional_properties_false: args.additionalProperties === false,
+            has_dollar_schema: !!args.$schema,
+            has_oneof: hasOneOf,
+            has_anyof: hasAnyOf,
+            has_allof: hasAllOf,
+            union_count: unionCount,
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
+export function loadLayer3Generated(toolName) {
+    const inputPath = path.join(GENERATED_SCHEMAS_DIR, `${toolName}.schema.json`);
+    const outputPath = path.join(GENERATED_SCHEMAS_DIR, `${toolName}.output.json`);
+    const inputExists = fs.existsSync(inputPath);
+    const outputExists = fs.existsSync(outputPath);
+    const inputSize = inputExists ? fs.statSync(inputPath).size : 0;
+    const outputSize = outputExists ? fs.statSync(outputPath).size : 0;
+    return {
+        input_schema_file: inputPath,
+        output_schema_file: outputPath,
+        input_exists: inputExists,
+        output_exists: outputExists,
+        input_size_bytes: inputSize,
+        output_size_bytes: outputSize,
+    };
+}
+export function analyzeLayerCensus() {
+    const census = [];
+    for (const tool of TOOLS_17) {
+        census.push({
+            name: tool.name,
+            layer2_zod: {
+                input_schema_export: tool.input_schema_export,
+                output_schema_export: tool.output_schema_export,
+                schema_dir: MCP_SRC_SCHEMA_DIR,
+            },
+            layer3_generated: loadLayer3Generated(tool.name),
+            layer4_deployed: loadLayer4Deployed(tool.name) ?? {},
+        });
+    }
+    return census;
+}
+export function analyzeDeployedStubInconsistency(census) {
+    const findings = [];
+    const stubs = [];
+    const fullSchemas = [];
+    for (const c of census) {
+        if (!c.layer4_deployed.file_exists) {
+            findings.push({
+                rule_id: 'MCP-DEPLOY-001',
+                severity: 'critical',
+                category: 'stub_inconsistency',
+                tool_name: c.name,
+                description: `Layer 4 deployed file does not exist: ${c.layer4_deployed.tool_descriptor_file}`,
+                location: c.layer4_deployed.tool_descriptor_file,
+                fix: `Create ${c.name}.json in DEPLOYED_TOOLS_DIR matching the Layer 3 generated schema.`,
+            });
+            continue;
+        }
+        if (c.layer4_deployed.is_stub) {
+            stubs.push(c);
+        }
+        else {
+            fullSchemas.push(c);
+        }
+    }
+    for (const c of stubs) {
+        findings.push({
+            rule_id: 'MCP-STUB-001',
+            severity: 'high',
+            category: 'stub_inconsistency',
+            tool_name: c.name,
+            description: `Layer 4 deployed file is a STUB (empty properties:{}) — LLM must call schema_query(action='get', name='${c.name}') to learn the parameter structure. This is inconsistent with the ${fullSchemas.length} tools that embed full schemas.`,
+            location: c.layer4_deployed.tool_descriptor_file,
+            fix: `Regenerate ${c.name}.json from dist/schemas/${c.name}.schema.json (resolve $ref, inline definitions, wrap as {name, description, arguments}).`,
+        });
+        if (!c.layer4_deployed.has_schema_hint) {
+            findings.push({
+                rule_id: 'MCP-STUB-003',
+                severity: 'high',
+                category: 'stub_inconsistency',
+                tool_name: c.name,
+                description: `Stub file is missing schema_query hint in description — the LLM has no way to discover the parameter structure. Description should mention schema_query(action='get', name='${c.name}').`,
+                location: c.layer4_deployed.tool_descriptor_file,
+                fix: `Add "💡 Schema hint: Use schema_query with action='get' and name='${c.name}' to retrieve the exact parameter schema before calling." to the description.`,
+            });
+        }
+    }
+    if (stubs.length > 0 && fullSchemas.length > 0) {
+        findings.push({
+            rule_id: 'MCP-STUB-002',
+            severity: 'info',
+            category: 'stub_inconsistency',
+            tool_name: '(all)',
+            description: `Layer 4 deployed files are INCONSISTENT: ${stubs.length} stubs + ${fullSchemas.length} full schemas. Stubs: ${stubs.map(s => s.name).join(', ')}. Full: ${fullSchemas.map(s => s.name).join(', ')}.`,
+            fix: `Make all 17 files consistent — either (a) embed full schemas in all 17 (RECOMMENDED — gives LLM immediate access), or (b) keep all stubs and rely on schema_query (increases token cost + latency).`,
+        });
+    }
+    return findings;
+}
+export function analyzeLayerParity(census) {
+    const findings = [];
+    for (const c of census) {
+        if (!c.layer4_deployed.file_exists || c.layer4_deployed.is_stub)
+            continue;
+        if (!c.layer3_generated.input_exists) {
+            findings.push({
+                rule_id: 'MCP-PARITY-001',
+                severity: 'critical',
+                category: 'layer_parity',
+                tool_name: c.name,
+                description: `Layer 4 has full schema but Layer 3 generated file is missing: ${c.layer3_generated.input_schema_file}`,
+                fix: `Run pnpm generate:schemas to regenerate Layer 3 from Zod source.`,
+            });
+            continue;
+        }
+        const l4 = readLayer4Arguments(c.name);
+        const l3 = readLayer3ResolvedSchema(c.name);
+        if (!l4 || !l3)
+            continue;
+        const l4Props = new Set(Object.keys(l4.properties ?? {}));
+        const l3Props = new Set(Object.keys(l3.properties ?? {}));
+        const missingInL4 = [...l3Props].filter(p => !l4Props.has(p));
+        const extraInL4 = [...l4Props].filter(p => !l3Props.has(p));
+        if (missingInL4.length > 0) {
+            findings.push({
+                rule_id: 'MCP-PARITY-002',
+                severity: 'high',
+                category: 'layer_parity',
+                tool_name: c.name,
+                description: `Layer 4 deployed schema is missing ${missingInL4.length} properties present in Layer 3 generated schema: ${missingInL4.join(', ')}`,
+                location: c.layer4_deployed.tool_descriptor_file,
+                fix: `Regenerate ${c.name}.json from dist/schemas/${c.name}.schema.json.`,
+            });
+        }
+        if (extraInL4.length > 0) {
+            findings.push({
+                rule_id: 'MCP-PARITY-003',
+                severity: 'medium',
+                category: 'layer_parity',
+                tool_name: c.name,
+                description: `Layer 4 deployed schema has ${extraInL4.length} extra properties not in Layer 3: ${extraInL4.join(', ')}`,
+                location: c.layer4_deployed.tool_descriptor_file,
+                fix: `Regenerate ${c.name}.json from dist/schemas/${c.name}.schema.json.`,
+            });
+        }
+        const l4Req = new Set(l4.required ?? []);
+        const l3Req = new Set(l3.required ?? []);
+        const reqMissing = [...l3Req].filter(r => !l4Req.has(r));
+        const reqExtra = [...l4Req].filter(r => !l3Req.has(r));
+        if (reqMissing.length > 0 || reqExtra.length > 0) {
+            findings.push({
+                rule_id: 'MCP-PARITY-004',
+                severity: 'high',
+                category: 'layer_parity',
+                tool_name: c.name,
+                description: `Layer 4 'required' array differs from Layer 3. Missing in L4: [${reqMissing.join(', ')}]. Extra in L4: [${reqExtra.join(', ')}].`,
+                location: c.layer4_deployed.tool_descriptor_file,
+                fix: `Sync 'required' array from Layer 3 to Layer 4.`,
+            });
+        }
+        const l4AP = l4.additionalProperties;
+        const l3AP = l3.additionalProperties;
+        if (l4AP !== l3AP) {
+            findings.push({
+                rule_id: 'MCP-PARITY-005',
+                severity: 'medium',
+                category: 'layer_parity',
+                tool_name: c.name,
+                description: `Layer 4 'additionalProperties' (${JSON.stringify(l4AP)}) differs from Layer 3 (${JSON.stringify(l3AP)}).`,
+                location: c.layer4_deployed.tool_descriptor_file,
+                fix: `Sync 'additionalProperties' value.`,
+            });
+        }
+    }
+    return findings;
+}
+function readLayer4Arguments(toolName) {
+    const filePath = path.join(DEPLOYED_TOOLS_DIR, `${toolName}.json`);
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        return data.arguments ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function readLayer3ResolvedSchema(toolName) {
+    const filePath = path.join(GENERATED_SCHEMAS_DIR, `${toolName}.schema.json`);
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        if (data.$ref && data.$ref.startsWith('#/definitions/')) {
+            const defName = data.$ref.slice('#/definitions/'.length);
+            const def = data.definitions?.[defName];
+            if (def && typeof def === 'object') {
+                return def;
+            }
+        }
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+export function analyzeAnyUnknownCensus() {
+    const instances = [];
+    const scanDirs = [MCP_SRC_SCHEMA_DIR, MCP_SRC_TOOLS_DIR];
+    for (const dir of scanDirs) {
+        const files = listTypeScriptFiles(dir);
+        for (const file of files) {
+            const lines = fs.readFileSync(file, 'utf-8').split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                const trimmed = line.trim();
+                if (trimmed.startsWith('//') || trimmed.startsWith('*'))
+                    continue;
+                const patterns = [
+                    { regex: /z\.any\(\)/g, pattern: 'z.any()' },
+                    { regex: /z\.unknown\(\)/g, pattern: 'z.unknown()' },
+                    { regex: /args\s*:\s*any\b/g, pattern: 'args: any' },
+                    { regex: /Promise\s*<\s*any\s*>/g, pattern: 'Promise<any>' },
+                    { regex: /Record\s*<\s*string\s*,\s*any\s*>/g, pattern: 'Record<string, any>' },
+                    { regex: /\bas\s+any\b/g, pattern: 'as any' },
+                ];
+                for (const { regex, pattern } of patterns) {
+                    regex.lastIndex = 0;
+                    let m;
+                    while ((m = regex.exec(line)) !== null) {
+                        const category = categorizeAnyInstance(file, i + 1, line, pattern);
+                        instances.push({
+                            file,
+                            line: i + 1,
+                            code: trimmed.length > 120 ? trimmed.slice(0, 117) + '...' : trimmed,
+                            pattern,
+                            category: category.category,
+                            reason: category.reason,
+                            fix_suggestion: category.fix,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return instances;
+}
+function listTypeScriptFiles(dir) {
+    const result = [];
+    if (!fs.existsSync(dir))
+        return result;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === '__tests__' || entry.name === 'node_modules')
+                continue;
+            result.push(...listTypeScriptFiles(fullPath));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.ts')) {
+            result.push(fullPath);
+        }
+    }
+    return result;
+}
+function categorizeAnyInstance(file, lineNum, line, pattern) {
+    const fileName = path.basename(file);
+    const trimmed = line.trim();
+    if (pattern === 'z.any()' && /SemanticSummarySchema\s*=\s*z\.any\(\)/.test(trimmed)) {
+        return {
+            category: 'fixable',
+            reason: 'Circular-dependency workaround for SemanticSummarySchema — can use z.lazy() or refactor to break the cycle.',
+            fix: 'Define SemanticSummarySchema with z.lazy(() => SemanticSummarySchemaReal) or restructure imports to break the cycle.',
+        };
+    }
+    if (pattern === 'z.any()' && /result\s*:\s*z\.any\(\)/.test(trimmed) && /[\\/]config[\\/]|[\\/]project[\\/]/.test(file)) {
+        return {
+            category: 'fixable',
+            reason: `Result shape depends on action — can use z.discriminatedUnion('action', [...]) to type each action's result.`,
+            fix: `Define discriminated union: z.discriminatedUnion('action', [z.object({action: z.literal('list'), result: ...}), ...]).`,
+        };
+    }
+    if (pattern === 'z.unknown()' && /result\s*:\s*z\.unknown\(\)/.test(trimmed) && /index\.ts/.test(fileName)) {
+        return {
+            category: 'fixable',
+            reason: 'query_toolkit output result depends on query_type — can use z.discriminatedUnion(\'query_type\', [...]).',
+            fix: 'Define discriminated union: z.discriminatedUnion(\'query_type\', [z.object({query_type: z.literal(\'local_mark_list\'), result: z.array(MarkDataSchema)}), ...]).',
+        };
+    }
+    if (pattern === 'z.any()' && /data\s*:\s*z\.any\(\)/.test(trimmed) && /[\\/]schema-query[\\/]/.test(file)) {
+        return {
+            category: 'fixable',
+            reason: 'SchemaQuery output data depends on action — can use discriminated union by action.',
+            fix: 'Define discriminated union: action=\'get\' returns JSON Schema, action=\'list\' returns array of items.',
+        };
+    }
+    if (pattern === 'args: any' && /handlers[\\/]/.test(file)) {
+        return {
+            category: 'fixable',
+            reason: 'Handler args can use `unknown` (forces runtime validation) or a typed input schema.',
+            fix: 'Replace `args: any` with `args: unknown` and use strictParse(schema, args) at the top of the handler.',
+        };
+    }
+    if (pattern === 'args: any' && /tools[\\/]index\.ts/.test(file)) {
+        return {
+            category: 'fixable',
+            reason: 'dispatchToolCall args is `any` — can be `unknown` since each tool parses with its own schema.',
+            fix: 'Change `args: any` to `args: unknown` in dispatchToolCall signature.',
+        };
+    }
+    if (pattern === 'args: any' && /types\.ts/.test(fileName) && /handler/.test(trimmed)) {
+        return {
+            category: 'fixable',
+            reason: 'ToolEntry.handler args is `any` — can be `unknown` (each handler parses with its own schema).',
+            fix: 'Change `handler: (args: any) => ...` to `handler: (args: unknown) => ...`.',
+        };
+    }
+    if (pattern === 'z.any()' && /claimReceipt|ethReceipt|wowReceipt/.test(trimmed)) {
+        return {
+            category: 'legitimate',
+            reason: 'EVM transaction receipts have an externally-defined shape from viem/ethers — z.any() is acceptable (receipt is informational, not validated).',
+        };
+    }
+    if (pattern === 'z.any()' && /content_raw/.test(trimmed)) {
+        return {
+            category: 'legitimate',
+            reason: 'content_raw holds raw content for unknown object types — by definition untyped. z.any() is acceptable here.',
+        };
+    }
+    if ((pattern === 'z.unknown()' || pattern === 'z.any()') && /parsedJson/.test(trimmed)) {
+        return {
+            category: 'legitimate',
+            reason: 'Event parsedJson is arbitrary on-chain event data — z.record(z.string(), z.unknown()) is appropriate.',
+        };
+    }
+    if (pattern === 'z.any()' && /key_value/.test(trimmed)) {
+        return {
+            category: 'fixable',
+            reason: 'Repository key_value depends on key_type — could use discriminated union by key_type (string→z.string(), u64→z.bigint()/number, etc.).',
+            fix: 'Define z.discriminatedUnion(\'key_type\', [...]) with each variant typed.',
+        };
+    }
+    if (pattern === 'z.unknown()' && /data\s*:\s*z\.unknown\(\)/.test(trimmed) && /[\\/]bridge/.test(file)) {
+        return {
+            category: 'legitimate',
+            reason: 'Bridge operation result data varies by operation_type — currently 9 different shapes. Discriminated union would be ideal but high refactor cost.',
+        };
+    }
+    if (pattern === 'z.unknown()' && /adjusted_params/.test(trimmed)) {
+        return {
+            category: 'legitimate',
+            reason: 'adjusted_params are free-form key-value pairs suggested by AI — z.record(z.string(), z.unknown()) is appropriate.',
+        };
+    }
+    if (pattern === 'z.any()' && /object\s*:\s*z\.union.*z\.record\(z\.any\(\)/.test(trimmed)) {
+        return {
+            category: 'fixable',
+            reason: 'Creation vs reference object union — z.record(z.any()) should be replaced with NamedObjectSchema (structured creation input).',
+            fix: 'Replace z.record(z.any()) with NamedObjectSchema (already defined in base.ts).',
+        };
+    }
+    if (pattern === 'z.any()' && /result\s*:\s*z\.any\(\)\.optional\(\)/.test(trimmed) && /[\\/]bridge/.test(file)) {
+        return {
+            category: 'legitimate',
+            reason: 'Bridge result is operation-specific (manage_evm_rpc has different result per operation) — z.any().optional() is acceptable here.',
+        };
+    }
+    if (pattern === 'Promise<any>' && /[\\/](wrap|shared)\.ts/.test(file)) {
+        return {
+            category: 'fixable',
+            reason: 'Generic wrappers in wrap.ts/shared.ts use Promise<any> — could be made generic <T>.',
+            fix: 'Replace `Promise<any>` with `Promise<ToolDispatchResult>` (the actual return shape).',
+        };
+    }
+    if (pattern === 'Record<string, any>' && /types\.ts/.test(fileName) && /_meta|structuredContent/.test(trimmed)) {
+        return {
+            category: 'fixable',
+            reason: 'ToolConfig._meta and ToolDispatchResult.structuredContent could use structured types.',
+            fix: 'Define ToolMeta interface (category, tags) and replace structuredContent: any with structured type.',
+        };
+    }
+    if (pattern === 'as any') {
+        return {
+            category: 'legitimate',
+            reason: '`as any` cast — usually for third-party type mismatches (MCP SDK). Acceptable if isolated.',
+        };
+    }
+    return {
+        category: 'legitimate',
+        reason: 'Unclassified any/unknown usage — review manually. Defaulting to legitimate (no auto-fix).',
+    };
+}
+export function analyzeHandlerTypeSafety(instances) {
+    const findings = [];
+    for (const inst of instances) {
+        if (inst.pattern !== 'args: any')
+            continue;
+        if (!/tools[\\/]/.test(inst.file))
+            continue;
+        findings.push({
+            rule_id: 'MCP-HANDLER-001',
+            severity: 'medium',
+            category: 'handler_types',
+            tool_name: path.basename(inst.file, '.ts'),
+            description: `Handler uses \`args: any\` — bypasses TypeScript type checking. ${inst.reason}`,
+            location: `${inst.file}:${inst.line}`,
+            fix: inst.fix_suggestion,
+        });
+    }
+    return findings;
+}
+export function analyzeOutputSchemaCoverage(census) {
+    const findings = [];
+    for (const c of census) {
+        if (!c.layer3_generated.output_exists) {
+            findings.push({
+                rule_id: 'MCP-OUTPUT-001',
+                severity: 'high',
+                category: 'output_coverage',
+                tool_name: c.name,
+                description: `Layer 3 output schema file does not exist: ${c.layer3_generated.output_schema_file}`,
+                fix: `Add outputSchema to ${c.name}'s tool definition and regenerate schemas.`,
+            });
+        }
+        if (c.layer2_zod.output_schema_export === null) {
+            findings.push({
+                rule_id: 'MCP-OUTPUT-002',
+                severity: 'medium',
+                category: 'output_coverage',
+                tool_name: c.name,
+                description: `Layer 2 outputSchema is defined inline (not exported with a stable name). This makes it harder to reference from tests.`,
+                fix: `Export the outputSchema with a stable name (e.g., ${c.name}OutputSchema).`,
+            });
+        }
+    }
+    return findings;
+}
+export function analyzeGenerationScriptSync() {
+    const findings = [];
+    if (!fs.existsSync(GENERATION_SCRIPT)) {
+        findings.push({
+            rule_id: 'MCP-GENSYNC-001',
+            severity: 'critical',
+            category: 'generation_sync',
+            tool_name: '(all)',
+            description: `Generation script not found: ${GENERATION_SCRIPT}`,
+        });
+        return findings;
+    }
+    const src = fs.readFileSync(GENERATION_SCRIPT, 'utf-8');
+    const nameRegex = /name:\s*["']([^"']+)["']/g;
+    const scriptNames = new Set();
+    let m;
+    while ((m = nameRegex.exec(src)) !== null) {
+        if (TOOLS_17.some(t => t.name === m[1])) {
+            scriptNames.add(m[1]);
+        }
+    }
+    for (const tool of TOOLS_17) {
+        if (!scriptNames.has(tool.name)) {
+            findings.push({
+                rule_id: 'MCP-GENSYNC-002',
+                severity: 'high',
+                category: 'generation_sync',
+                tool_name: tool.name,
+                description: `Tool "${tool.name}" is in TOOL_REGISTRY but missing from generate-json-schemas.ts. Layer 3 schemas will not be generated.`,
+                location: GENERATION_SCRIPT,
+                fix: `Add a get${toPascalCase(tool.name)}Tool() function and add it to the tools array.`,
+            });
+        }
+    }
+    return findings;
+}
+function toPascalCase(s) {
+    return s.split('_').map(p => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase()).join('');
+}
+export function analyzeSchemaQueryReflection(census) {
+    const findings = [];
+    for (const c of census) {
+        if (!c.layer3_generated.input_exists) {
+            findings.push({
+                rule_id: 'MCP-REFLECT-001',
+                severity: 'high',
+                category: 'reflection',
+                tool_name: c.name,
+                description: `schema_query(action='get', name='${c.name}') would fail — Layer 3 input schema missing.`,
+                fix: `Run pnpm generate:schemas.`,
+            });
+        }
+        if (!c.layer3_generated.output_exists) {
+            findings.push({
+                rule_id: 'MCP-REFLECT-002',
+                severity: 'medium',
+                category: 'reflection',
+                tool_name: c.name,
+                description: `schema_query(action='get_output', name='${c.name}') would fail — Layer 3 output schema missing.`,
+                fix: `Run pnpm generate:schemas.`,
+            });
+        }
+    }
+    const onchainOps = [
+        'permission', 'service', 'machine', 'progress', 'guard',
+        'arbitration', 'repository', 'contact', 'treasury', 'reward',
+        'allocation', 'personal', 'payment', 'demand', 'order', 'gen_passport',
+    ];
+    for (const op of onchainOps) {
+        const opFile = path.join(GENERATED_SCHEMAS_DIR, `onchain_operations_${op}.schema.json`);
+        if (!fs.existsSync(opFile)) {
+            findings.push({
+                rule_id: 'MCP-REFLECT-003',
+                severity: 'medium',
+                category: 'reflection',
+                tool_name: `onchain_operations_${op}`,
+                description: `Individual operation schema missing: ${opFile}. schema_query(action='get', name='onchain_operations_${op}') would fail.`,
+                fix: `Run pnpm generate:schemas.`,
+            });
+        }
+    }
+    return findings;
+}
+export function scanAllMcpSchemas() {
+    const census = analyzeLayerCensus();
+    const anyInstances = analyzeAnyUnknownCensus();
+    const findings = [
+        ...analyzeDeployedStubInconsistency(census),
+        ...analyzeLayerParity(census),
+        ...analyzeHandlerTypeSafety(anyInstances),
+        ...analyzeOutputSchemaCoverage(census),
+        ...analyzeGenerationScriptSync(),
+        ...analyzeSchemaQueryReflection(census),
+    ];
+    const bySev = new Map();
+    const byCat = new Map();
+    for (const f of findings) {
+        if (!bySev.has(f.severity))
+            bySev.set(f.severity, []);
+        bySev.get(f.severity).push(f);
+        if (!byCat.has(f.category))
+            byCat.set(f.category, []);
+        byCat.get(f.category).push(f);
+    }
+    const fixable = anyInstances.filter(i => i.category === 'fixable').length;
+    const legit = anyInstances.filter(i => i.category === 'legitimate').length;
+    const external = anyInstances.filter(i => i.category === 'external').length;
+    const stubCount = census.filter(c => c.layer4_deployed.is_stub).length;
+    const fullCount = census.filter(c => !c.layer4_deployed.is_stub && c.layer4_deployed.file_exists).length;
+    return {
+        census,
+        findings,
+        any_unknown_instances: anyInstances,
+        findings_by_severity: bySev,
+        findings_by_category: byCat,
+        total_findings: findings.length,
+        fixable_any_count: fixable,
+        legitimate_any_count: legit,
+        external_any_count: external,
+        stub_count: stubCount,
+        full_schema_count: fullCount,
+    };
+}
+export function formatAuditReport(result) {
+    const lines = [];
+    lines.push(`# MCP Schema Audit Report — 17 WoWok Tools`);
+    lines.push('');
+    lines.push(`> Auto-generated by \`mcp-schema-audit.ts\` v${MCP_SCHEMA_AUDIT_VERSION} — comprehensive`);
+    lines.push(`> 4-layer audit of schema consistency, any/unknown usage, and I/O coverage.`);
+    lines.push('');
+    lines.push(`## Summary`);
+    lines.push('');
+    lines.push(`- **Tools audited**: ${result.census.length}`);
+    lines.push(`- **Total findings**: ${result.total_findings}`);
+    lines.push(`- **Stub files**: ${result.stub_count} / ${result.census.length}`);
+    lines.push(`- **Full schema files**: ${result.full_schema_count} / ${result.census.length}`);
+    lines.push(`- **any/unknown instances**: ${result.any_unknown_instances.length} total`);
+    lines.push(`  - Fixable: ${result.fixable_any_count}`);
+    lines.push(`  - Legitimate: ${result.legitimate_any_count}`);
+    lines.push(`  - External: ${result.external_any_count}`);
+    lines.push('');
+    lines.push(`### Findings by Severity`);
+    lines.push('');
+    lines.push(`| Severity | Count |`);
+    lines.push(`|----------|-------|`);
+    for (const sev of ['critical', 'high', 'medium', 'low', 'info']) {
+        const arr = result.findings_by_severity.get(sev) ?? [];
+        lines.push(`| ${sev} | ${arr.length} |`);
+    }
+    lines.push('');
+    lines.push(`### Findings by Category`);
+    lines.push('');
+    lines.push(`| Category | Count |`);
+    lines.push(`|----------|-------|`);
+    for (const cat of ['stub_inconsistency', 'layer_parity', 'handler_types', 'output_coverage', 'generation_sync', 'reflection']) {
+        const arr = result.findings_by_category.get(cat) ?? [];
+        lines.push(`| ${cat} | ${arr.length} |`);
+    }
+    lines.push('');
+    lines.push(`## Layer Census — All 17 Tools`);
+    lines.push('');
+    lines.push(`| Tool | L3 Input | L3 Output | L4 Status | L4 Properties | L4 Required |`);
+    lines.push(`|------|----------|-----------|-----------|---------------|-------------|`);
+    for (const c of result.census) {
+        const l3i = c.layer3_generated.input_exists ? `✓ ${(c.layer3_generated.input_size_bytes / 1024).toFixed(1)}KB` : '✗ MISSING';
+        const l3o = c.layer3_generated.output_exists ? `✓ ${(c.layer3_generated.output_size_bytes / 1024).toFixed(1)}KB` : '✗ MISSING';
+        const l4s = !c.layer4_deployed.file_exists ? '✗ MISSING' : c.layer4_deployed.is_stub ? '⚠ STUB' : '✓ FULL';
+        const l4p = c.layer4_deployed.properties_count;
+        const l4r = c.layer4_deployed.required_count;
+        lines.push(`| ${c.name} | ${l3i} | ${l3o} | ${l4s} | ${l4p} | ${l4r} |`);
+    }
+    lines.push('');
+    lines.push(`## Findings Detail`);
+    lines.push('');
+    const orderedSeverities = ['critical', 'high', 'medium', 'low', 'info'];
+    for (const sev of orderedSeverities) {
+        const sevFindings = result.findings_by_severity.get(sev) ?? [];
+        if (sevFindings.length === 0)
+            continue;
+        const title = sev.toUpperCase();
+        lines.push(`### ${title} (${sevFindings.length})`);
+        lines.push('');
+        for (const f of sevFindings) {
+            lines.push(`- **[${f.rule_id}] ${f.description}`);
+            if (f.location)
+                lines.push(`  - Location: \`${f.location}\``);
+            if (f.fix)
+                lines.push(`  - Fix: ${f.fix}`);
+            lines.push('');
+        }
+    }
+    lines.push(`## any/unknown Census Detail`);
+    lines.push('');
+    lines.push(`Total instances: ${result.any_unknown_instances.length}`);
+    lines.push('');
+    lines.push(`### By Pattern`);
+    lines.push('');
+    lines.push(`| Pattern | Total | Fixable | Legitimate | External |`);
+    lines.push(`|---------|-------|---------|------------|----------|`);
+    const patternGroups = new Map();
+    for (const inst of result.any_unknown_instances) {
+        if (!patternGroups.has(inst.pattern))
+            patternGroups.set(inst.pattern, []);
+        patternGroups.get(inst.pattern).push(inst);
+    }
+    for (const [pattern, arr] of [...patternGroups.entries()].sort((a, b) => b[1].length - a[1].length)) {
+        const fixable = arr.filter(i => i.category === 'fixable').length;
+        const legit = arr.filter(i => i.category === 'legitimate').length;
+        const ext = arr.filter(i => i.category === 'external').length;
+        lines.push(`| \`${pattern}\` | ${arr.length} | ${fixable} | ${legit} | ${ext} |`);
+    }
+    lines.push('');
+    const fixable = result.any_unknown_instances.filter(i => i.category === 'fixable');
+    if (fixable.length > 0) {
+        lines.push(`### Fixable Instances (Priority List)`);
+        lines.push('');
+        for (const inst of fixable) {
+            lines.push(`- **${path.basename(inst.file)}:${inst.line}** [\`${inst.pattern}\`]`);
+            lines.push(`  - Code: \`${inst.code}\``);
+            lines.push(`  - Reason: ${inst.reason}`);
+            if (inst.fix_suggestion)
+                lines.push(`  - Fix: ${inst.fix_suggestion}`);
+            lines.push('');
+        }
+    }
+    lines.push(`## Recommended Action Plan`);
+    lines.push('');
+    lines.push(`### Phase 1: Fix Layer 4 Stub Inconsistency (CRITICAL UX)`);
+    lines.push('');
+    lines.push(`The ${result.stub_count} stub files force the LLM to call \`schema_query\` first, creating an extra round-trip. Fix by regenerating all 17 Layer 4 files from Layer 3 schemas:`);
+    lines.push('');
+    lines.push(`\`\`\`bash`);
+    lines.push(`# 1. Generate Layer 3 schemas from Zod source`);
+    lines.push(`cd d:/wowok/agent/mcp && pnpm generate:schemas`);
+    lines.push('');
+    lines.push(`# 2. Generate Layer 4 deployed files from Layer 3`);
+    lines.push(`# (Run the new sync-deployed-tools.ts script — see E2.4)`);
+    lines.push(`npx tsx scripts/sync-deployed-tools.ts`);
+    lines.push(`\`\`\``);
+    lines.push('');
+    lines.push(`### Phase 2: Type the ${result.fixable_any_count} fixable any/unknown instances`);
+    lines.push('');
+    lines.push(`Priority order:`);
+    lines.push('');
+    lines.push(`1. **SemanticSummarySchema** (src/schema/local/index.ts:6) — use \`z.lazy()\``);
+    lines.push(`2. **ConfigOperationOutputSchema.result** (src/schema/config/index.ts:17) — discriminated union by action`);
+    lines.push(`3. **ProjectOperationOutputSchema.result** (src/schema/project/index.ts:34) — discriminated union by action`);
+    lines.push(`4. **query_toolkit output result** (src/tools/index.ts:250) — discriminated union by query_type`);
+    lines.push(`5. **SchemaQueryOutputSchema.data** (src/schema/schema-query/index.ts:34) — discriminated union by action`);
+    lines.push(`6. **RepositoryKeyValueSchema.key_value** (src/schema/operations.ts:331) — discriminated union by key_type`);
+    lines.push(`7. **Handler args: any** — replace with \`unknown\` (forces strictParse at top of handler)`);
+    lines.push(`8. **dispatchToolCall(name, args: any)** — replace with \`unknown\``);
+    lines.push('');
+    lines.push(`### Phase 3: Verify I/O Schema Match`);
+    lines.push('');
+    lines.push(`For each tool, write a parity test that:`);
+    lines.push(`1. Calls the handler with a minimal valid input`);
+    lines.push(`2. Captures the structuredContent`);
+    lines.push(`3. Validates structuredContent against outputSchema`);
+    lines.push(`4. Reports any mismatch`);
+    lines.push('');
+    return lines.join('\n');
+}