@wowok/agent-mcp 2.6.1 → 2.6.4

package/dist/schema-query/index.js

@@ -1,6 +1,10 @@
-import { readFileSync, existsSync, writeFileSync, mkdirSync } from "fs";
+import { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync } from "fs";
 import { resolve, join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { TOOLS_REFERENCE, getToolReference, searchToolReference, getToolSequence, } from "../knowledge/tools-reference.js";
+import { GUARD_DESIGN_PATTERNS, getGuardDesignPattern, GUARD_DESIGN_PATTERNS_VERSION, } from "../knowledge/guard-design-patterns.js";
+import { OBJECT_REUSE_RULES, CREATE_VS_MODIFY_PATTERN, IMMUTABILITY_RULES, OPERATION_TYPE_CLASSIFICATION, OPERATION_CLASS_META, NAMING_CONVENTIONS, SAFETY_RULES_VERSION, } from "../knowledge/safety-rules.js";
+import { listTemplates as listRegistryTemplates, getTemplateDetail, instantiateTemplate, getTemplateCounts, TEMPLATE_OBJECT_TYPES, } from "../knowledge/template-registry.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const SCHEMAS_DIR = resolve(__dirname, "../../dist/schemas");
@@ -9,6 +13,11 @@ const GUARD_TEMPLATES_PATH_DIST = resolve(__dirname, "../../dist/schemas/guard-t
 const GUARD_TEMPLATES_PATH = existsSync(GUARD_TEMPLATES_PATH_SCRIPTS)
     ? GUARD_TEMPLATES_PATH_SCRIPTS
     : GUARD_TEMPLATES_PATH_DIST;
+const EXAMPLES_DIR_SCRIPTS = resolve(__dirname, "../../scripts/examples");
+const EXAMPLES_DIR_DIST = resolve(__dirname, "../examples");
+export const EXAMPLES_DIR = existsSync(EXAMPLES_DIR_SCRIPTS)
+    ? EXAMPLES_DIR_SCRIPTS
+    : EXAMPLES_DIR_DIST;
 const WORKSPACE_TMP_DIR = resolve(process.cwd(), ".trae", "tmp");
 export function areSchemasAvailable() {
     return existsSync(SCHEMAS_DIR) && existsSync(join(SCHEMAS_DIR, "index.json"));
@@ -96,6 +105,75 @@ export function getGuardTemplates(templateName) {
         return null;
     }
 }
+export function searchExamples(query) {
+    if (!existsSync(EXAMPLES_DIR)) {
+        return [];
+    }
+    let files;
+    try {
+        files = readdirSync(EXAMPLES_DIR);
+    }
+    catch {
+        return [];
+    }
+    const lowerQuery = query.toLowerCase().trim();
+    if (!lowerQuery) {
+        return [];
+    }
+    const results = [];
+    for (const file of files) {
+        if (!file.endsWith(".json"))
+            continue;
+        const filePath = join(EXAMPLES_DIR, file);
+        try {
+            const content = readFileSync(filePath, "utf-8");
+            const example = JSON.parse(content);
+            const title = String(example.title ?? "");
+            const description = String(example.description ?? "");
+            const tags = Array.isArray(example.tags) ? example.tags.map((t) => String(t)) : [];
+            const operationType = String(example.operation_type ?? "");
+            const industry = String(example.industry ?? "");
+            const matchedFields = [];
+            if (title.toLowerCase().includes(lowerQuery)) {
+                matchedFields.push("title");
+            }
+            if (description.toLowerCase().includes(lowerQuery)) {
+                matchedFields.push("description");
+            }
+            if (tags.some((t) => t.toLowerCase() === lowerQuery)) {
+                matchedFields.push("tags");
+            }
+            if (operationType && operationType.toLowerCase() === lowerQuery) {
+                matchedFields.push("operation_type");
+            }
+            if (industry && industry.toLowerCase() === lowerQuery) {
+                matchedFields.push("industry");
+            }
+            if (matchedFields.length > 0) {
+                results.push({
+                    file,
+                    title,
+                    description,
+                    tags,
+                    industry,
+                    operation_type: operationType,
+                    verified: example.verified === true,
+                    score: matchedFields.length,
+                    matched_fields: matchedFields,
+                });
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    results.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.file.localeCompare(b.file);
+    });
+    return results;
+}
 export function getSchemaField(name, fieldPath) {
     const schema = getSchema(name);
     if (!schema)
@@ -228,7 +306,7 @@ function writeResponseToFile(data, preferredPath) {
     }
 }
 export function processSchemaQuery(request) {
-    const { action, name, query, field_path, template, output_file } = request;
+    const { action, name, query, field_path, template, output_file, object_type, params } = request;
     if (action === "get_guard_templates") {
         const templates = getGuardTemplates(template);
         if (!templates) {
@@ -267,6 +345,284 @@ export function processSchemaQuery(request) {
                 : `Retrieved ${Array.isArray(templates.templates) ? templates.templates.length : 0} Guard templates`,
         };
     }
+    if (action === "get_templates") {
+        if (!template) {
+            const metas = listRegistryTemplates(object_type);
+            const counts = getTemplateCounts();
+            const data = {
+                total: metas.length,
+                filter: object_type ?? null,
+                counts_by_object_type: counts,
+                templates: metas,
+            };
+            if (output_file) {
+                const filePath = writeResponseToFile(data, output_file);
+                if (filePath) {
+                    return {
+                        success: true,
+                        action,
+                        data: null,
+                        message: `${metas.length} templates written to file: ${filePath}`,
+                        output_file_path: filePath,
+                        suggestions: [`Use Read tool to open ${filePath}`],
+                    };
+                }
+            }
+            return {
+                success: true,
+                action,
+                data,
+                message: `${metas.length} template(s)${object_type ? ` for object_type='${object_type}'` : ""} ` +
+                    `(total registry: ${Object.values(counts).reduce((a, b) => a + b, 0)} across ${TEMPLATE_OBJECT_TYPES.length} object types). ` +
+                    `Provide 'template' (id) for full detail; add 'params' (JSON string) to instantiate.`,
+            };
+        }
+        if (!params) {
+            const detail = getTemplateDetail(template);
+            if (!detail) {
+                return {
+                    success: false,
+                    action,
+                    data: null,
+                    message: `Template '${template}' not found in the unified registry.`,
+                    suggestions: [
+                        "Omit 'template' to list all template metadata (id + object_type + parameters).",
+                        `Filter by object_type: ${TEMPLATE_OBJECT_TYPES.join(", ")}`,
+                    ],
+                };
+            }
+            if (output_file) {
+                const filePath = writeResponseToFile(detail, output_file);
+                if (filePath) {
+                    return {
+                        success: true,
+                        action,
+                        data: null,
+                        message: `Template '${template}' detail written to file: ${filePath}`,
+                        output_file_path: filePath,
+                        suggestions: [`Use Read tool to open ${filePath}`],
+                    };
+                }
+            }
+            return {
+                success: true,
+                action,
+                data: detail,
+                message: `Template '${template}' (${detail.object_type}, ${detail.instantiable ? "instantiable" : "guidance-only"}). ` +
+                    `To instantiate, call again with 'params' = JSON object of the declared parameters.`,
+            };
+        }
+        let parsedParams;
+        try {
+            const parsed = JSON.parse(params);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                return {
+                    success: false,
+                    action,
+                    data: null,
+                    message: `'params' must be a JSON object (e.g. '{"key":"value"}'), got ${Array.isArray(parsed) ? "array" : typeof parsed}.`,
+                };
+            }
+            parsedParams = parsed;
+        }
+        catch (e) {
+            return {
+                success: false,
+                action,
+                data: null,
+                message: `Failed to parse 'params' as JSON: ${e instanceof Error ? e.message : String(e)}`,
+                suggestions: ["Example: params='{\"whitelist\":[\"0xabc...\"]}'"],
+            };
+        }
+        const result = instantiateTemplate(template, parsedParams);
+        if (!result.ok) {
+            return {
+                success: false,
+                action,
+                data: result.guidance !== undefined ? { guidance: result.guidance } : null,
+                message: `Instantiation failed for '${template}': ${result.error}`,
+                suggestions: result.missing_params
+                    ? [`Missing required params: ${result.missing_params.join(", ")}`, "Call with 'template' only (no 'params') to see full parameter declarations."]
+                    : ["Call with 'template' only (no 'params') to see full parameter declarations."],
+            };
+        }
+        const data = {
+            object_type: result.object_type,
+            template_id: result.template_id,
+            body: result.body,
+            ...(result.notes ? { notes: result.notes } : {}),
+        };
+        if (output_file) {
+            const filePath = writeResponseToFile(data, output_file);
+            if (filePath) {
+                return {
+                    success: true,
+                    action,
+                    data: null,
+                    message: `Instantiated template '${template}' written to file: ${filePath}`,
+                    output_file_path: filePath,
+                    suggestions: [`Use Read tool to open ${filePath}`],
+                };
+            }
+        }
+        return {
+            success: true,
+            action,
+            data,
+            message: `Instantiated '${template}' (${result.object_type}). ` +
+                `Review the body against the onchain_operations schema before submitting.`,
+        };
+    }
+    if (action === "search_examples") {
+        if (!query) {
+            return {
+                success: false,
+                action,
+                data: null,
+                message: "Search query is required for 'search_examples' action",
+                suggestions: [
+                    "Provide a 'query' string (e.g. 'rental', 'guard', 'service', 'machine')",
+                    "Searchable fields: title, description, tags, operation_type, industry",
+                ],
+            };
+        }
+        const results = searchExamples(query);
+        return {
+            success: true,
+            action,
+            data: results,
+            message: `Found ${results.length} example(s) matching '${query}'`,
+            suggestions: results.length === 0
+                ? [
+                    "Try broader terms like 'service', 'machine', 'guard', 'permission'",
+                    "Try an industry name: 'rental', 'retail', 'general'",
+                    "Use 'get' action with a schema name to see the full JSON Schema",
+                ]
+                : undefined,
+        };
+    }
+    if (action === "get_tool_reference") {
+        if (name) {
+            const entry = getToolReference(name);
+            if (!entry) {
+                return {
+                    success: false,
+                    action,
+                    data: null,
+                    message: `Tool '${name}' not found in the tool reference.`,
+                    suggestions: [
+                        "Omit 'name' to list all tools.",
+                        `Available tools: ${TOOLS_REFERENCE.map((t) => t.name).join(", ")}`,
+                    ],
+                };
+            }
+            const sequence = getToolSequence(name);
+            return {
+                success: true,
+                action,
+                data: { tool: entry, call_sequence: sequence ?? null },
+                message: `Retrieved tool reference: ${name}`,
+            };
+        }
+        if (query) {
+            const matches = searchToolReference(query);
+            return {
+                success: true,
+                action,
+                data: { tools: matches, count: matches.length },
+                message: `Found ${matches.length} tool(s) matching '${query}'`,
+                suggestions: matches.length === 0
+                    ? ["Try a broader keyword (e.g. 'onchain', 'guard', 'schema'), or omit 'query' to list all tools."]
+                    : undefined,
+            };
+        }
+        const catalog = TOOLS_REFERENCE.map((t) => ({
+            name: t.name,
+            summary: t.summary,
+            actions: t.actions ?? [],
+            notes: t.notes ?? [],
+        }));
+        return {
+            success: true,
+            action,
+            data: { tools: catalog, count: catalog.length },
+            message: `Retrieved reference for ${catalog.length} MCP tools. Pass name='<tool>' for full detail (params, prerequisites, follow-ups).`,
+        };
+    }
+    if (action === "get_guard_design_patterns") {
+        if (name) {
+            const pattern = getGuardDesignPattern(name);
+            if (!pattern) {
+                return {
+                    success: false,
+                    action,
+                    data: null,
+                    message: `Guard design pattern '${name}' not found.`,
+                    suggestions: [
+                        "Omit 'name' to list the full catalog.",
+                        `Available pattern ids: ${GUARD_DESIGN_PATTERNS.map((p) => p.id).join(", ")}`,
+                    ],
+                };
+            }
+            return {
+                success: true,
+                action,
+                data: { pattern },
+                message: `Retrieved Guard design pattern: ${name}`,
+            };
+        }
+        if (query) {
+            const byHost = GUARD_DESIGN_PATTERNS.filter((p) => p.host === query);
+            const matches = byHost.length > 0
+                ? byHost
+                : GUARD_DESIGN_PATTERNS.filter((p) => p.business_requirement.toLowerCase().includes(query.toLowerCase()) ||
+                    p.logic_summary.toLowerCase().includes(query.toLowerCase()));
+            return {
+                success: true,
+                action,
+                data: { patterns: matches, count: matches.length, filtered_by: byHost.length > 0 ? "host" : "keyword" },
+                message: `Found ${matches.length} Guard design pattern(s) matching '${query}'`,
+                suggestions: matches.length === 0
+                    ? ["Filter by host: service_buy_guard, service_allocator_guard, machine_forward, progress_submission, reward_claim, repository_write, arbitration_usage, arbitration_voting, gen_passport"]
+                    : undefined,
+            };
+        }
+        const catalog = GUARD_DESIGN_PATTERNS.map((p) => ({
+            id: p.id,
+            business_requirement: p.business_requirement,
+            host: p.host,
+            data_source: p.data_source,
+            verifier_level: p.verifier_level,
+            logic_summary: p.logic_summary,
+            key_queries: p.key_queries,
+            notes: p.notes ?? [],
+        }));
+        return {
+            success: true,
+            action,
+            data: { patterns: catalog, count: catalog.length, version: GUARD_DESIGN_PATTERNS_VERSION },
+            message: `Retrieved ${catalog.length} Guard design patterns. Pass name='<pattern_id>' for full detail (witness types, mitigated risks, industries).`,
+        };
+    }
+    if (action === "get_safety_rules") {
+        return {
+            success: true,
+            action,
+            data: {
+                version: SAFETY_RULES_VERSION,
+                object_reuse_rules: OBJECT_REUSE_RULES,
+                create_vs_modify_pattern: CREATE_VS_MODIFY_PATTERN,
+                immutability_rules: IMMUTABILITY_RULES,
+                operation_type_classification: OPERATION_TYPE_CLASSIFICATION,
+                operation_class_meta: OPERATION_CLASS_META,
+                naming_conventions: NAMING_CONVENTIONS,
+            },
+            message: "Retrieved safety rule tables (reuse / immutability / operation classification / naming). " +
+                "Key points: prefer REUSING existing objects (string reference = reuse, object shape = create); " +
+                "Machine publish locks nodes/pairs/forwards, Service publish locks machine/order_allocators/arbitrations (sales stays mutable); " +
+                "Guard is CREATE-only immutable; on-chain writes require explicit user confirmation.",
+        };
+    }
     if (!areSchemasAvailable()) {
         return {
             success: false,
@@ -448,7 +804,7 @@ export function processSchemaQuery(request) {
                 action,
                 data: null,
                 message: `Unknown action: ${action}`,
-                suggestions: ["Use 'list', 'get', 'get_field', 'get_output', 'search', 'list_operations', or 'get_guard_templates'"],
+                suggestions: ["Use 'list', 'get', 'get_field', 'get_output', 'search', 'list_operations', 'get_guard_templates', or 'search_examples'"],
             };
     }
 }

package/dist/schemas/account_operation.schema.json

@@ -236,7 +236,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Account operations. Parameters MUST be wrapped in the operation type property (e.g. {transfer: {...}}, NOT {amount: ...}). Unwrapped parameters are rejected."
+      "description": "Account operations (mutations only: gen/faucet/suspend/resume/rename/swap_name/transfer/get/signData/messenger). Parameters MUST be wrapped in the operation type property (e.g. {transfer: {...}}, NOT {amount: ...}). Unwrapped parameters are rejected. TO LIST ALL ACCOUNTS: use the query_toolkit tool with query_type='account_list' (returns name, address, suspended status, messenger status for all local accounts). This separation follows CQRS: account_operation = mutations, query_toolkit = queries. Common workflow after MCP restart: (1) query_toolkit query_type='account_list' to see all accounts, (2) account_operation with the appropriate mutation."
     }
   }
 }

package/dist/schemas/bridge_operation.schema.json

@@ -108,6 +108,7 @@
                 },
                 "schema_strict_mode": {
                   "type": "boolean",
+                  "default": false,
                   "description": "When true, schema incompatibility returns an error instead of a warning. Default: false (warn mode)."
                 },
                 "dry_run": {
@@ -289,7 +290,7 @@
                     "mainnet"
                   ],
                   "default": "mainnet",
