@wowok/agent-mcp 2.2.13 → 2.2.15

package/README.md

@@ -39,18 +39,26 @@ Skills provide structured guidance for AI assistants:
 - **Tool usage failures** — Correct parameter formats, tool selection, error recovery
 - **Safety & authorization** — User confirmation for important operations
 
-#### Available Skills
-
-| Skill | Purpose |
-|-------|---------|
-| `wowok-build` | Complex system building (Service + Machine + Guard + Allocation + Reward) |
-| `wowok-guard` | Guard design mastery (programmable trust rules) |
-| `wowok-tools` | MCP tool usage mastery (13 tools, common pitfalls) |
-| `wowok-safety` | Safety & authorization protocol (dry-run → confirm → execute) |
-| `wowok-machine` | Machine workflow design (state machines, progress tracking) |
-| `wowok-order` | Order lifecycle management (payment, allocation, arbitration) |
+#### Available Skills (Organized by Role)
+
+| Skill | Role | Purpose |
+|-------|------|---------|
+| `wowok-order` | 👤 Customer | Order lifecycle — place orders, track progress, submit disputes, claim compensation |
+| `wowok-provider` | 🏪 Provider | Service provider guide — create Service, design Machine, configure Allocators |
+| `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-tools` | 🛠️ Shared | MCP tool usage mastery — 13+ tools, parameter formats, schema references |
+| `wowok-safety` | 🛠️ Shared | Safety protocol — dry-run validation, user confirmation checkpoints |
+
+#### Role-Based Skill Selection
+
+- **Use `wowok-order`** when user acts as a customer/buyer placing orders
+- **Use `wowok-provider`** + `wowok-machine` when user is a merchant/service provider
+- **Use `wowok-arbitrator`** when user operates dispute resolution services
+- **Use `wowok-tools`** + `wowok-safety`** (always loaded) for all roles
+- **Use `wowok-guard`** when designing complex validation rules
 
 #### Using Skills
 
 Once installed, Claude Code will automatically use these skills when working with WoWok tools.
-

package/dist/index.js

@@ -7,7 +7,7 @@ import { resolve } from "path";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
 import { CallService_DataSchema, CallMachine_DataSchema, MachineNode2File_InputSchema, MachineNode2File_OutputWrappedSchema, CallProgress_DataSchema, CallPermission_DataSchema, CallGuard_DataSchema, Guard2File_InputSchema, Guard2File_OutputWrappedSchema, CallArbitration_DataSchema, CallRepository_DataSchema, CallContact_DataSchema, CallTreasury_DataSchema, CallReward_DataSchema, CallAllocation_DataSchema, CallPersonal_DataSchema, CallPayment_DataSchema, CallDemand_DataSchema, CallOrder_DataSchema, CallEnvSchema, SubmissionCallSchema, strictParse, CallOutputSchema, handleCallResult, createServerConfig, createCapabilitiesConfig, createToolMeta, transformSubmission, getEnvConfig, WipGenerationOptionsSchema, WipToHtmlOptionsSchema, TokenDataFilterSchema, LocalInfoFilterSchema, LocalMarkFilterSchema, AccountFilterSchema, TokenTypeSchema, OnchainEventsInputSchema, OnchainEventsResultSchema, ProtocolInfoQuerySchema, ProtocolInfoResultSchema, TableAnswerSchema, TableItem_RepositoryDataSchema, TableItem_PermissionPermSchema, TableItem_EntityRegistrarSchema, TableItem_EntityLinkerSchema, TableItem_RewardRecordSchema, TableItem_DemandPresenterSchema, TableItem_TreasuryHistorySchema, TableItem_MachineNodeSchema, TableItem_ProgressHistorySchema, TableItem_AddressMarkSchema, NameOrAddressSchema, ObjectBaseSchema, AccountOrMark_AddressSchema, AccountOrMark_AddressAISchema, EntrypointSchema, AccountOperationOutputWrappedSchema, LocalMarkOperationOutputWrappedSchema, LocalInfoOperationOutputWrappedSchema, WipOperationOutputSchema, MessengerOperationOutputSchema, AccountOperationSchema, LocalMarkOperationSchema, LocalInfoOperationSchema, parseMachineNodesFromText, formatNodeErrors as formatMachineNodeErrors, MessengerOperationInputSchema, } from "./schema/index.js";
 import { CallService, CallMachine, CallProgress, CallPermission, CallGuard, CallArbitration, CallRepository, CallContact, CallTreasury, CallReward, CallAllocation, CallPersonal, CallPayment, CallDemand, CallOrder, gen_passport, guard2file, parseGuardFile, formatGuardParseErrors, machineNode2file, generateNodeComments, generate_wip, verify_wip, sign_wip, wip2html, account_operation, local_mark_operation, local_info_operation, watch_conversations, send_message, send_file, watch_messages, extract_zip_messages, generate_wts, verify_wts, sign_wts, wts2html, proof_message, mark_messages_as_viewed, mark_conversation_as_viewed, query_local_mark_list, query_account_list, query_local_info_list, query_local_token_list, query_account, GetLocalNamesByAddresses, query_personal, query_objects, query_table, query_tableItem, queryProtocolInfo, query_received, queryTableItem_RepositoryData, queryTableItem_PermissionPerm, queryTableItem_RewardRecord, queryTableItem_DemandPresenter, queryTableItem_TreasuryHistory, queryTableItem_MachineNode, queryTableItem_ProgressHistory, queryTableItem_AddressMark, queryTableItem_EntityRegistrar, queryTableItem_EntityLinker, query_events, blacklist, friendslist, guardlist, settings, AmountType, } from "@wowok/wowok";
