@wowok/agent-mcp 2.6.1 → 2.6.3

package/dist/tools/handlers/project.js

@@ -3,10 +3,12 @@ import { generateDeploymentDocFromProject } from "../../project/deployment-bridg
 import { LocalProject } from "@wowok/wowok";
 import { validateStageGate } from "../../project/stage-gate.js";
 import { scanDeployment } from "../../knowledge/deployment-scanner.js";
-import { handleListProjects, handleCreateProject, handleCreateProjectFromOnchain, handleUpdateProject, handleGetProjectDetail, handleAddObject, handleRemoveObject, handleUpdateObject, handleCreateVersion, handleBuildGraph, handleGetGraph, handleEvaluateProject, handleSaveEvaluation, handleCompareProjects, handleRefreshObjects, handleGetObjectDiff, handleDeleteProject, handleGetMachineGraph, handlePreEvaluateCheck, handleVerifyDeployment, handleCloneProjectToNetwork, } from "../../project/handlers.js";
+import { handleListProjects, handleCreateProject, handleCreateProjectFromOnchain, handleUpdateProject, handleGetProjectDetail, handleAddObject, handleRemoveObject, handleUpdateObject, handleCreateVersion, handleBuildGraph, handleGetGraph, handleEvaluateProject, handleSaveEvaluation, handleCompareProjects, handleRefreshObjects, handleGetObjectDiff, handleDeleteProject, handleGetMachineGraph, handleGetGuardGraph, handlePreEvaluateCheck, handleVerifyDeployment, handleCloneProjectToNetwork, handleMigrateToMainnet, } from "../../project/handlers.js";
+import { handlePlanObjectEdit, handleApplyObjectEdit, handlePatchMachineNodes, handlePatchGuardTree, } from "../../project/edit-planner.js";
 import { strictParse } from "../../schema/index.js";
 import { ProjectOperationInputSchema } from "../../schema/project/index.js";
 import { getStageCache } from "../../project/index.js";
+import { getSkillsHintForProject } from "../../schema/utils/skills-recommendation.js";
 export async function handleProjectOperation(args) {
     const validated = strictParse(ProjectOperationInputSchema, args, "project_operation input");
     const { action } = validated;
@@ -66,6 +68,9 @@ export async function handleProjectOperation(args) {
         case "get_machine_graph":
             result = await handleGetMachineGraph(validated);
             break;
+        case "get_guard_graph":
+            result = await handleGetGuardGraph(validated);
+            break;
         case "assemble_context":
             result = await assembleContext(validated);
             break;
@@ -132,11 +137,29 @@ export async function handleProjectOperation(args) {
         case "migrate_network":
             result = await handleCloneProjectToNetwork(validated);
             break;
+        case "migrate_to_mainnet":
+            result = await handleMigrateToMainnet(validated);
+            break;
+        case "plan_object_edit":
+            result = await handlePlanObjectEdit(validated);
+            break;
+        case "apply_object_edit":
+            result = await handleApplyObjectEdit(validated);
+            break;
+        case "patch_machine_nodes":
+            result = await handlePatchMachineNodes(validated);
+            break;
+        case "patch_guard_tree":
+            result = await handlePatchGuardTree(validated);
+            break;
         default:
             throw new Error(`Unknown project_operation action: ${String(action)}`);
     }
+    const skillsHint = getSkillsHintForProject(action);
     return {
         content: [{ type: "text", text: JSON.stringify({ result }) }],
-        structuredContent: { result },
+        structuredContent: skillsHint
+            ? { result, skills_recommended: skillsHint }
+            : { result },
     };
 }

package/dist/tools/handlers/schema-query.js

@@ -1,4 +1,4 @@
-import { processSchemaQuery, } from "../../schema-query/index.js";
+import { processSchemaQuery, EXAMPLES_DIR, } from "../../schema-query/index.js";
 import { strictParse } from "../../schema/index.js";
 import { SchemaQueryInputSchema } from "../../schema/schema-query/index.js";
 export async function handleSchemaQuery(args) {
@@ -92,6 +92,29 @@ export async function handleSchemaQuery(args) {
                     textContent += "\n\nNo schemas found. Try 'list' to browse all available schemas, or use a broader search term.";
                 }
                 break;
+            case "search_examples": {
+                const items = (Array.isArray(data) ? data : []);
+                if (items.length > 0) {
+                    textContent += `\n\nFound ${items.length} example(s) matching '${request.query ?? ""}':\n`;
+                    for (const item of items) {
+                        textContent += `\n  • [score: ${item.score}] ${item.file}`;
+                        textContent += `\n    Title: ${item.title}`;
+                        textContent += `\n    Industry: ${item.industry} | Operation: ${item.operation_type} | Verified: ${item.verified ? "yes" : "no"}`;
+                        textContent += `\n    Tags: ${item.tags.join(", ")}`;
+                        textContent += `\n    Matched fields: ${item.matched_fields.join(", ")}`;
+                        const descPreview = item.description.length > 120
+                            ? `${item.description.slice(0, 120)}...`
+                            : item.description;
+                        textContent += `\n    Description: ${descPreview}`;
+                        textContent += "\n";
+                    }
+                    textContent += `\n  To view the full example JSON, read files from: ${EXAMPLES_DIR}`;
+                }
+                else {
+                    textContent += "\n\nNo examples found. Try broader terms like 'service', 'machine', 'guard', 'permission', or an industry name like 'rental' or 'retail'.";
+                }
+                break;
+            }
             default:
                 throw new Error(`Unknown schema_query action: ${String(request.action)}`);
         }

package/dist/tools/index.d.ts

@@ -2,6 +2,14 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ToolEntry, ToolDispatchResult, DispatchOptions } from "./types.js";
 export declare const TOOL_REGISTRY: ToolEntry[];
 export declare const TOOL_REGISTRY_MAP: Map<string, ToolEntry>;
