@wowok/agent-mcp 2.6.0 → 2.6.3

package/dist/schemas/schema_query.output.json

@@ -43,17 +43,80 @@
               },
               "description": "List of schema summaries (list/search/list_operations)."
             },
+            {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "file": {
+                    "type": "string",
+                    "description": "Example file name (e.g. 'rental-ziroom-service-create.json')."
+                  },
+                  "title": {
+                    "type": "string",
+                    "description": "Human-readable title from the example metadata."
+                  },
+                  "description": {
+                    "type": "string",
+                    "description": "Longer description from the example metadata."
+                  },
+                  "tags": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Tags from the example metadata."
+                  },
+                  "industry": {
+                    "type": "string",
+                    "description": "Industry category (e.g. 'rental', 'retail', 'general')."
+                  },
+                  "operation_type": {
+                    "type": "string",
+                    "description": "Operation type (e.g. 'service', 'machine', 'guard', 'permission')."
+                  },
+                  "verified": {
+                    "type": "boolean",
+                    "description": "Whether the example is marked as verified."
+                  },
+                  "score": {
+                    "type": "number",
+                    "description": "Relevance score — number of fields that matched the query (0-5)."
+                  },
+                  "matched_fields": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "List of fields that matched the query."
+                  }
+                },
+                "required": [
+                  "file",
+                  "title",
+                  "description",
+                  "tags",
+                  "industry",
+                  "operation_type",
+                  "verified",
+                  "score",
+                  "matched_fields"
+                ],
+                "additionalProperties": false
+              },
+              "description": "List of matching examples (search_examples)."
+            },
             {
               "type": "object",
               "additionalProperties": {},
-              "description": "JSON Schema object (get/get_output)."
+              "description": "JSON Schema object (get/get_output/get_field) or Guard template data."
             },
             {
               "type": "null",
-              "description": "No data — lookup failed or returned nothing."
+              "description": "No data — lookup failed or returned nothing, or data was written to output_file."
             }
           ],
-          "description": "Response data — array of schema summaries for list-like actions, JSON Schema object for get/get_output, null on failure."
+          "description": "Response data — array of schema summaries for list-like actions, array of example results for search_examples, JSON Schema object for get/get_output/get_field, Guard template data for get_guard_templates, null on failure or when output_file is used."
         },
         "message": {
           "type": "string",
@@ -65,6 +128,10 @@
             "type": "string"
           },
           "description": "Suggested next steps or alternatives"
+        },
+        "output_file_path": {
+          "type": "string",
+          "description": "When output_file is used, contains the absolute file path where data was written."
         }
       },
       "required": [

package/dist/schemas/schema_query.schema.json

@@ -15,17 +15,32 @@
             "get",
             "get_output",
             "search",
-            "list_operations"
+            "list_operations",
+            "get_guard_templates",
+            "get_field",
+            "search_examples"
           ],