-import { loadAllDocuments, isDocumentationAvailable, getDocStats, processLearnRequest, } from "./docs/index.js";
+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.
 
 ## Token System Overview
@@ -89,7 +89,7 @@ Token amounts are HIGHLY SENSITIVE. Always:
 | Send encrypted file via messenger | messenger_operation (send_file) | wip_file |
 | Generate witness timestamp (WTS) | messenger_operation (generate_wts) | wip_file |
 | Query protocol constants | wowok_buildin_info | query_toolkit |
-| Get documentation URL | documents_and_learn | wowok_buildin_info |
+| Query tool schemas | schema_query | wowok_buildin_info |
 
 ## Local vs On-chain Operations
 
@@ -107,7 +107,7 @@ Token amounts are HIGHLY SENSITIVE. Always:
 - query_toolkit
 - onchain_events
 - wowok_buildin_info
-- documents_and_learn
+- schema_query
 - guard2file
 - machineNode2file
 `;
@@ -1306,19 +1306,14 @@ async function handleMachineNode2File(args) {
 }
 export { OnchainOperationsSchema, WipOperationsSchema, WatchQueryOperationsSchema, AccountOperationSchema, LocalMarkOperationSchema, LocalInfoOperationSchema, ProtocolInfoQuerySchema, CallOutputSchema, MessengerOperationInputSchema, MessengerOperationOutputSchema };
 async function main() {
-    let docIndex = null;
-    if (isDocumentationAvailable()) {
-        try {
-            docIndex = loadAllDocuments();
-            const stats = getDocStats();
-            console.error(`Documentation loaded: ${stats.total} files (${stats.skills} skills, ${stats.examples} examples)`);
-        }
-        catch (error) {
-            console.error("Failed to load documentation:", error);
+    if (areSchemasAvailable()) {
+        const index = getSchemaIndex();
+        if (index) {
+            console.error(`Schema system ready: ${index.tools?.length || 0} tools, ${index.operations?.length || 0} operations`);
         }
     }
     else {
-        console.error("Documentation not available. Please ensure docs/skills and docs/examples directories exist.");
+        console.error("Schema files not available. Run 'npm run generate:schemas' to generate them.");
     }
     server.registerTool("onchain_operations", {
         title: "⛓️ On-chain Operations",
@@ -1444,119 +1439,68 @@ async function main() {
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
         _meta: createToolMeta("WoWok info", ["build-in", "constants", "permissions", "guard", "network", "value-types"]),
     }, handleWowokInfo);
-    server.registerTool("documents_and_learn", {
-        title: "📚 Documents and Learn",
-        description: "Access WoWok documentation and learning resources locally. Search documentation, get operation schemas, learn from examples, and read guides without external network access.",
+    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.",
         inputSchema: z.object({
-            action: z.enum(["search", "get_schema", "learn_example", "guide", "list_operations", "list_examples"])
-                .describe("Action to perform: 'search' for keywords, 'get_schema' for operation/tool schemas, 'learn_example' for case studies, 'guide' for documentation, 'list_operations' or 'list_examples' to see available resources"),
-            topic: z.string().optional().describe("Topic for guide or schema lookup (e.g., 'guard', 'service', 'WOWOK', '_index')"),
-            query: z.string().optional().describe("Search query for finding relevant documentation"),
-            example: z.string().optional().describe("Example name to learn from (e.g., 'MyShop', 'Travel', 'Insurance')"),
-            operationType: z.string().optional().describe("Operation type for schema lookup (e.g., 'service', 'guard', 'machine', 'order')"),
-            toolName: z.string().optional().describe("Tool name for schema lookup (e.g., 'query_toolkit', 'messenger_operation')"),
+            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"),
+            name: z.string().optional().describe("Schema name for 'get' action (e.g., 'onchain_operations', 'account_operation', 'onchain_operations_permission')"),
+            query: z.string().optional().describe("Search query for 'search' action"),
         }),
         outputSchema: z.object({
             success: z.boolean().describe("Whether the request was successful"),
             action: z.string().describe("The action that was performed"),
-            data: z.any().describe("Response data (varies by action)"),
+            data: z.any().describe("Response data - JSON Schema object for 'get', array of schema info for 'list'/'search'/'list_operations'"),
             message: z.string().describe("Human-readable message describing the result"),
             suggestions: z.array(z.string()).optional().describe("Suggested next steps or alternatives"),
         }),
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-        _meta: createToolMeta("documentation", ["docs", "learn", "tutorial", "guide", "help", "reference", "schema", "example"]),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        _meta: createToolMeta("schema", ["schema", "json-schema", "types", "structure", "validation", "reference"]),
     }, async (args) => {
-        if (!docIndex) {
-            return {
-                content: [{
-                        type: "text",
-                        text: "Documentation system is not available. Please ensure docs/skills and docs/examples are copied to the package.",
-                    }],
-                structuredContent: {
-                    success: false,
-                    action: args.action,
-                    data: null,
-                    message: "Documentation system unavailable",
-                    suggestions: ["Check that docs/ directory exists", "Ensure docs/skills and docs/examples subdirectories are present"],
-                },
-            };
-        }
         const request = {
             action: args.action,
-            topic: args.topic,
+            name: args.name,
             query: args.query,
-            example: args.example,
-            operationType: args.operationType,
-            toolName: args.toolName,
         };
-        const response = processLearnRequest(docIndex.index, request);
+        const response = processSchemaQuery(request);
         let textContent = response.message;
         const data = response.data;
         if (response.success && data) {
             switch (args.action) {
-                case "search":
+                case "list":
+                case "list_operations":
                     if (Array.isArray(data) && data.length > 0) {
-                        textContent += "\n\nFound documents:\n";
+                        textContent += "\n\nAvailable schemas:\n";
                         for (const item of data) {
-                            textContent += `\n📄 ${item.title} (${item.category})\n`;
-                            if (item.snippets && item.snippets.length > 0) {
-                                textContent += `   ${item.snippets[0].slice(0, 150)}...\n`;
+                            textContent += `\n  • ${item.name}`;
+                            if (item.title) {
+                                textContent += ` - ${item.title}`;
                             }
+                            if (item.description) {
+                                textContent += `\n    ${item.description.slice(0, 100)}...`;
+                            }
+                            textContent += "\n";
                         }
                     }
                     break;
-                case "get_schema":
-                    if (data.title) {
-                        textContent += `\n\n${data.title}\n`;
-                        textContent += `${"=".repeat(data.title.length)}\n\n`;
-                    }
-                    if (data.description) {
-                        textContent += `${data.description}\n\n`;
-                    }
-                    if (data.dataSchema) {
-                        textContent += "## Data Schema\n\n";
-                        textContent += "```typescript\n";
-                        textContent += data.dataSchema.slice(0, 1000);
+                case "get":
+                    if (data) {
+                        textContent += "\n\n## JSON Schema\n\n";
+                        textContent += "```json\n";
+                        textContent += JSON.stringify(data, null, 2);
                         textContent += "\n```\n";
                     }