+export interface StructuredSchemaError {
+    path: string;
+    code: string;
+    message: string;
+    expected?: string;
+    received_value?: unknown;
+    suggestion: string;
+}
 export declare function dispatchToolCall(name: string, args: unknown, options?: DispatchOptions): Promise<ToolDispatchResult>;
 export interface ToolListEntry {
     name: string;

package/dist/tools/index.js

@@ -462,10 +462,10 @@ const WOWOK_TOOL_DESCRIPTION = [
     "Projects are the core organizing unit for all WoWok workflows. The policy is context-aware:",
     "",
     "CASE 1 — COMPLEX REQUIREMENT (user wants to build/deploy a full service):",
-    "  Examples: '搭建旅行地陪服务', '开一个玩具店', '创建租赁服务'",
+    "  Examples: 'build a travel guide service', 'open a toy store', 'create a rental service'",
     "  → You MUST auto-create a project FIRST, then create objects.",
     "  → Check for similar existing projects first: project_operation action='list_projects'",
-    "    If similar projects exist (same industry), remind the user: '发现类似项目 X, 是否复用或新建?'",
+    "    If similar projects exist (same industry), remind the user: 'Found similar project X. Reuse or create new?'",
     "  → Workflow:",
     "    1. project_operation action='create_project' (perspective='producer', project_industry=<best match>)",
     "    2. Create on-chain objects via onchain_operations with env.project='<prefix>' (auto-tags + auto-associates to SQLite project)",
@@ -475,11 +475,11 @@ const WOWOK_TOOL_DESCRIPTION = [
     "    6. Report results, fix critical findings, then publish Service",
     "",
     "CASE 2 — SINGLE OBJECT CREATION (user wants one specific object):",
-    "  Examples: '创建一个Permission', '添加一个Contact', '建一个Guard'",
+    "  Examples: 'create a Permission', 'add a Contact', 'build a Guard'",
     "  → Do NOT auto-create a project. If the user has an existing project, create with env.project='<prefix>' to auto-associate.",
     "  → If no existing project, after creation, REMIND the user:",
-    "    '此对象已创建。建议将其加入一个项目以便管理: project_operation action=\"add_object\"",
-    "    如还没有项目, 可用 action=\"create_project\" 新建。现有项目: [list projects if any]'",
+    "    'This object has been created. Consider adding it to a project for management: project_operation action=\"add_object\"",
+    "    If no project exists yet, use action=\"create_project\" to create one. Existing projects: [list projects if any]'",
     "  → If the user then says 'yes, create a project' or 'add to project X', proceed accordingly.",
     "",
     "CASE 3 — CONSUMER FLOW (user wants to buy/evaluate a service):",
@@ -545,6 +545,150 @@ function formatZodErrors(error, input) {
         return `${path} [${code}]: ${message}${extras}`;
     });
 }
+function generateSuggestion(code, issue, receivedValue) {
+    const issueAny = issue;
+    switch (code) {
+        case "invalid_type": {
+            const expected = issueAny.expected;
+            const received = issueAny.received;
+            if (expected === "number" && typeof receivedValue === "string") {
+                return `Convert to number: ${Number(receivedValue)}`;
+            }
+            if (expected === "string") {
+                return `Wrap in quotes or call String(...)`;
+            }
+            if (expected === "array") {
+                return `Wrap in array: [${JSON.stringify(receivedValue)}]`;
+            }
+            if (expected === "object") {
+                return `Provide an object, not a primitive`;
+            }
+            return `Convert value to ${expected ?? "the expected type"}`;
+        }
+        case "invalid_enum_value": {
+            const options = issueAny.options;
+            const optionsStr = Array.isArray(options)
+                ? options.map((v) => JSON.stringify(v)).join(" | ")
+                : String(options);
+            return `Use one of: ${optionsStr}`;
+        }
+        case "invalid_literal": {
+            const expected = issueAny.expected;
+            return `Use the exact value: ${JSON.stringify(expected)}`;
+        }
+        case "too_small": {
+            const minimum = issueAny.minimum;
+            const type = issueAny.type;
+            if (type === "array") {
+                return `Add at least ${minimum} element(s) to the array`;
+            }
+            if (type === "string") {
+                return `String must be at least ${minimum} character(s) long`;
+            }
+            if (type === "number") {
+                return `Use a value >= ${minimum}`;
+            }
+            return `Value must be >= ${minimum}`;
+        }
+        case "too_big": {
+            const maximum = issueAny.maximum;
+            const type = issueAny.type;
+            if (type === "array") {
+                return `Reduce array to at most ${maximum} element(s)`;
+            }
+            if (type === "string") {
+                return `Shorten string to at most ${maximum} character(s)`;
+            }
+            if (type === "number") {
+                return `Use a value <= ${maximum}`;
+            }
+            return `Value must be <= ${maximum}`;
+        }
+        case "unrecognized_keys": {
+            const keys = issueAny.keys;
+            return `Remove unknown field(s): ${(keys ?? []).join(", ")}. Check the schema for valid field names.`;
+        }
+        case "invalid_union": {
+            return `Value does not match any of the union variants. Check the schema for valid shapes.`;
+        }
+        case "invalid_string": {
+            const validation = issueAny.validation;
+            if (validation === "url")
+                return `Provide a valid URL string`;
+            if (validation === "email")
+                return `Provide a valid email string`;
+            if (validation === "uuid")
+                return `Provide a valid UUID string`;
+            if (validation === "regex")
+                return `String does not match the required pattern`;
+            return `Provide a valid string matching the validation: ${validation ?? "unknown"}`;
+        }
+        case "invalid_date": {
+            return `Provide a valid Date object or ISO date string`;
+        }
+        case "not_finite": {
+            return `Use a finite number (not Infinity or NaN)`;
+        }
+        case "invalid_arguments": {
+            return `Arguments do not match the expected schema`;
+        }
+        case "invalid_return_type": {
+            return `Return type does not match the expected schema`;
+        }
+        case "custom": {
+            return `Custom validation failed — see the field's description in the schema`;
+        }
+        default: {
+            return `Fix the value at '${issue.path.join(".")}' based on the schema`;
+        }
+    }
+}
+function formatZodErrorsStructured(error, input) {
+    return error.issues.map(issue => {
+        const path = issue.path.length > 0
+            ? issue.path.map(p => typeof p === "number" ? `[${p}]` : p).join(".").replace(".[", "[")
+            : "(root)";
+        const code = issue.code;
+        const message = issue.message;
+        const issueAny = issue;
+        let expected;
+        if (code === "invalid_type") {
+            const exp = issueAny.expected;
+            const rec = issueAny.received;
+            if (typeof exp === "string" && typeof rec === "string") {
+                expected = exp;
+            }
+        }
+        else if (code === "invalid_literal") {
+            const exp = issueAny.expected;
+            if (exp !== undefined) {
+                expected = typeof exp === "string" ? exp : JSON.stringify(exp);
+            }
+        }
+        else if (code === "invalid_enum_value") {
+            const options = issueAny.options;
+            if (Array.isArray(options)) {
+                expected = options.map((v) => JSON.stringify(v)).join(" | ");
+            }
+        }
+        else if (code === "too_big" || code === "too_small") {
+            const threshold = issueAny.maximum ?? issueAny.minimum;
+            if (threshold !== undefined) {
+                expected = String(threshold);
+            }
+        }
+        const receivedVal = extractValueAtPath(input, issue.path);
+        const suggestion = generateSuggestion(code, issue, receivedVal);
+        return {
+            path,
+            code,
+            message,
+            expected,
+            received_value: receivedVal,
+            suggestion,
+        };
+    });
+}
 function extractValueAtPath(input, path) {
     if (input === undefined || input === null || path.length === 0) {
         return undefined;
@@ -837,18 +981,36 @@ async function handleWowok(args) {
         if (unknownFields.length > 0) {
             allErrors.push(`Unknown field(s): ${unknownFields.join(", ")}`);
         }
+        const structuredErrors = [];
+        if (!validationResult.success) {
+            structuredErrors.push(...formatZodErrorsStructured(validationResult.error, normalizedData));
+        }
+        if (unknownFields.length > 0) {
+            for (const f of unknownFields) {
+                structuredErrors.push({
+                    path: f,
+                    code: "unrecognized_keys",
+                    message: `Unknown field '${f}' is not allowed`,
+                    suggestion: `Remove field '${f}' or check the schema for valid field names`,
+                });
+            }
+        }
         const fullSchema = loadPreGeneratedSchema(normalizedToolName) ?? zodToJsonSchemaSafe(entry.config.inputSchema, normalizedToolName);
         const relevantSchema = extractRelevantSchema(fullSchema, normalizedToolName, normalizedData);
+        const firstSuggestion = structuredErrors[0]?.suggestion
+            ? ` FIRST ERROR SUGGESTION: ${structuredErrors[0].suggestion}`
+            : '';
         const errorPreview = allErrors.slice(0, 5).map((e, i) => `  ${i + 1}. ${e}`).join("\n");
         const schemaPreview = buildSchemaPreview(relevantSchema, normalizedToolName, normalizedData);
         const textContent = [
-            `Schema mismatch for ${normalizedToolName}. ${allErrors.length} error(s):`,
+            `Schema mismatch for ${normalizedToolName}. ${allErrors.length} error(s).${firstSuggestion}`,
             errorPreview,
             "",
             schemaPreview,
             "",
             "Fix the parameters based on the errors above and the schema summary, then retry.",
             `Full JSON Schema is in the structuredContent.schema.input field (cache it for future ${normalizedToolName} calls).`,
+            `Structured errors with fix suggestions are in structuredContent.result.structured_errors (ARCH-02).`,
         ].filter(Boolean).join("\n");
         return {
             content: [{
@@ -859,6 +1021,7 @@ async function handleWowok(args) {
                 result: {
                     status: "schema_mismatch",
                     errors: allErrors,
+                    structured_errors: structuredErrors,
                     hint: `Fix your parameters based on the schema below and retry. CACHE THIS SCHEMA for future ${normalizedToolName} calls — you don't need to query it again.`,
                 },
                 schema: {
@@ -903,12 +1066,19 @@ async function handleWowok(args) {
             const fullSchema = loadPreGeneratedSchema(normalizedToolName) ?? zodToJsonSchemaSafe(entry.config.inputSchema, normalizedToolName);
             const relevantSchema = extractRelevantSchema(fullSchema, normalizedToolName, normalizedData);
             const schemaPreview = buildSchemaPreview(relevantSchema, normalizedToolName, normalizedData);
+            const structuredErrors = [{
+                    path: "(runtime)",
+                    code: "schema_validation_error",
+                    message: errorMessage,
+                    suggestion: "Check the error message and the schema below for the correct field format",
+                }];
             const textContent = [
                 `Schema mismatch for ${normalizedToolName}: ${errorMessage}`,
                 "",
                 schemaPreview,
                 "",
                 "Fix the parameters and retry. Full JSON Schema is in structuredContent.schema.input.",
+                "Structured errors with fix suggestions are in structuredContent.result.structured_errors (ARCH-02).",
             ].join("\n");
             return {
                 content: [{
@@ -919,6 +1089,7 @@ async function handleWowok(args) {
                     result: {
                         status: "schema_mismatch",
                         errors: [errorMessage],
+                        structured_errors: structuredErrors,
                         hint: `Fix your parameters based on the schema below and retry. CACHE THIS SCHEMA for future ${normalizedToolName} calls.`,
                     },
                     schema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/agent-mcp",
-  "version": "2.6.1",
+  "version": "2.6.3",
   "description": "Making It Easy for AI Agents to Communicate, Collaborate, Trade, and Trust.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -50,7 +50,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@wowok/wowok": "2.6.1",
+    "@wowok/wowok": "2.6.3",
     "lodash": "^4.18.1",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.25.2"