-          "description": "Action to perform: 'list' to see all available schemas, 'get' to retrieve a specific input schema, 'get_output' to retrieve a tool's output schema, 'search' to find schemas by keyword, 'list_operations' to list all on-chain operations"
+          "description": "Action to perform: 'list' (all schemas), 'get' (specific input schema), 'get_output' (tool output schema), 'get_field' (field-path query e.g. field_path='data.node'), 'search' (by keyword), 'list_operations' (on-chain operations), 'get_guard_templates' (Guard creation templates + best practices), 'search_examples' (search verified example files by keyword — matches title, description, tags, operation_type, industry)."
         },
         "name": {
           "type": "string",
-          "description": "Schema/tool name for 'get'/'get_output' action (e.g., 'onchain_operations', 'account_operation', 'onchain_operations_permission')"
+          "description": "Schema/tool name for 'get'/'get_output'/'get_field' action (e.g., 'onchain_operations', 'onchain_operations_machine')."
         },
         "query": {
           "type": "string",
           "description": "Search query for 'search' action"
+        },
+        "field_path": {
+          "type": "string",
+          "description": "Dot-separated field path for 'get_field' action (e.g. 'data.node', 'data.node.nodes.0.pairs'). Navigates schema.properties.* and schema.items.*."
+        },
+        "template": {
+          "type": "string",
+          "description": "Guard template name for 'get_guard_templates' action. Omit to list all available templates. Available: signer_verification, progress_node_check, order_owner_verification, service_belonging_check, reward_not_claimed, combined_reward_guard."
+        },
+        "output_file": {
+          "type": "string",
+          "description": "When set, writes the response data to this file path (relative to cwd) and returns the path instead of inline data. Use for large schemas that would be truncated. Prefer workspace paths like '.trae/tmp/schema.json' so the Read tool can access them."
         }
       },
       "required": [

package/dist/schemas/wowok_buildin_info.output.json

@@ -69,19 +69,23 @@
                     "properties": {
                       "index": {
                         "type": "number",
-                        "description": "Permission index"
+                        "description": "Permission index (e.g. 315 for service.compensation_fund_deposit)"
                       },
                       "name": {
                         "type": "string",
-                        "description": "Name"
+                        "description": "Permission name (e.g. \"service.compensation_fund_deposit\")"
                       },
                       "description": {
                         "type": "string",
-                        "description": "Description"
+                        "description": "Description of what this permission allows"
                       },
                       "object_type": {
                         "type": "string",
-                        "description": "Object type"
+                        "description": "Object type this permission belongs to (e.g. \"Service\", \"Arbitration\")"
+                      },
+                      "operation": {
+                        "type": "string",
+                        "description": "The SDK/MCP operation field name that triggers this permission check (e.g. \"compensation_fund_add\", \"publish\", \"pause\"). Undefined for permissions with no direct Call*_Data field (e.g. \"*.new\" permissions). Use this to answer: \"What permission does operation X require?\" by filtering with {operation: \"compensation_fund_add\"}."
                       }
                     },
                     "required": [
@@ -91,9 +95,78 @@
                       "object_type"
                     ],
                     "additionalProperties": false,
-                    "description": "Permission info type"
+                    "description": "Permission info type — includes the operation field name that maps to this permission, so AI can look up required permissions by operation name."
+                  },
+                  "description": "Built-in permissions result. Each item includes an optional \"operation\" field mapping to the SDK/MCP field name that triggers this permission."
+                }
+              },
+              "required": [
+                "info",
+                "result"
+              ],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "info": {
+                  "type": "string",
+                  "const": "common mistakes"
+                },
+                "result": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "object_type": {
+                        "type": "string",
+                        "description": "The object type this mistake applies to (e.g. \"Service\", \"Arbitration\")"
+                      },
+                      "operation": {
+                        "type": "string",
+                        "description": "The operation field name this mistake applies to (e.g. \"compensation_fund_add\", \"voting_deadline\")"
+                      },
+                      "category": {
+                        "type": "string",
+                        "enum": [
+                          "field_name",
+                          "unit",
+                          "value_range",
+                          "workflow",
+                          "timing"
+                        ],
+                        "description": "Category of the mistake: field_name (wrong field name), unit (wrong unit like seconds vs ms), value_range (wrong expected value), workflow (wrong operation order), timing (wrong time constraint)"
+                      },
+                      "mistake": {
+                        "type": "string",
+                        "description": "Short description of the mistake"
+                      },
+                      "correct_usage": {
+                        "type": "string",
+                        "description": "The correct usage pattern"
+                      },
+                      "wrong_example": {
+                        "type": "string",
+                        "description": "Example of the wrong usage"
+                      },
+                      "correct_example": {
+                        "type": "string",
+                        "description": "Example of the correct usage"
+                      }
+                    },
+                    "required": [
+                      "object_type",
+                      "operation",
+                      "category",
+                      "mistake",
+                      "correct_usage",
+                      "wrong_example",
+                      "correct_example"
+                    ],
+                    "additionalProperties": false,
+                    "description": "A known common mistake for an on-chain operation. Use this to proactively warn users before they submit a transaction."
                   },