-                    if (data.relatedOperations && data.relatedOperations.length > 0) {
-                        textContent += `\nRelated operations: ${data.relatedOperations.join(", ")}\n`;
-                    }
                     break;
-                case "learn_example":
-                    if (data.name) {
-                        textContent += `\n\n📚 ${data.title || data.name}\n`;
-                        textContent += `${"=".repeat((data.title || data.name).length)}\n\n`;
-                    }
-                    if (data.description) {
-                        textContent += `${data.description}\n\n`;
-                    }
-                    if (data.documents && data.documents.length > 0) {
-                        textContent += "Documents:\n";
-                        for (const doc of data.documents) {
-                            textContent += `  • ${doc.title}\n`;
-                        }
-                    }
-                    if (data.hasTestResults) {
-                        textContent += "\n✓ Test results available\n";
-                    }
-                    break;
-                case "guide":
-                    if (data.content) {
-                        const maxLength = 3000;
-                        let content = data.content;
-                        if (content.length > maxLength) {
-                            content = content.slice(0, maxLength) + "\n\n... [Content truncated, use search for specific topics]";
-                        }
-                        textContent += `\n\n${content}\n`;
-                    }
-                    break;
-                case "list_operations":
-                case "list_examples":
-                    if (Array.isArray(response.data)) {
-                        textContent += `\n\nAvailable ${args.action === "list_operations" ? "operations" : "examples"}:\n`;
-                        for (const item of response.data) {
-                            textContent += `  • ${item.name}${item.title ? ` - ${item.title}` : ""}\n`;
+                case "search":
+                    if (Array.isArray(data) && data.length > 0) {
+                        textContent += `\n\nFound ${data.length} schemas matching '${args.query}':\n`;
+                        for (const item of data) {
+                            textContent += `\n  • ${item.name}`;
+                            if (item.title) {
+                                textContent += ` - ${item.title}`;
+                            }
+                            textContent += "\n";
                         }
                     }
                     break;

package/dist/schema/query/index.js

@@ -117,7 +117,7 @@ export const ObjectOrderSchema = ObjectBaseSchema.extend({
     amount: BalanceTypeSchema.describe("Order amount"),
     builder: z.string().describe("Purchaser ID"),
     service: z.string().describe("Service ID"),
-    dispute: z.array(z.string()).describe("Dispute object ID list. When unsatisfied with order delivery, dispute objects can be created."),
+    dispute: z.array(z.string()).describe("Arb object ID list. When unsatisfied with order delivery, dispute objects can be created."),
     agent: z.array(z.string()).describe("Agent ID list. Agents handle all order operations except payment collection."),
     allocation: z.union([z.string(), z.null()]).describe("Order amount allocation object ID"),
     claimed_by: z.union([z.string(), z.null()]).describe("Order dispute object ID that has claimed order arbitration amount."),

package/dist/schema-query/index.d.ts

@@ -0,0 +1,29 @@
+export interface SchemaInfo {
+    name: string;
+    title: string;
+    description?: string;
+    path: string;
+}
+export interface SchemaQueryRequest {
+    action: "list" | "get" | "search" | "list_operations";
+    name?: string;
+    query?: string;
+}
+export interface SchemaQueryResponse {
+    [key: string]: unknown;
+    success: boolean;
+    action: string;
+    data: any;
+    message: string;
+    suggestions?: string[];
+}
+export declare function areSchemasAvailable(): boolean;
+export declare function getSchemaIndex(): {
+    tools: SchemaInfo[];
+    operations: SchemaInfo[];
+} | null;
+export declare function listSchemas(): SchemaInfo[];
+export declare function getSchema(name: string): any | null;
+export declare function searchSchemas(query: string): SchemaInfo[];
+export declare function listOperations(): SchemaInfo[];
+export declare function processSchemaQuery(request: SchemaQueryRequest): SchemaQueryResponse;

package/dist/schema-query/index.js

@@ -0,0 +1,149 @@
+import { readFileSync, existsSync } from "fs";
+import { resolve, join } from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const SCHEMAS_DIR = resolve(__dirname, "../../dist/schemas");
+export function areSchemasAvailable() {
+    return existsSync(SCHEMAS_DIR) && existsSync(join(SCHEMAS_DIR, "index.json"));
+}
+export function getSchemaIndex() {
+    try {
+        const indexPath = join(SCHEMAS_DIR, "index.json");
+        if (!existsSync(indexPath))
+            return null;
+        const content = readFileSync(indexPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+export function listSchemas() {
+    const index = getSchemaIndex();
+    if (!index)
+        return [];
+    return [
+        ...(index.tools || []),
+        ...(index.operations || []),
+    ];
+}
+export function getSchema(name) {
+    try {
+        let schemaPath = join(SCHEMAS_DIR, `${name}.schema.json`);
+        if (!existsSync(schemaPath)) {
+            schemaPath = join(SCHEMAS_DIR, `${name}.json`);
+        }
+        if (!existsSync(schemaPath)) {
+            return null;
+        }
+        const content = readFileSync(schemaPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+export function searchSchemas(query) {
+    const allSchemas = listSchemas();
+    const lowerQuery = query.toLowerCase();
+    return allSchemas.filter(schema => {
+        const nameMatch = schema.name.toLowerCase().includes(lowerQuery);
+        const titleMatch = schema.title?.toLowerCase().includes(lowerQuery);
+        const descMatch = schema.description?.toLowerCase().includes(lowerQuery);
+        return nameMatch || titleMatch || descMatch;
+    });
+}
+export function listOperations() {
+    const index = getSchemaIndex();
+    if (!index)
+        return [];
+    return (index.operations || []).filter(op => op.name.startsWith("onchain_operations_"));
+}
+export function processSchemaQuery(request) {
+    const { action, name, query } = request;
+    if (!areSchemasAvailable()) {
+        return {
+            success: false,
+            action,
+            data: null,
+            message: "Schema files are not available. Please run 'npm run generate:schemas' first.",
+            suggestions: ["Run 'npm run generate:schemas' to generate schema files", "Ensure the dist/schemas directory exists"],
+        };
+    }
+    switch (action) {
+        case "list": {
+            const schemas = listSchemas();
+            return {
+                success: true,
+                action,
+                data: schemas,
+                message: `Found ${schemas.length} available schemas`,
+            };
+        }
+        case "get": {
+            if (!name) {
+                return {
+                    success: false,
+                    action,
+                    data: null,
+                    message: "Schema name is required for 'get' action",
+                    suggestions: ["Provide a schema name", "Use 'list' action to see available schemas"],
+                };
+            }
+            const schema = getSchema(name);
+            if (!schema) {
+                const suggestions = searchSchemas(name).slice(0, 5);
+                return {
+                    success: false,
+                    action,
+                    data: null,
+                    message: `Schema '${name}' not found`,
+                    suggestions: suggestions.length > 0
+                        ? suggestions.map(s => `Did you mean: ${s.name}?`)
+                        : ["Use 'list' action to see available schemas"],
+                };
+            }
+            return {
+                success: true,
+                action,
+                data: schema,
+                message: `Retrieved schema: ${name}`,
+            };
+        }
+        case "search": {
+            if (!query) {
+                return {
+                    success: false,
+                    action,
+                    data: null,
+                    message: "Search query is required for 'search' action",
+                };
+            }
+            const results = searchSchemas(query);
+            return {
+                success: true,
+                action,
+                data: results,
+                message: `Found ${results.length} schemas matching '${query}'`,
+            };
+        }
+        case "list_operations": {
+            const operations = listOperations();
+            return {
+                success: true,
+                action,
+                data: operations,
+                message: `Found ${operations.length} on-chain operations`,
+            };
+        }
+        default:
+            return {
+                success: false,
+                action,
+                data: null,
+                message: `Unknown action: ${action}`,
+                suggestions: ["Use 'list', 'get', 'search', or 'list_operations'"],
+            };
+    }
+}