ralph-hero-mcp-server 2.5.126 → 2.5.129

package/dist/lib/zod-helpers.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+/**
+ * Boolean schema that tolerates the harness wire-format for booleans.
+ *
+ * Background (GH-1130): When a ralph-hero MCP tool is invoked before its
+ * schema has been hydrated by Claude Code's `ToolSearch`, the harness
+ * passes boolean argument values through as the literal strings `"true"`
+ * or `"false"` instead of the native boolean primitives. A plain
+ * `z.boolean()` schema rejects those strings with `"Expected boolean,
+ * received string"`, producing MCP error -32602 and forcing the caller
+ * to round-trip through `ToolSearch` before the call can succeed.
+ *
+ * `z.coerce.boolean()` is NOT a safe replacement: it uses the JavaScript
+ * `Boolean()` constructor, and `Boolean("false") === true` because any
+ * non-empty string is truthy. That would silently flip every `"false"`
+ * arrival into `true`.
+ *
+ * `zBoolish` uses `z.preprocess` to map only the two exact literal
+ * strings the harness emits (`"true"` → `true`, `"false"` → `false`)
+ * before handing off to a real `z.boolean()` validator. Anything else
+ * (numbers, objects, `"yes"`, `"1"`, etc.) is passed through unchanged
+ * and rejected with the standard boolean error message. Native booleans
+ * pass through unchanged.
+ *
+ * @example
+ *   const Schema = z.object({ flag: zBoolish().optional().default(false) });
+ *   Schema.parse({ flag: true })     // { flag: true }
+ *   Schema.parse({ flag: "true" })   // { flag: true }
+ *   Schema.parse({ flag: "false" })  // { flag: false }
+ *   Schema.parse({ flag: "yes" })    // throws ZodError
+ */
+export function zBoolish() {
+    return z.preprocess((value) => {
+        if (value === "true")
+            return true;
+        if (value === "false")
+            return false;
+        return value;
+    }, z.boolean());
+}
+//# sourceMappingURL=zod-helpers.js.map

package/dist/tools/activity-tools.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import * as os from "node:os";
 import { readActivity } from "../lib/activity.js";
 import { toolSuccess, toolError } from "../types.js";
+import { zBoolish } from "../lib/zod-helpers.js";
 function defaultActivityRoot() {
     return process.env.RALPH_ACTIVITY_DIR ?? path.join(os.homedir(), ".ralph-hero", "activity");
 }
