@wowok/agent-mcp 2.2.16 → 2.2.18

package/README.md

@@ -48,6 +48,8 @@ Skills provide structured guidance for AI assistants:
 | `wowok-machine` | 🏪 Provider | Workflow design — state machines, node definitions, progress tracking |
 | `wowok-arbitrator` | ⚖️ Arbitrator | Arbitration service — dispute resolution, voting organization, fee management |
 | `wowok-guard` | 🛠️ Shared | Guard design mastery — programmable trust rules, multi-signature authorization |
+| `wowok-messenger` | 🛠️ Shared | Encrypted messaging — E2E communication, WTS evidence, conversation management |
+| `wowok-output` | 🛠️ Shared | Output processing — post-process responses for human-readable presentation |
 | `wowok-tools` | 🛠️ Shared | MCP tool usage mastery — 13+ tools, parameter formats, schema references |
 | `wowok-safety` | 🛠️ Shared | Safety protocol — dry-run validation, user confirmation checkpoints |
 

package/dist/index.js

@@ -10,6 +10,10 @@ import { CallService, CallMachine, CallProgress, CallPermission, CallGuard, Call
 import { areSchemasAvailable, getSchemaIndex, processSchemaQuery, } from "./schema-query/index.js";
 const SERVER_DESCRIPTION = `WoWok MCP Server - Making It Easy for AI Agents to Communicate, Collaborate, Trade, and Trust.
 
+## CRITICAL: Schema Discovery Rule
+
+When the current context does not contain a tool's input/output schema, or when you are uncertain whether the schema you have is complete and up-to-date, you MUST query it first before calling the tool. Use schema_query for operational tool schemas or wowok_buildin_info for protocol constants and reference data. Never guess schema parameters, query instruction IDs, or type codes — always retrieve them from the live server.
+
 ## Token System Overview
 
 ### Default Platform Token: WOW
@@ -87,7 +91,7 @@ Token amounts are HIGHLY SENSITIVE. Always:
 | Sign WIP file | wip_file (sign) | account_operation (signData) |
 | Verify WIP file integrity | wip_file (verify) | query_toolkit |
 | Send encrypted file via messenger | messenger_operation (send_file) | wip_file |
-| Generate witness timestamp (WTS) | messenger_operation (generate_wts) | wip_file |
+| Generate Witness Timestamped Sequence (WTS) | messenger_operation (generate_wts) | wip_file |
 | Query protocol constants | wowok_buildin_info | query_toolkit |
 | Query tool schemas | schema_query | wowok_buildin_info |
 
@@ -1351,7 +1355,7 @@ async function main() {
         _meta: createToolMeta("operation", ["info", "local", "private", "data-management", "off-chain"]),
     }, handleInfoOperation);
     server.registerTool("wip_file", {
-        title: "🤝 Witness Information Promise File Operations",
+        title: "🤝 Witness Immutable Promise File Operations",
         description: "generate (create WIP files from markdown and images), verify (integrity check), sign (add signatures), or wip2html (convert to HTML).",
         inputSchema: WipOperationsSchema,
         outputSchema: z.object({
@@ -1444,7 +1448,14 @@ async function main() {
     }, handleWowokInfo);
     server.registerTool("schema_query", {
         title: "📋 Schema Query",
-        description: "Query JSON schemas for all WoWok MCP tools and operations. Use this tool to understand the exact structure required for calling other tools. Returns complete JSON Schema definitions with all properties, types, and descriptions. This is the authoritative source for tool schemas.",
+        description: "Look up JSON Schemas for WoWok MCP tools and on-chain operations. " +
+            "This is the authoritative reference for exact parameter structures, types, and required fields. " +
+            "Always check the schema before calling an unfamiliar tool.\n\n" +
+            "Actions:\n" +
+            "  'list' - Show all available schemas (tools + on-chain operations). Start here to discover what exists.\n" +
+            "  'get' - Fetch the full JSON Schema by name (e.g. 'onchain_operations'). Use with the 'name' param.\n" +
+            "  'search' - Find schemas by keyword, matching name/title/description. Use with the 'query' param.\n" +
+            "  'list_operations' - Show only on-chain operation schemas (prefixed 'onchain_operations_'). Narrower than 'list'.",
         inputSchema: z.object({
             action: z.enum(["list", "get", "search", "list_operations"])
                 .describe("Action to perform: 'list' to see all available schemas, 'get' to retrieve a specific schema, 'search' to find schemas by keyword, 'list_operations' to list all on-chain operations"),
@@ -1472,9 +1483,23 @@ async function main() {
         if (response.success && data) {
             switch (args.action) {
                 case "list":
+                    if (Array.isArray(data) && data.length > 0) {
+                        textContent += "\n\nAll available schemas:\n";
+                        for (const item of data) {
+                            textContent += `\n  • ${item.name}`;
+                            if (item.title) {
+                                textContent += ` - ${item.title}`;
+                            }
+                            if (item.description) {
+                                textContent += `\n    ${item.description.slice(0, 100)}...`;
+                            }
+                            textContent += "\n";
+                        }
+                    }
+                    break;
                 case "list_operations":
                     if (Array.isArray(data) && data.length > 0) {
-                        textContent += "\n\nAvailable schemas:\n";
+                        textContent += "\n\nOn-chain operation schemas:\n";
                         for (const item of data) {
                             textContent += `\n  • ${item.name}`;
                             if (item.title) {
@@ -1503,9 +1528,15 @@ async function main() {
                             if (item.title) {
                                 textContent += ` - ${item.title}`;
                             }
+                            if (item.description) {
+                                textContent += `\n    ${item.description.slice(0, 100)}...`;
+                            }
                             textContent += "\n";
                         }
                     }
+                    else {
+                        textContent += "\n\nNo schemas found. Try 'list' to browse all available schemas, or use a broader search term.";
+                    }
                     break;
             }
         }

package/dist/schema/query/index.js

@@ -3,7 +3,7 @@ import { TokenTypeInfoSchema, QueryLocalMarkListResultSchema, QueryAccountListRe
 import { AccountOrMark_AddressSchema, BalanceTypeSchema, EntrypointSchema, GuardIdentifierSchema, GuardTableItemSchema, NameOrAddressSchema, ObjectBaseSchema, ObjectTypeSchema, QueryIdSchema, SupportedValueSchema, ValueTypeSchema, QueryReceivedResultSchema, LongNameSchema, DescriptionSchema } from "../common/index.js";
 import { isValidPermissionIndex } from '../utils/permission-index-utils.js';
 import { isValidGuardQueryId, isValidGuardQueryIdOrName } from '../utils/guard-query-utils.js';
-import { isWitnessType, } from "@wowok/wowok";
+import { ENTITY_LINKER_ADDRESS, ENTITY_REGISTRAR_ADDRESS, isWitnessType, } from "@wowok/wowok";
 import { DiscountType as WDiscountType } from "@wowok/wowok";
 import { QueryEnvSchema } from "../common/index.js";
 const MAX_MULTI_OPERANDS = 8;
@@ -402,7 +402,7 @@ export const WitnessTypeSchema = z.number()
     .int()
     .refine(isWitnessType, {
     message: 'Invalid WitnessType value',
-});
+}).describe("When specified, the query retrieves data from the associated (witness) object instead of the queried object itself. This enables cross-object queries within Guard validation logic. Available WitnessTypes and their use cases:\n\n- TypeOrderProgress (100): Query an Order's associated Progress object. Use case: Check if order has reached a specific workflow node (e.g., 'complete') before allowing reward claims.\n- TypeOrderMachine (101): Query an Order's associated Machine (workflow definition). Use case: Verify the workflow structure or check node configurations.\n- TypeOrderService (102): Query an Order's parent Service object. Use case: Validate the service offering details or check service-level configurations.\n- TypeProgressMachine (103): Query a Progress's associated Machine. Use case: Access workflow definition from a Progress context.\n- TypeArbOrder (104): Query an Arb's associated Order. Use case: In arbitration voting guards, verify order details like payment amount or service ID.\n- TypeArbArbitration (105): Query an Arb's parent Arbitration service. Use case: Access arbitration configuration or fee settings from within an Arb case.\n- TypeArbProgress (106): Query an Arb's associated Progress. Use case: Check order workflow state during arbitration validation.\n- TypeArbMachine (107): Query an Arb's associated Machine. Use case: Access workflow definition for dispute context analysis.\n- TypeArbService (108): Query an Arb's associated Service. Use case: Verify service terms or compensation fund status during arbitration.\n\nExample: To validate that an order has reached the 'complete' node, query the Order with convert_witness=TypeOrderProgress and check the Progress's current_node field.");
 export const GuardQueryIdSchema = z.number().int().min(0).refine((id) => isValidGuardQueryId(id), { message: "Invalid guard query ID. ID not found in GUARDQUERY array." }).describe("ID of the data query instruction for the Object.");
 export const GuardNodeSchema = z.lazy(() => z.discriminatedUnion('type', [
     z.object({
@@ -417,10 +417,10 @@ export const GuardNodeSchema = z.lazy(() => z.discriminatedUnion('type', [
         ]).describe("ID or name of the wowok object data query instruction. Can be a numeric ID (e.g., 1001) or a name string (e.g., 'permission.description'). Name matching is case-insensitive."),
         object: z.object({
             identifier: GuardIdentifierSchema,
-            convert_witness: WitnessTypeSchema.optional().describe("Optional. When specified, the query retrieves data from the associated object instead of the object itself. For example, querying an order with convert_witness=TypeOrderProgress retrieves the associated Progress object data."),
+            convert_witness: WitnessTypeSchema.optional(),
         }).strict().describe("The object to query from the Guard table."),
         parameters: z.array(GuardNodeSchema).describe("Parameters required by the query (must match the query's expected parameters type)."),
-    }).strict().describe("Returns the result of executing a data query instruction on the specified object. The return type depends on the query being executed. SPECIAL NOTE for EntityLinker/EntityRegistrar queries: Use system addresses in the Guard table - ENTITY_LINKER_ADDRESS (0xaaa) for EntityLinker queries, ENTITY_REGISTRAR_ADDRESS (0xaab) for EntityRegistrar queries."),
+    }).strict().describe(`Returns the result of executing a data query instruction on the specified object. The return type depends on the query being executed. SPECIAL NOTE for EntityLinker/EntityRegistrar queries: Use system addresses in the Guard table -${ENTITY_LINKER_ADDRESS} for EntityLinker queries, ${ENTITY_REGISTRAR_ADDRESS} for EntityRegistrar queries.`),
     z.object({
         type: z.literal('logic_as_u256_greater_or_equal'),
         nodes: z.array(GuardNodeSchema),

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-05-20T13:29:28.773Z",
+  "generatedAt": "2026-05-22T02:20:38.513Z",
   "tools": [
     {
       "name": "onchain_operations",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/agent-mcp",
-  "version": "2.2.16",
+  "version": "2.2.18",
   "description": "Making It Easy for AI Agents to Communicate, Collaborate, Trade, and Trust.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",