-                  "description": "Target chain (defaults to Ethereum mainnet)"
+                  "description": "Target chain (defaults to Ethereum mainnet when omitted — EvmChainSchema carries .default(\"mainnet\"))"
                 }
               },
               "required": [
@@ -319,6 +320,7 @@
               "properties": {
                 "network": {
                   "$ref": "#/definitions/bridge_operation/anyOf/4/properties/data/properties/network",
+                  "default": "mainnet",
                   "description": "Specific chain; if omitted, queries all supported chains"
                 },
                 "tokens": {
@@ -364,7 +366,7 @@
               "type": "object",
               "properties": {
                 "network": {
-                  "$ref": "#/definitions/bridge_operation/anyOf/4/properties/data/properties/network",
+                  "$ref": "#/definitions/bridge_operation/anyOf/5/properties/data/properties/network",
                   "description": "Specific chain; if omitted, returns token lists for all supported chains"
                 }
               },
@@ -485,7 +487,8 @@
                     },
                     "network": {
                       "$ref": "#/definitions/bridge_operation/anyOf/4/properties/data/properties/network",
-                      "description": "Target chain (defaults to Ethereum mainnet)"
+                      "default": "mainnet",
+                      "description": "Target chain (defaults to Ethereum mainnet when omitted — EvmChainSchema carries .default(\"mainnet\"))"
                     }
                   },
                   "required": [
@@ -504,7 +507,8 @@
                     },
                     "network": {
                       "$ref": "#/definitions/bridge_operation/anyOf/4/properties/data/properties/network",
-                      "description": "Target chain (defaults to Ethereum mainnet)"
+                      "default": "mainnet",
+                      "description": "Target chain (defaults to Ethereum mainnet when omitted — EvmChainSchema carries .default(\"mainnet\"))"
                     },
                     "rpcUrls": {
                       "type": "array",
@@ -533,7 +537,8 @@
                     },
                     "network": {
                       "$ref": "#/definitions/bridge_operation/anyOf/4/properties/data/properties/network",
-                      "description": "Target chain (defaults to Ethereum mainnet)"
+                      "default": "mainnet",
+                      "description": "Target chain (defaults to Ethereum mainnet when omitted — EvmChainSchema carries .default(\"mainnet\"))"
                     },
                     "rpcUrls": {
                       "type": "array",
@@ -562,7 +567,8 @@
                     },
                     "network": {
                       "$ref": "#/definitions/bridge_operation/anyOf/4/properties/data/properties/network",
-                      "description": "Target chain (defaults to Ethereum mainnet)"
+                      "default": "mainnet",
+                      "description": "Target chain (defaults to Ethereum mainnet when omitted — EvmChainSchema carries .default(\"mainnet\"))"
                     },
                     "rpcUrls": {
                       "type": "array",
@@ -591,7 +597,8 @@
                     },
                     "network": {
                       "$ref": "#/definitions/bridge_operation/anyOf/4/properties/data/properties/network",
-                      "description": "Target chain (defaults to Ethereum mainnet)"
+                      "default": "mainnet",
+                      "description": "Target chain (defaults to Ethereum mainnet when omitted — EvmChainSchema carries .default(\"mainnet\"))"
                     },
                     "rpcUrls": {
                       "type": "array",

package/dist/schemas/guard2file.schema.json

@@ -22,6 +22,7 @@
             "json",
             "markdown"
           ],
+          "default": "json",
           "description": "Output format: 'json' (default) or 'markdown'"
         },
         "env": {
@@ -77,6 +78,7 @@
             },
             "schema_strict_mode": {
               "type": "boolean",
+              "default": false,
               "description": "When true, schema incompatibility returns an error instead of a warning. Default: false (warn mode)."
             },
             "dry_run": {

package/dist/schemas/index.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "WoWok MCP Schema Index",
   "description": "Index of all available JSON schemas for WoWok MCP tools",
-  "generatedAt": "2026-07-26T22:55:28.022Z",
+  "generatedAt": "2026-08-01T01:54:35.836Z",
   "tools": [
     {
       "name": "onchain_operations",

package/dist/schemas/machineNode2file.schema.json

@@ -22,6 +22,7 @@
             "json",
             "markdown"
           ],
+          "default": "json",
           "description": "Output format: 'json' (default) or 'markdown'"
         },
         "env": {
@@ -77,6 +78,7 @@
             },
             "schema_strict_mode": {
               "type": "boolean",
+              "default": false,
               "description": "When true, schema incompatibility returns an error instead of a warning. Default: false (warn mode)."
             },
             "dry_run": {

package/dist/schemas/messenger_operation.schema.json

@@ -1423,7 +1423,7 @@
           "additionalProperties": false
         }
       ],