-                  "description": "Built-in permissions result"
+                  "description": "Common mistakes result. Each item documents a known pitfall (wrong field name, wrong unit, wrong workflow order, etc.) with wrong/correct examples."
                 }
               },
               "required": [
@@ -486,12 +559,12 @@
                       "parameters": {
                         "type": "array",
                         "items": {
-                          "$ref": "#/definitions/wowok_buildin_info/properties/result/anyOf/2/properties/result/items/properties/returnType"
+                          "$ref": "#/definitions/wowok_buildin_info/properties/result/anyOf/3/properties/result/items/properties/returnType"
                         },
                         "description": "Parameters for guard query"
                       },
                       "return": {
-                        "$ref": "#/definitions/wowok_buildin_info/properties/result/anyOf/2/properties/result/items/properties/returnType",
+                        "$ref": "#/definitions/wowok_buildin_info/properties/result/anyOf/3/properties/result/items/properties/returnType",
                         "description": "Return type for guard query"
                       },
                       "parameters_description": {

package/dist/schemas/wowok_buildin_info.schema.json

@@ -80,17 +80,61 @@
                 "description": {
                   "type": "string",
                   "description": "Description filter"
+                },
+                "operation": {
+                  "type": "string",
+                  "description": "Filter by SDK/MCP operation field name (e.g. \"compensation_fund_add\"). Returns only permissions triggered by this operation. Use this to answer: \"What permission does operation X require?\""
+                }
+              },
+              "additionalProperties": false,
+              "description": "Filter for built-in permissions. Use operation:\"compensation_fund_add\" to find which permission a specific operation requires."
+            }
+          },
+          "required": [
+            "info"
+          ],
+          "additionalProperties": false,
+          "description": "Built-in permissions query. Each permission includes an optional \"operation\" field that maps to the SDK/MCP Call*_Data field name triggering it. Use this to answer: \"What permission does operation X require?\" — e.g. filter operation:\"compensation_fund_add\" returns permission index 315 (service.compensation_fund_deposit)."
+        },
+        {
+          "type": "object",
+          "properties": {
+            "info": {
+              "type": "string",
+              "const": "common mistakes"
+            },
+            "filter": {
+              "type": "object",
+              "properties": {
+                "object_type": {
+                  "type": "string",
+                  "description": "Filter by object type (e.g. \"Service\")"
+                },
+                "operation": {
+                  "type": "string",
+                  "description": "Filter by operation field name (e.g. \"compensation_fund_add\")"
+                },
+                "category": {
+                  "type": "string",
+                  "enum": [
+                    "field_name",
+                    "unit",
+                    "value_range",
+                    "workflow",
+                    "timing"
+                  ],
+                  "description": "Filter by category (e.g. \"field_name\" for field-name mistakes, \"unit\" for unit mistakes)"
                 }
               },
               "additionalProperties": false,
-              "description": "Filter for built-in permissions"
+              "description": "Filter for common mistakes. Use operation:\"compensation_fund_add\" to find mistakes for a specific operation, or category:\"field_name\" for all field-name mistakes."
             }
           },
           "required": [
             "info"
           ],
           "additionalProperties": false,
-          "description": "Built-in permissions query"
+          "description": "Common mistakes query. Returns known field-name, unit, value-range, workflow, and timing pitfalls for on-chain operations. Use this to proactively warn users before submitting a transaction. Example: query operation:\"compensation_fund_add\" to learn about the {amount} vs {balance} field name mistake."
         },
         {
           "type": "object",

package/dist/tools/handlers/local.js

@@ -1,4 +1,5 @@
 import { wrapLocalHandler } from "../shared.js";
+import { withFaucetRetry } from "../retry.js";
 import { AccountOperationSchema, LocalMarkOperationSchema, LocalInfoOperationSchema, } from "../../schema/index.js";
 import { account_operation, local_mark_operation, local_info_operation, } from "@wowok/wowok";
 function deriveOpType(prefix, validated) {
@@ -11,7 +12,7 @@ function deriveOpType(prefix, validated) {
 }
 export const handleAccountOperation = wrapLocalHandler({
     schema: AccountOperationSchema,
-    operationFn: account_operation,
+    operationFn: withFaucetRetry(account_operation),
     parseLabel: "account_operation input",
     buildContext: (validated) => ({
         operation_type: deriveOpType("account", validated),
@@ -22,10 +23,24 @@ export const handleMarkOperation = wrapLocalHandler({
     schema: LocalMarkOperationSchema,
     operationFn: local_mark_operation,
     parseLabel: "local_mark_operation input",
-    buildContext: (validated) => ({
-        operation_type: deriveOpType("mark", validated),
-        data: validated,
-    }),
+    buildContext: (validated) => {
+        const ctx = {
+            operation_type: deriveOpType("mark", validated),
+            data: validated,
+        };
+        const v = validated;
+        if (v.add && Array.isArray(v.add.data) && v.add.data.length > 0) {
+            ctx.pre_warnings = [
+                "Cross-network consistency (FIX-011): LocalMark names are scoped per network. " +
+                    "When creating marks for the same logical object on different networks " +
+                    "(e.g. testnet and mainnet), use the SAME name value to keep name-based " +
+                    "references portable. Before creating a mark on mainnet, consider querying " +
+                    "testnet via query_local with network='testnet' to check for an existing " +
+                    "same-named mark and replicate it.",
+            ];
+        }
+        return ctx;
+    },
 });
 export const handleInfoOperation = wrapLocalHandler({
     schema: LocalInfoOperationSchema,