@@ -14,7 +15,7 @@ export function registerActivityTools(server) {
         category: z.enum(["work", "meta", "all"]).default("work").describe("Filter by category; default 'work' excludes meta noise"),
         project: z.string().nullable().default(null).describe("Filter by project name"),
         limit: z.number().int().min(1).default(50).describe("Max events to return (default 50; was 100 before 2.5.x)"),
-        compact: z.boolean().default(false).describe("When true, project each event to {ts, kind, tool, project}; drops actor/session_id/category/wrapper-target. Use for narrative synthesis."),
+        compact: zBoolish().default(false).describe("When true, project each event to {ts, kind, tool, project}; drops actor/session_id/category/wrapper-target. Use for narrative synthesis."),
     }, async (params) => {
         try {
             const result = readActivity({

package/dist/tools/batch-tools.js

@@ -8,6 +8,7 @@
 import { z } from "zod";
 import { isEarlierState, WORKFLOW_STATE_TO_STATUS } from "../lib/workflow-states.js";
 import { toolSuccess, toolError } from "../types.js";
+import { zBoolish } from "../lib/zod-helpers.js";
 import { ensureFieldCache, resolveFullConfig, } from "../lib/helpers.js";
 // ---------------------------------------------------------------------------
 // Aliased GraphQL builders
@@ -171,8 +172,7 @@ export function registerBatchTools(server, client, fieldCache) {
             .min(1)
             .max(MAX_OPERATIONS)
             .describe("Field updates to apply to all issues (1-3)"),
-        skipIfAtOrPast: z
-            .boolean()
+        skipIfAtOrPast: zBoolish()
             .optional()
             .default(false)
             .describe("For workflow_state operations, skip issues already at or past the target state (default: false)"),

package/dist/tools/dashboard-tools.js

@@ -12,6 +12,7 @@ import { toolSuccess, toolError, resolveProjectOwner, resolveProjectNumbers } fr
 import { detectWorkStreams } from "../lib/work-stream-detection.js";
 import { detectStreamPipelinePositions } from "../lib/pipeline-detection.js";
 import { calculateMetrics, DEFAULT_METRICS_CONFIG, } from "../lib/metrics.js";
+import { zBoolish } from "../lib/zod-helpers.js";
 // Re-export for backwards compatibility — tests + downstream tools used to
 // pull these symbols straight out of dashboard-tools.ts before they were
 // hoisted into lib/dashboard-fetch.ts.
@@ -34,8 +35,7 @@ export function registerDashboardTools(server, client, fieldCache) {
             .optional()
             .default("json")
             .describe("Output format (default: json)"),
-        includeHealth: z
-            .boolean()
+        includeHealth: zBoolish()
             .optional()
             .default(true)
             .describe("Include health indicators (default: true)"),
@@ -58,8 +58,7 @@ export function registerDashboardTools(server, client, fieldCache) {
             .optional()
             .default(10)
             .describe("Max issues to list per phase (default: 10)"),
-        includeMetrics: z
-            .boolean()
+        includeMetrics: zBoolish()
             .optional()
             .default(false)
             .describe("Include velocity metrics, risk score, and auto-status (default: false)"),

package/dist/tools/debug-tools.js

@@ -12,6 +12,7 @@ import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { toolSuccess, toolError } from "../types.js";
+import { zBoolish } from "../lib/zod-helpers.js";
 // ---------------------------------------------------------------------------
 // JSONL Parsing
 // ---------------------------------------------------------------------------
@@ -186,8 +187,7 @@ export function registerDebugTools(server, client) {
             .string()
             .optional()
             .describe("ISO date string. Only process events after this time (default: 24h ago)"),
-        dryRun: z
-            .boolean()
+        dryRun: zBoolish()
             .optional()
             .default(false)
             .describe("If true, report what would be created/updated without making changes"),

package/dist/tools/decompose-tools.js

@@ -12,6 +12,7 @@ import { z } from "zod";
 import { toolSuccess, toolError } from "../types.js";
 import { ensureFieldCache, resolveFullConfigOptionalRepo, } from "../lib/helpers.js";
 import { lookupRepo, lookupPattern, mergeDefaults, } from "../lib/repo-registry.js";
+import { zBoolish } from "../lib/zod-helpers.js";
 // ---------------------------------------------------------------------------
 // Pure function: buildDecomposition
 // ---------------------------------------------------------------------------
@@ -109,8 +110,7 @@ export function registerDecomposeTools(server, client, fieldCache) {
             .optional()
             .describe("Decomposition pattern name from .ralph-repos.yml. " +
             "Omit to list available patterns and repos."),
-        dryRun: z
-            .boolean()
+        dryRun: zBoolish()
             .optional()
             .default(true)
             .describe("When true (default), return the proposal without creating issues. " +

package/dist/tools/issue-tools.js

@@ -14,6 +14,7 @@ import { resolveState } from "../lib/state-resolution.js";
 import { parseDateMath } from "../lib/date-math.js";
 import { expandProfile } from "../lib/filter-profiles.js";
 import { toolSuccess, toolError } from "../types.js";
+import { zBoolish } from "../lib/zod-helpers.js";
 import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, getCurrentFieldValue, resolveConfig, resolveFullConfig, resolveFullConfigOptionalRepo, syncStatusField, autoAdvanceParent, resolveIterationId, } from "../lib/helpers.js";
 import { lookupRepo, mergeDefaults } from "../lib/repo-registry.js";
 import { isLockConflict } from "../lib/lock-guard.js";
@@ -378,13 +379,11 @@ export function registerIssueTools(server, client, fieldCache) {
         projectNumber: z.coerce.number().optional()
             .describe("Project number override (defaults to configured project)"),
         number: z.coerce.number().describe("Issue number"),
-        includeGroup: z
-            .boolean()
+        includeGroup: zBoolish()
             .optional()
             .default(true)
             .describe("Include group detection results (default: true). Set to false to skip group detection and save API calls when group context is not needed."),
-        includePipeline: z
-            .boolean()
+        includePipeline: zBoolish()
             .optional()
             .default(false)
             .describe("Include pipeline position: phase, convergence, member states, remaining phases. Auto-enables includeGroup."),
@@ -833,7 +832,7 @@ export function registerIssueTools(server, client, fieldCache) {
             .describe("Iteration/sprint title (e.g., 'Sprint 1'), @current, @next, or null to clear."),
         command: z.string().optional()
             .describe("Ralph command for semantic intent resolution (e.g., 'ralph_impl'). Required when workflowState is a semantic intent."),
-        force: z.boolean().optional()
+        force: zBoolish().optional()
             .describe("Bypass lock guard. Use only for recovery when an agent crash left an issue stuck in a lock state."),
     }, async (args) => {
         try {

package/dist/tools/plan-graph-tools.js

@@ -10,6 +10,7 @@ import { readFile } from "fs/promises";
 import { parsePlanGraph } from "../lib/plan-graph.js";
 import { toolSuccess, toolError } from "../types.js";
 import { resolveIssueNodeId, resolveConfig } from "../lib/helpers.js";
+import { zBoolish } from "../lib/zod-helpers.js";
 // ---------------------------------------------------------------------------
 // Pure function: diffDependencyEdges
 // ---------------------------------------------------------------------------
@@ -52,8 +53,7 @@ export function registerPlanGraphTools(server, client) {
         planPath: z
             .string()
             .describe("Absolute path to the plan markdown document"),
-        dryRun: z
-            .boolean()
+        dryRun: zBoolish()
             .optional()
             .default(false)
             .describe("When true, report what would change without mutating GitHub. Default: false."),

package/dist/tools/project-management-tools.js

@@ -9,6 +9,7 @@
 import { z } from "zod";
 import { toolSuccess, toolError } from "../types.js";
 import { buildBatchArchiveMutation } from "./batch-tools.js";
+import { zBoolish } from "../lib/zod-helpers.js";
 import { ensureFieldCache, resolveProjectItemId, resolveFullConfig, updateProjectItemField, } from "../lib/helpers.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -406,7 +407,7 @@ export function registerProjectManagementTools(server, client, fieldCache) {
             .describe("Archive a single issue by number. Mutually exclusive with workflowStates filter."),
         projectItemId: z.string().optional()
             .describe("Archive by project item ID (for draft issues). Mutually exclusive with number and workflowStates."),
-        unarchive: z.boolean().optional().default(false)
+        unarchive: zBoolish().optional().default(false)
             .describe("Unarchive instead of archive. Only works with number or projectItemId (single-item mode)."),
         workflowStates: z
             .array(z.string())
@@ -417,8 +418,7 @@ export function registerProjectManagementTools(server, client, fieldCache) {
             .optional()
             .default(50)
             .describe("Max items to archive per invocation (default 50, cap 200). Bulk mode only."),
-        dryRun: z
-            .boolean()
+        dryRun: zBoolish()
             .optional()
             .default(false)
             .describe("If true, return matching items without archiving them (default: false). Bulk mode only."),

package/dist/tools/project-tools.js

@@ -7,6 +7,7 @@
 import { z } from "zod";
 import { toolSuccess, toolError } from "../types.js";
 import { resolveProjectOwner } from "../types.js";
+import { zBoolish } from "../lib/zod-helpers.js";
 const WORKFLOW_STATE_OPTIONS = [
     { name: "Backlog", color: "GRAY", description: "Awaiting triage" },
     {
@@ -107,8 +108,7 @@ export function registerProjectTools(server, client, fieldCache) {
             .optional()
             .describe("Template project number to copy from. Overrides RALPH_GH_TEMPLATE_PROJECT env var. " +
             "When set, copies the template project (views, fields, automations) instead of creating blank."),
-        createIterationField: z
-            .boolean()
+        createIterationField: zBoolish()
             .optional()
             .default(false)
             .describe('When true, creates a "Sprint" iteration field with 2-week duration starting next Monday. ' +

package/dist/tools/relationship-tools.js

@@ -12,6 +12,7 @@ import { isValidState, isEarlierState, VALID_STATES, PARENT_GATE_STATES, isParen
 import { toolSuccess, toolError } from "../types.js";
 import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, getCurrentFieldValue, resolveConfig, resolveFullConfig, resolveFullConfigOptionalRepo, syncStatusField, } from "../lib/helpers.js";
 import { paginateConnection } from "../lib/pagination.js";
+import { zBoolish } from "../lib/zod-helpers.js";
 // ---------------------------------------------------------------------------
 // Sub-issue tree helpers (exported for testing)
 // ---------------------------------------------------------------------------
@@ -84,8 +85,7 @@ export function registerRelationshipTools(server, client, fieldCache) {
         childNumber: z
             .coerce.number()
             .describe("Child issue number (will become sub-issue of parent)"),
-        replaceParent: z
-            .boolean()
+        replaceParent: zBoolish()
             .optional()
             .default(false)
             .describe("If true, move child even if it already has a parent"),
@@ -692,8 +692,7 @@ export function registerRelationshipTools(server, client, fieldCache) {
             .optional()
             .default("OPEN")
             .describe("Filter parent issues by state (default: OPEN)"),
-        showChildren: z
-            .boolean()
+        showChildren: zBoolish()
             .optional()
             .default(false)
             .describe("Expand each group to include child issues with number/title/state/workflowState"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "2.5.126",
+  "version": "2.5.129",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",