-      "description": "Messenger operation input schema"
+      "description": "Messenger operation input schema. PREREQUISITE: an account must ENABLE messenger before sending/receiving. There is NO 'enable' operation in this tool — enable via account_operation {messenger: {enabled: true, name_or_account: '<account>'}}, or implicitly via send_message/send_file with options.enable_messenger: true. Use proof_message to anchor a message's WTS proof on-chain (creates a Proof object consumable by Guards via proof.signer/proof.time queries)."
     }
   }
 }

package/dist/schemas/onchain_events.output.json

@@ -219,7 +219,7 @@
                               "number",
                               "string"
                             ],
-                            "description": "A coin/balance amount in the smallest on-chain unit (u64). Accepts a JS number OR a numeric string. PRECISION RULE: for values exceeding 2^53 (e.g. token amounts with 18 decimals), ALWAYS pass a numeric STRING (e.g. \"1000000000000000000\") to preserve precision — JS numbers lose precision above 2^53. UNIT: this is the smallest unit, NOT the display unit. For SUI: 1 SUI = 10^9 MIST, so 10 SUI = 10000000000. For custom tokens: use the token's native smallest unit (decimals from coin metadata). Examples: 10000000000 (10 SUI), \"1000000000000000000\" (1 token with 18 decimals), 500 (500 units of a token with 0 decimals). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
+                            "description": "A coin/balance amount. Accepts three formats: (1) DISPLAY FORMAT with token symbol: \"2.5WOW\", \"10USDC\", \"0.05SUI\" — auto-converted to smallest units via the Fund Processing Layer (token precision resolved from official registry → cache → on-chain). The symbol MUST match the token's type_parameter. (2) SMALLEST UNIT (numeric string): \"10000000000\" — used as-is, no conversion. (3) SMALLEST UNIT (number): 10000000000 — used as-is (loses precision above 2^53). PRECISION RULE: for values exceeding 2^53, ALWAYS use format (1) or (2) — JS numbers lose precision. Default token: WOW (9 decimals, 1 WOW = 10^9 MIST). For custom tokens: use display format with the token's symbol, or pass smallest units directly. MONEY CONFIRMATION: all monetary fields trigger user confirmation via the Fund Processing Layer. If multiple tokens share a symbol (ambiguity), specify the full type string in type_parameter. Examples: \"2.5WOW\" (display → 2500000000), 10000000000 (number, smallest unit), \"50000000000\" (string, smallest unit). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
                           }
                         },
                         "required": [