@crowley/rag-mcp 1.2.0 → 1.3.0

package/dist/__tests__/tools/memory.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createMemoryTools } from '../../tools/memory';
+import { createMemoryTools } from '../../tools/memory.js';
 function createMockCtx() {
     return {
         api: {
@@ -24,7 +24,7 @@ describe('Memory Tools', () => {
         ctx = createMockCtx();
     });
     function findTool(name) {
-        return tools.find(t => t.name === name);
+        return tools.find((t) => t.name === name);
     }
     describe('remember', () => {
         it('stores memory and returns formatted result', async () => {

package/dist/schemas.d.ts

@@ -11,40 +11,57 @@ import type { ToolInputSchema } from "./types.js";
  * Used during Phase 2 migration while ToolRegistry still expects raw JSON Schema.
  * Phase 3 passes Zod schemas directly to McpServer.registerTool().
  */
-export declare function zodToInputSchema(schema: z.ZodObject<z.ZodRawShape>): ToolInputSchema;
+export declare function zodToInputSchema(schema: z.ZodObject<Record<string, z.ZodType>>): ToolInputSchema;
 export declare const QueryStr: z.ZodString;
 export declare const Limit: z.ZodDefault<z.ZodNumber>;
 export declare const Offset: z.ZodDefault<z.ZodNumber>;
 export declare const FilePath: z.ZodString;
-export declare const FilePaths: z.ZodArray<z.ZodString, "many">;
+export declare const FilePaths: z.ZodArray<z.ZodString>;
 export declare const Content: z.ZodString;
 export declare const CollectionSuffix: z.ZodString;
-export declare const MemoryType: z.ZodEnum<["decision", "insight", "pattern", "adr", "tech_debt", "todo", "architecture", "convention", "bug_fix", "optimization"]>;
-export declare const ResponseFormat: z.ZodDefault<z.ZodEnum<["json", "markdown"]>>;
-export declare const Importance: z.ZodDefault<z.ZodEnum<["low", "medium", "high", "critical"]>>;
-export declare const Priority: z.ZodEnum<["low", "medium", "high", "critical"]>;
-export declare const Severity: z.ZodEnum<["low", "medium", "high", "critical"]>;
+export declare const MemoryType: z.ZodEnum<{
+    decision: "decision";
+    insight: "insight";
+    todo: "todo";
+    pattern: "pattern";
+    adr: "adr";
+    architecture: "architecture";
+    tech_debt: "tech_debt";
+    convention: "convention";
+    bug_fix: "bug_fix";
+    optimization: "optimization";
+}>;
+export declare const ResponseFormat: z.ZodDefault<z.ZodEnum<{
+    markdown: "markdown";
+    json: "json";
+}>>;
+export declare const Importance: z.ZodDefault<z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+    critical: "critical";
+}>>;
+export declare const Priority: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+    critical: "critical";
+}>;
+export declare const Severity: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+    critical: "critical";
+}>;
 export declare const PaginationParams: z.ZodObject<{
     limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     offset: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
-}, "strip", z.ZodTypeAny, {
-    limit?: number | undefined;
-    offset?: number | undefined;
-}, {
-    limit?: number | undefined;
-    offset?: number | undefined;
-}>;
+}, z.core.$strip>;
 export declare const SearchFilters: z.ZodOptional<z.ZodObject<{
     file_type: z.ZodOptional<z.ZodString>;
     directory: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    file_type?: string | undefined;
-    directory?: string | undefined;
-}, {
-    file_type?: string | undefined;
-    directory?: string | undefined;
-}>>;
-export declare const Tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, z.core.$strip>>;
+export declare const Tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
 export declare const Confidence: z.ZodOptional<z.ZodNumber>;
 /** Base shape for search tools: query + optional limit + optional filters */
 export declare const SearchInput: z.ZodObject<{
@@ -53,45 +70,29 @@ export declare const SearchInput: z.ZodObject<{
     filters: z.ZodOptional<z.ZodObject<{
         file_type: z.ZodOptional<z.ZodString>;
         directory: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        file_type?: string | undefined;
-        directory?: string | undefined;
-    }, {
-        file_type?: string | undefined;
-        directory?: string | undefined;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    query: string;
-    limit?: number | undefined;
-    filters?: {
-        file_type?: string | undefined;
-        directory?: string | undefined;
-    } | undefined;
-}, {
-    query: string;
-    limit?: number | undefined;
-    filters?: {
-        file_type?: string | undefined;
-        directory?: string | undefined;
-    } | undefined;
-}>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /** Base shape for memory record tools */
 export declare const MemoryRecordInput: z.ZodObject<{
     content: z.ZodString;
-    type: z.ZodEnum<["decision", "insight", "pattern", "adr", "tech_debt", "todo", "architecture", "convention", "bug_fix", "optimization"]>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    importance: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high", "critical"]>>>;
+    type: z.ZodEnum<{
+        decision: "decision";
+        insight: "insight";
+        todo: "todo";
+        pattern: "pattern";
+        adr: "adr";
+        architecture: "architecture";
+        tech_debt: "tech_debt";
+        convention: "convention";
+        bug_fix: "bug_fix";
+        optimization: "optimization";
+    }>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    importance: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>>>;
     context: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    type: "decision" | "insight" | "todo" | "adr" | "pattern" | "architecture" | "tech_debt" | "convention" | "bug_fix" | "optimization";
-    content: string;
-    context?: string | undefined;
-    tags?: string[] | undefined;
-    importance?: "low" | "medium" | "high" | "critical" | undefined;
-}, {
-    type: "decision" | "insight" | "todo" | "adr" | "pattern" | "architecture" | "tech_debt" | "convention" | "bug_fix" | "optimization";
-    content: string;
-    context?: string | undefined;
-    tags?: string[] | undefined;
-    importance?: "low" | "medium" | "high" | "critical" | undefined;
-}>;
+}, z.core.$strip>;

package/dist/schemas.js

@@ -5,7 +5,6 @@
  * from raw JSON Schema objects to Zod-based inputSchema definitions.
  */
 import { z } from "zod";
-import { zodToJsonSchema } from "zod-to-json-schema";
 // ── JSON Schema conversion ──────────────────────────────────
 /**
  * Convert a Zod object schema to the MCP ToolInputSchema format.
@@ -13,7 +12,7 @@ import { zodToJsonSchema } from "zod-to-json-schema";
  * Phase 3 passes Zod schemas directly to McpServer.registerTool().
  */
 export function zodToInputSchema(schema) {
-    const jsonSchema = zodToJsonSchema(schema, { target: "openApi3" });
+    const jsonSchema = z.toJSONSchema(schema);
     return {
         type: "object",
         properties: (jsonSchema.properties ?? {}),

package/dist/tool-middleware.js

@@ -8,6 +8,7 @@
  * During Phase 2 migration, ToolRegistry continues to use its own copy.
  * Phase 3 replaces ToolRegistry with wrapHandler() + McpServer.registerTool().
  */
+import { validationPipeline } from "./validation-hooks.js";
 // ── Timeouts ────────────────────────────────────────────────
 /** Default tool timeout in milliseconds */
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -182,13 +183,22 @@ export function wrapHandler(name, handler, deps) {
         }
         const startTime = Date.now();
         try {
+            // Validate: run PreToolUse hooks
+            const validation = await validationPipeline.validate(name, args, ctx);
+            if (!validation.allowed) {
+                return `Blocked: ${validation.reason || 'validation failed'}`;
+            }
+            const validatedArgs = validation.modifiedArgs || args;
+            const warningPrefix = validation.warnings?.length
+                ? `⚠️ ${validation.warnings.join(' | ')}\n\n`
+                : '';
             // Before: auto-enrich context
             const contextPrefix = ctx.enrichmentEnabled && deps.enricher
-                ? await deps.enricher.before(name, args, ctx)
+                ? await deps.enricher.before(name, validatedArgs, ctx)
                 : null;
             // Execute original handler (with timeout)
             const timeoutMs = TOOL_TIMEOUTS[name] ?? DEFAULT_TIMEOUT_MS;
-            const result = await withTimeout(handler(args, ctx), timeoutMs, name);
+            const result = await withTimeout(handler(validatedArgs, ctx), timeoutMs, name);
             // Extract text for tracking/enrichment
             const text = typeof result === "string" ? result : result.text;
             // After: track interaction (fire-and-forget)
@@ -197,12 +207,13 @@ export function wrapHandler(name, handler, deps) {
             }
             // Track usage (fire-and-forget)
             trackUsage(name, args, startTime, true, text, undefined, ctx);
-            // Prepend context if available
-            if (contextPrefix) {
+            // Prepend context/warnings if available
+            const prefix = [warningPrefix, contextPrefix].filter(Boolean).join('');
+            if (prefix) {
                 if (typeof result === "string") {
-                    return contextPrefix + "\n\n" + result;
+                    return prefix + result;
                 }
-                return { text: contextPrefix + "\n\n" + result.text, structured: result.structured };
+                return { text: prefix + result.text, structured: result.structured };
             }
             return result;
         }

package/dist/tools/advanced.js

@@ -15,9 +15,9 @@ export function createAdvancedTools(projectName) {
             description: `Consolidate duplicate memories for ${projectName}. Finds similar memories and merges them using LLM to reduce clutter.`,
             schema: z.object({
                 type: z.string().optional().describe("Filter by memory type (decision, insight, context, todo, conversation, note, or all). Default: all"),
-                threshold: z.number().optional().describe("Similarity threshold for merging (0.5-1.0, default: 0.9). Lower = more aggressive merging."),
+                threshold: z.coerce.number().optional().describe("Similarity threshold for merging (0.5-1.0, default: 0.9). Lower = more aggressive merging."),
                 dryRun: z.boolean().optional().describe("If true, preview merge candidates without making changes (default: true)."),
-                limit: z.number().optional().describe("Max clusters to process (default: 50)."),
+                limit: z.coerce.number().optional().describe("Max clusters to process (default: 50)."),
             }),
             annotations: TOOL_ANNOTATIONS["merge_memories"],
             handler: async (args, ctx) => {
@@ -65,7 +65,7 @@ export function createAdvancedTools(projectName) {
                 currentFile: z.string().describe("Path of the file being edited"),
                 currentCode: z.string().describe("Current code snippet or file content"),
                 language: z.string().optional().describe("Programming language filter (optional)"),
-                limit: z.number().optional().describe("Max results (default: 5)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 5)"),
             }),
             annotations: TOOL_ANNOTATIONS["get_completion_context"],
             handler: async (args, ctx) => {
@@ -108,7 +108,7 @@ export function createAdvancedTools(projectName) {
                 currentFile: z.string().describe("Path of the file being edited"),
                 currentCode: z.string().describe("Current code content"),
                 language: z.string().optional().describe("Programming language filter (optional)"),
-                limit: z.number().optional().describe("Max suggestions (default: 10)"),
+                limit: z.coerce.number().optional().describe("Max suggestions (default: 10)"),
             }),
             annotations: TOOL_ANNOTATIONS["get_import_suggestions"],
             handler: async (args, ctx) => {
@@ -147,7 +147,7 @@ export function createAdvancedTools(projectName) {
                 typeName: z.string().optional().describe("Name of the type/interface/class to look up"),
                 code: z.string().optional().describe("Code containing types to look up (alternative to typeName)"),
                 currentFile: z.string().optional().describe("Current file to exclude from results"),
-                limit: z.number().optional().describe("Max results per category (default: 5)"),
+                limit: z.coerce.number().optional().describe("Max results per category (default: 5)"),
             }),
             annotations: TOOL_ANNOTATIONS["get_type_context"],
             handler: async (args, ctx) => {
@@ -187,7 +187,7 @@ export function createAdvancedTools(projectName) {
             name: "get_behavior_patterns",
             description: `Analyze user workflow patterns for ${projectName}. Shows peak hours, tool preferences, common sequences, and session statistics.`,
             schema: z.object({
-                days: z.number().optional().describe("Number of days to analyze (default: 7)"),
+                days: z.coerce.number().optional().describe("Number of days to analyze (default: 7)"),
                 sessionId: z.string().optional().describe("Filter to a specific session (optional)"),
             }),
             annotations: TOOL_ANNOTATIONS["get_behavior_patterns"],

package/dist/tools/agents.js

@@ -15,7 +15,7 @@ export function createAgentTools(projectName) {
                 type: z.enum(["research", "review", "documentation", "refactor", "test"]).describe("Agent type: research, review, documentation, refactor, or test"),
                 task: z.string().describe("The task for the agent to perform"),
                 context: z.string().optional().describe("Optional additional context (code, requirements, etc.)"),
-                maxIterations: z.number().optional().describe("Maximum ReAct iterations (default: varies by agent type)"),
+                maxIterations: z.coerce.number().optional().describe("Maximum ReAct iterations (default: varies by agent type)"),
             }),
             annotations: TOOL_ANNOTATIONS["run_agent"],
             handler: async (args, ctx) => {
@@ -59,6 +59,74 @@ export function createAgentTools(projectName) {
                 return result;
             },
         },
+        {
+            name: "tribunal_debate",
+            description: `Run an adversarial debate on a topic for ${projectName}. Multiple advocates argue positions, a judge renders a verdict. Use for architecture decisions, tech choices, or code approach trade-offs.`,
+            schema: z.object({
+                topic: z.string().describe("The debate topic (e.g., 'Should we use REST or gRPC for the new API?')"),
+                positions: z.array(z.string()).min(2).max(4).describe("Positions to debate (2-4 options, e.g., ['REST', 'gRPC'])"),
+                context: z.string().optional().describe("Additional context for the debate"),
+                maxRounds: z.coerce.number().optional().describe("Number of rebuttal rounds (default: 1, max: 3)"),
+                useCodeContext: z.boolean().optional().describe("Fetch relevant code, ADRs, and patterns as evidence (default: false)"),
+                autoRecord: z.boolean().optional().describe("Save verdict as a decision in project memory (default: false)"),
+            }),
+            annotations: TOOL_ANNOTATIONS["tribunal_debate"] || { priority: 0.4, readOnlyHint: true },
+            handler: async (args, ctx) => {
+                const { topic, positions, context, maxRounds, useCodeContext, autoRecord } = args;
+                const response = await ctx.api.post("/api/tribunal/debate", {
+                    projectName: ctx.projectName,
+                    topic,
+                    positions,
+                    context,
+                    maxRounds,
+                    useCodeContext,
+                    autoRecord,
+                });
+                const data = response.data;
+                // Format result as markdown
+                let result = `## Tribunal Debate: ${data.topic}\n`;
+                result += `**Status:** ${data.status}`;
+                result += ` | **Duration:** ${Math.round(data.durationMs / 1000)}s`;
+                result += ` | **Cost:** ~$${data.cost?.estimatedUsd?.toFixed(3) || '?'}\n\n`;
+                // Phases summary
+                if (data.phases) {
+                    result += `### Phases\n`;
+                    for (const phase of data.phases) {
+                        result += `- **${phase.name}**: ${Math.round(phase.durationMs / 1000)}s, ${phase.tokens} tokens\n`;
+                    }
+                    result += `\n`;
+                }
+                // Arguments
+                if (data.arguments && data.arguments.length > 0) {
+                    result += `### Arguments\n`;
+                    for (const arg of data.arguments) {
+                        const label = arg.round === 0 ? 'Initial' : `Rebuttal R${arg.round}`;
+                        result += `#### ${arg.position} (${label})\n${arg.content}\n\n`;
+                    }
+                }
+                // Verdict
+                if (data.verdict) {
+                    result += `### Verdict\n`;
+                    result += `**Recommendation:** ${data.verdict.recommendation}\n`;
+                    result += `**Confidence:** ${data.verdict.confidence}\n\n`;
+                    if (data.verdict.scores) {
+                        result += `**Scores:**\n`;
+                        for (const s of data.verdict.scores) {
+                            result += `- ${s.position}: ${s.score}/10\n`;
+                        }
+                        result += `\n`;
+                    }
+                    result += `**Reasoning:**\n${data.verdict.reasoning}\n\n`;
+                    result += `**Trade-offs:**\n${data.verdict.tradeoffs}\n\n`;
+                    result += `**Dissent:**\n${data.verdict.dissent}\n\n`;
+                    result += `**Conditions:**\n${data.verdict.conditions}\n`;
+                }
+                if (data.error) {
+                    result += `\n**Error:** ${data.error}\n`;
+                }
+                return result;
+            },
+        },
         {
             name: "get_agent_types",
             description: `List available agent types for ${projectName} with descriptions.`,

package/dist/tools/analytics.js

@@ -154,7 +154,7 @@ export function createAnalyticsTools(projectName) {
             description: `Enable scalar quantization on a ${projectName} collection to reduce memory usage.`,
             schema: z.object({
                 collectionName: z.string().describe("Collection name to enable quantization on"),
-                quantile: z.number().optional().describe("Quantile for quantization (0-1, default: 0.99)"),
+                quantile: z.coerce.number().optional().describe("Quantile for quantization (0-1, default: 0.99)"),
             }),
             annotations: TOOL_ANNOTATIONS["enable_quantization"],
             handler: async (args, ctx) => {

package/dist/tools/architecture.js

@@ -56,7 +56,7 @@ ${alternatives ? `## Alternatives Considered\n${alternatives}` : ""}`;
             schema: z.object({
                 query: z.string().optional().describe("Search query (optional - returns all if empty)"),
                 status: z.enum(["proposed", "accepted", "deprecated", "superseded", "all"]).optional().describe("Filter by status"),
-                limit: z.number().optional().describe("Max results (default: 10)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 10)"),
             }),
             annotations: TOOL_ANNOTATIONS["get_adrs"],
             handler: async (args, ctx) => {
@@ -138,7 +138,7 @@ ${appliesTo ? `## Applies To\n${appliesTo}` : ""}`;
             schema: z.object({
                 query: z.string().optional().describe("Search for patterns by name or description"),
                 appliesTo: z.string().optional().describe("Filter by what patterns apply to (e.g., 'api', 'module')"),
-                limit: z.number().optional().describe("Max results (default: 10)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 10)"),
             }),
             annotations: TOOL_ANNOTATIONS["get_patterns"],
             handler: async (args, ctx) => {
@@ -437,7 +437,7 @@ ${relatedAdr ? `## Related ADR\n${relatedAdr}` : ""}`;
             description: `List technical debt items for ${projectName}.`,
             schema: z.object({
                 impact: z.enum(["low", "medium", "high", "critical", "all"]).optional().describe("Filter by impact"),
-                limit: z.number().optional().describe("Max results (default: 10)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 10)"),
             }),
             annotations: TOOL_ANNOTATIONS["get_tech_debt"],
             handler: async (args, ctx) => {

package/dist/tools/ask.js

@@ -99,7 +99,7 @@ export function createAskTools(projectName) {
                 conversation: z.string().describe("The conversation text to analyze"),
                 context: z.string().optional().describe("Additional context about the conversation"),
                 autoSave: z.boolean().optional().describe("Automatically save extracted learnings (default: false)"),
-                minConfidence: z.number().optional().describe("Minimum confidence threshold for learnings (0-1, default: 0.7)"),
+                minConfidence: z.coerce.number().optional().describe("Minimum confidence threshold for learnings (0-1, default: 0.7)"),
             }),
             annotations: TOOL_ANNOTATIONS["analyze_conversation"],
             handler: async (args, ctx) => {

package/dist/tools/clustering.js

@@ -15,8 +15,8 @@ export function createClusteringTools(projectName) {
             description: `Cluster code in the ${projectName} codebase by similarity. Groups related files around seed points.`,
             schema: z.object({
                 seedIds: z.array(z.string()).describe("Seed point IDs to cluster around"),
-                limit: z.number().optional().describe("Max results per cluster (default: 5)"),
-                threshold: z.number().optional().describe("Minimum similarity threshold (0-1, default: 0.7)"),
+                limit: z.coerce.number().optional().describe("Max results per cluster (default: 5)"),
+                threshold: z.coerce.number().optional().describe("Minimum similarity threshold (0-1, default: 0.7)"),
             }),
             annotations: TOOL_ANNOTATIONS["cluster_code"],
             handler: async (args, ctx) => {
@@ -52,8 +52,8 @@ export function createClusteringTools(projectName) {
             description: `Find duplicate or near-duplicate code in ${projectName}. Groups similar files by content.`,
             schema: z.object({
                 collection: z.string().optional().describe("Collection to search (default: codebase)"),
-                limit: z.number().optional().describe("Max duplicate groups to return (default: 10)"),
-                threshold: z.number().optional().describe("Minimum similarity threshold (0-1, default: 0.9)"),
+                limit: z.coerce.number().optional().describe("Max duplicate groups to return (default: 10)"),
+                threshold: z.coerce.number().optional().describe("Minimum similarity threshold (0-1, default: 0.9)"),
             }),
             annotations: TOOL_ANNOTATIONS["find_duplicates"],
             handler: async (args, ctx) => {
@@ -97,7 +97,7 @@ export function createClusteringTools(projectName) {
             schema: z.object({
                 positiveIds: z.array(z.string()).describe("IDs of vectors to find similar code to"),
                 negativeIds: z.array(z.string()).optional().describe("IDs of vectors to avoid (dissimilar)"),
-                limit: z.number().optional().describe("Max results (default: 5)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 5)"),
             }),
             annotations: TOOL_ANNOTATIONS["recommend_similar"],
             handler: async (args, ctx) => {
@@ -129,7 +129,7 @@ export function createClusteringTools(projectName) {
                 text: z.string().describe("Text to extract learnings from"),
                 context: z.string().optional().describe("Additional context about the text"),
                 autoSave: z.boolean().optional().describe("Automatically save extracted learnings (default: false)"),
-                minConfidence: z.number().optional().describe("Minimum confidence threshold (0-1, default: 0.7)"),
+                minConfidence: z.coerce.number().optional().describe("Minimum confidence threshold (0-1, default: 0.7)"),
             }),
             annotations: TOOL_ANNOTATIONS["extract_learnings"],
             handler: async (args, ctx) => {

package/dist/tools/confluence.js

@@ -15,7 +15,7 @@ export function createConfluenceTools(projectName) {
             description: `Search indexed Confluence documentation for ${projectName}. Returns relevant pages with content snippets.`,
             schema: z.object({
                 query: z.string().describe("Search query for Confluence content"),
-                limit: z.number().optional().describe("Max results (default: 5)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 5)"),
                 spaceKey: z.string().optional().describe("Filter by Confluence space key"),
             }),
             annotations: TOOL_ANNOTATIONS["search_confluence"],
@@ -46,7 +46,7 @@ export function createConfluenceTools(projectName) {
             schema: z.object({
                 spaceKeys: z.array(z.string()).optional().describe("Specific space keys to index (indexes all accessible if empty)"),
                 labels: z.array(z.string()).optional().describe("Filter pages by labels"),
-                maxPages: z.number().optional().describe("Maximum pages to index (default: 500)"),
+                maxPages: z.coerce.number().optional().describe("Maximum pages to index (default: 500)"),
                 force: z.boolean().optional().describe("Force re-index even if already indexed"),
             }),
             annotations: TOOL_ANNOTATIONS["index_confluence"],

package/dist/tools/indexing.js

@@ -138,10 +138,10 @@ export function createIndexingTools(projectName) {
             schema: z.object({}),
             outputSchema: z.object({
                 status: z.string(),
-                totalFiles: z.number().optional(),
-                indexedFiles: z.number().optional(),
+                totalFiles: z.coerce.number().optional(),
+                indexedFiles: z.coerce.number().optional(),
                 lastUpdated: z.string().optional(),
-                vectorCount: z.number().optional(),
+                vectorCount: z.coerce.number().optional(),
                 cached: z.boolean(),
             }),
             annotations: TOOL_ANNOTATIONS["get_index_status"],

package/dist/tools/memory.js

@@ -62,7 +62,7 @@ export function createMemoryTools(projectName) {
             schema: z.object({
                 query: z.string().describe("What to recall (semantic search)"),
                 type: z.enum(["decision", "insight", "context", "todo", "conversation", "note", "all"]).optional().describe("Filter by memory type (default: all)"),
-                limit: z.number().optional().describe("Max memories to retrieve (default: 5)"),
+                limit: z.coerce.number().optional().describe("Max memories to retrieve (default: 5)"),
             }),
             annotations: TOOL_ANNOTATIONS["recall"],
             handler: async (args, ctx) => {
@@ -89,8 +89,8 @@ export function createMemoryTools(projectName) {
             schema: z.object({
                 type: z.enum(["decision", "insight", "context", "todo", "conversation", "note", "all"]).optional().describe("Filter by type"),
                 tag: z.string().optional().describe("Filter by tag"),
-                limit: z.number().optional().describe("Max results (default: 10)"),
-                offset: z.number().optional().describe("Pagination offset (default: 0)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 10)"),
+                offset: z.coerce.number().optional().describe("Pagination offset (default: 0)"),
             }),
             annotations: TOOL_ANNOTATIONS["list_memories"],
             handler: async (args, ctx) => {
@@ -129,7 +129,7 @@ export function createMemoryTools(projectName) {
             schema: z.object({
                 memoryId: z.string().optional().describe("Specific memory ID to delete"),
                 type: z.enum(["decision", "insight", "context", "todo", "conversation", "note"]).optional().describe("Delete all memories of this type"),
-                olderThanDays: z.number().optional().describe("Delete memories older than N days"),
+                olderThanDays: z.coerce.number().optional().describe("Delete memories older than N days"),
             }),
             annotations: TOOL_ANNOTATIONS["forget"],
             handler: async (args, ctx) => {
@@ -247,8 +247,8 @@ export function createMemoryTools(projectName) {
             name: "review_memories",
             description: `Get auto-extracted memories pending review in ${projectName}. Shows unvalidated learnings that need human confirmation.`,
             schema: z.object({
-                limit: z.number().optional().describe("Max memories to return (default: 20)"),
-                offset: z.number().optional().describe("Pagination offset (default: 0)"),
+                limit: z.coerce.number().optional().describe("Max memories to return (default: 20)"),
+                offset: z.coerce.number().optional().describe("Pagination offset (default: 0)"),
             }),
             annotations: TOOL_ANNOTATIONS["review_memories"],
             handler: async (args, ctx) => {

package/dist/tools/pm.js

@@ -15,7 +15,7 @@ export function createPmTools(projectName) {
             description: `Search technical requirements and product documentation for ${projectName}. Finds relevant requirements, user stories, and specifications from Confluence.`,
             schema: z.object({
                 query: z.string().describe("Search query for requirements (e.g., 'video inspection flow', 'payment integration')"),
-                limit: z.number().optional().describe("Max results (default: 5)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 5)"),
             }),
             annotations: TOOL_ANNOTATIONS["search_requirements"],
             handler: async (args, ctx) => {
@@ -236,8 +236,8 @@ export function createPmTools(projectName) {
             description: `List all documented requirements/features for ${projectName} from Confluence. Groups by category or status.`,
             schema: z.object({
                 category: z.string().optional().describe("Filter by category (optional)"),
-                limit: z.number().optional().describe("Max results (default: 20)"),
-                offset: z.number().optional().describe("Pagination offset (default: 0)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 20)"),
+                offset: z.coerce.number().optional().describe("Pagination offset (default: 0)"),
             }),
             annotations: TOOL_ANNOTATIONS["list_requirements"],
             handler: async (args, ctx) => {

package/dist/tools/search.js

@@ -15,7 +15,7 @@ export function createSearchTools(projectName) {
             description: `Search the ${projectName} codebase. Returns file locations, symbols, and graph connections. Use Read tool to view the actual code at returned locations.`,
             schema: z.object({
                 query: z.string().describe("Search query for finding code"),
-                limit: z.number().optional().describe("Max results to return (default: 5)"),
+                limit: z.coerce.number().optional().describe("Max results to return (default: 5)"),
                 language: z.string().optional().describe("Filter by language (typescript, python, vue, etc.)"),
                 path: z.string().optional().describe("Filter by path pattern (e.g., 'src/modules/*')"),
                 layer: z.string().optional().describe("Filter by architectural layer (api, service, util, model, middleware, test, parser, types, config, other)"),
@@ -43,7 +43,7 @@ export function createSearchTools(projectName) {
             description: "Find code similar to a given snippet.",
             schema: z.object({
                 code: z.string().describe("Code snippet to find similar code for"),
-                limit: z.number().optional().describe("Max results (default: 5)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 5)"),
             }),
             annotations: TOOL_ANNOTATIONS["search_similar"],
             handler: async (args, ctx) => {
@@ -66,7 +66,7 @@ export function createSearchTools(projectName) {
             schema: z.object({
                 query: z.string().describe("Search query"),
                 groupBy: z.string().optional().describe("Field to group by (default: 'file')"),
-                limit: z.number().optional().describe("Max groups to return (default: 10)"),
+                limit: z.coerce.number().optional().describe("Max groups to return (default: 10)"),
                 language: z.string().optional().describe("Filter by language"),
                 layer: z.string().optional().describe("Filter by architectural layer (api, service, util, etc.)"),
                 service: z.string().optional().describe("Filter by service/class name"),
@@ -97,8 +97,8 @@ export function createSearchTools(projectName) {
             description: `Hybrid search combining keyword matching and semantic similarity for ${projectName}. Returns file locations with symbols and connections. Use Read tool to view code.`,
             schema: z.object({
                 query: z.string().describe("Search query"),
-                limit: z.number().optional().describe("Max results (default: 10)"),
-                semanticWeight: z.number().optional().describe("Weight for semantic vs keyword (0-1, default: 0.7)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 10)"),
+                semanticWeight: z.coerce.number().optional().describe("Weight for semantic vs keyword (0-1, default: 0.7)"),
                 language: z.string().optional().describe("Filter by language"),
                 layer: z.string().optional().describe("Filter by architectural layer (api, service, util, etc.)"),
                 service: z.string().optional().describe("Filter by service/class name"),
@@ -128,7 +128,7 @@ export function createSearchTools(projectName) {
             description: `Search documentation in the ${projectName} project.`,
             schema: z.object({
                 query: z.string().describe("Search query"),
-                limit: z.number().optional().describe("Max results (default: 5)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 5)"),
             }),
             annotations: TOOL_ANNOTATIONS["search_docs"],
             handler: async (args, ctx) => {
@@ -154,11 +154,11 @@ export function createSearchTools(projectName) {
             schema: z.object({}),
             outputSchema: z.object({
                 projectName: z.string(),
-                totalFiles: z.number(),
-                totalLines: z.number().optional(),
-                vectorCount: z.number(),
+                totalFiles: z.coerce.number(),
+                totalLines: z.coerce.number().optional(),
+                vectorCount: z.coerce.number(),
                 lastIndexed: z.string().optional(),
-                languages: z.record(z.string(), z.number()).optional(),
+                languages: z.record(z.string(), z.coerce.number()).optional(),
             }),
             annotations: TOOL_ANNOTATIONS["get_project_stats"],
             handler: async (_args, ctx) => {
@@ -194,15 +194,15 @@ export function createSearchTools(projectName) {
             schema: z.object({
                 symbol: z.string().describe("Symbol name to find (function, class, type, etc.)"),
                 kind: z.string().optional().describe("Filter by kind: function, class, interface, type, enum, const"),
-                limit: z.number().optional().describe("Max results (default: 10)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 10)"),
             }),
             outputSchema: z.object({
                 symbols: z.array(z.object({
                     kind: z.string(),
                     name: z.string(),
                     file: z.string(),
-                    startLine: z.number(),
-                    endLine: z.number(),
+                    startLine: z.coerce.number(),
+                    endLine: z.coerce.number(),
                     signature: z.string(),
                     exported: z.boolean(),
                 })),
@@ -246,8 +246,8 @@ export function createSearchTools(projectName) {
             description: `Search ${projectName} codebase with graph expansion. Returns file locations plus connected files via import/call relationships. Use Read tool to view code.`,
             schema: z.object({
                 query: z.string().describe("Search query"),
-                limit: z.number().optional().describe("Max direct results (default: 5)"),
-                expandHops: z.number().optional().describe("Number of graph hops to expand (default: 1)"),
+                limit: z.coerce.number().optional().describe("Max direct results (default: 5)"),
+                expandHops: z.coerce.number().optional().describe("Number of graph hops to expand (default: 1)"),
             }),
             annotations: TOOL_ANNOTATIONS["search_graph"],
             handler: async (args, ctx) => {

package/dist/tools/session.js

@@ -102,7 +102,7 @@ export function createSessionTools(projectName, sharedCtx) {
             name: "analyze_usage_patterns",
             description: `Analyze tool usage patterns for ${projectName}. Shows common workflows, detected patterns, and recommendations for improving productivity.`,
             schema: z.object({
-                days: z.number().optional().describe("Number of days to analyze (default: 7)."),
+                days: z.coerce.number().optional().describe("Number of days to analyze (default: 7)."),
             }),
             annotations: TOOL_ANNOTATIONS["analyze_usage_patterns"],
             handler: async (args, ctx) => {

package/dist/tools/suggestions.js

@@ -290,7 +290,7 @@ export function createSuggestionTools(projectName) {
             schema: z.object({
                 file: z.string().optional().describe("File path to find related code for"),
                 code: z.string().optional().describe("Code snippet to find related code for"),
-                limit: z.number().optional().describe("Max results (default: 5)"),
+                limit: z.coerce.number().optional().describe("Max results (default: 5)"),
             }),
             annotations: TOOL_ANNOTATIONS["suggest_related_code"],
             handler: async (args, ctx) => {

package/dist/types.d.ts

@@ -2,7 +2,7 @@
  * Shared types for the MCP server tool modules.
  */
 import type { AxiosInstance } from "axios";
-import type { ZodObject, ZodRawShape } from "zod";
+import type { z } from "zod";
 import type { ToolAnnotations } from "./annotations.js";
 /** MCP tool input schema shape (raw JSON Schema) */
 export interface ToolInputSchema {
@@ -42,8 +42,8 @@ export interface ToolModule {
 export interface ToolSpec {
     name: string;
     description: string;
-    schema: ZodObject<ZodRawShape>;
-    outputSchema?: ZodObject<ZodRawShape>;
+    schema: z.ZodObject<Record<string, z.ZodType>>;
+    outputSchema?: z.ZodObject<Record<string, z.ZodType>>;
     annotations?: ToolAnnotations;
     handler: ToolHandler;
 }

package/dist/validation-hooks.d.ts

@@ -0,0 +1,40 @@
+/**
+ * PreToolUse Validation Hooks
+ *
+ * Validation pipeline that runs before tool execution.
+ * Hooks can block execution, modify args, or add warnings.
+ *
+ * Inspired by claude-quanta-plugin's PreToolUse hooks pattern.
+ */
+import type { ToolContext } from "./types.js";
+export interface ValidationResult {
+    allowed: boolean;
+    reason?: string;
+    warnings?: string[];
+    modifiedArgs?: Record<string, unknown>;
+}
+export type ValidationHook = (toolName: string, args: Record<string, unknown>, ctx: ToolContext) => Promise<ValidationResult> | ValidationResult;
+/**
+ * Prevent destructive operations without explicit confirmation.
+ * Blocks: index_codebase with force=true, forget (memory deletion).
+ */
+export declare const destructiveGuard: ValidationHook;
+/**
+ * Validate required fields for critical tools.
+ */
+export declare const requiredFieldsValidator: ValidationHook;
+/**
+ * Sanitize inputs — trim strings, enforce reasonable limits.
+ */
+export declare const inputSanitizer: ValidationHook;
+export declare class ValidationPipeline {
+    private hooks;
+    constructor(hooks?: ValidationHook[]);
+    addHook(hook: ValidationHook): void;
+    /**
+     * Run all hooks in sequence. First rejection stops the pipeline.
+     * Args can be modified by hooks (each hook sees the potentially modified args).
+     */
+    validate(toolName: string, args: Record<string, unknown>, ctx: ToolContext): Promise<ValidationResult>;
+}
+export declare const validationPipeline: ValidationPipeline;

package/dist/validation-hooks.js

@@ -0,0 +1,108 @@
+/**
+ * PreToolUse Validation Hooks
+ *
+ * Validation pipeline that runs before tool execution.
+ * Hooks can block execution, modify args, or add warnings.
+ *
+ * Inspired by claude-quanta-plugin's PreToolUse hooks pattern.
+ */
+// ── Built-in Hooks ──────────────────────────────────────────
+/**
+ * Prevent destructive operations without explicit confirmation.
+ * Blocks: index_codebase with force=true, forget (memory deletion).
+ */
+export const destructiveGuard = (toolName, args) => {
+    if (toolName === 'index_codebase' && args.force === true) {
+        return {
+            allowed: true,
+            warnings: ['Force reindex will delete and rebuild the entire index. This may take several minutes.'],
+        };
+    }
+    if (toolName === 'forget') {
+        return {
+            allowed: true,
+            warnings: ['This will permanently delete a memory entry.'],
+        };
+    }
+    return { allowed: true };
+};
+/**
+ * Validate required fields for critical tools.
+ */
+export const requiredFieldsValidator = (toolName, args) => {
+    // Search tools must have a query
+    const searchTools = ['search_codebase', 'hybrid_search', 'search_docs', 'find_feature', 'ask_codebase'];
+    if (searchTools.includes(toolName)) {
+        const query = args.query || args.question;
+        if (!query || (typeof query === 'string' && query.trim().length < 3)) {
+            return { allowed: false, reason: `${toolName} requires a query of at least 3 characters` };
+        }
+    }
+    // Memory tools must have content
+    if (toolName === 'remember' && (!args.content || (typeof args.content === 'string' && args.content.trim().length < 10))) {
+        return { allowed: false, reason: 'remember requires content of at least 10 characters' };
+    }
+    return { allowed: true };
+};
+/**
+ * Sanitize inputs — trim strings, enforce reasonable limits.
+ */
+export const inputSanitizer = (toolName, args) => {
+    const modified = { ...args };
+    let changed = false;
+    // Trim string values
+    for (const [key, value] of Object.entries(modified)) {
+        if (typeof value === 'string' && value !== value.trim()) {
+            modified[key] = value.trim();
+            changed = true;
+        }
+    }
+    // Cap limit params to prevent excessive results
+    if (typeof modified.limit === 'number' && modified.limit > 50) {
+        modified.limit = 50;
+        changed = true;
+    }
+    return changed
+        ? { allowed: true, modifiedArgs: modified }
+        : { allowed: true };
+};
+// ── Validation Pipeline ─────────────────────────────────────
+export class ValidationPipeline {
+    hooks = [];
+    constructor(hooks) {
+        this.hooks = hooks || [
+            destructiveGuard,
+            requiredFieldsValidator,
+            inputSanitizer,
+        ];
+    }
+    addHook(hook) {
+        this.hooks.push(hook);
+    }
+    /**
+     * Run all hooks in sequence. First rejection stops the pipeline.
+     * Args can be modified by hooks (each hook sees the potentially modified args).
+     */
+    async validate(toolName, args, ctx) {
+        let currentArgs = { ...args };
+        const allWarnings = [];
+        for (const hook of this.hooks) {
+            const result = await hook(toolName, currentArgs, ctx);
+            if (!result.allowed) {
+                return result;
+            }
+            if (result.warnings) {
+                allWarnings.push(...result.warnings);
+            }
+            if (result.modifiedArgs) {
+                currentArgs = result.modifiedArgs;
+            }
+        }
+        return {
+            allowed: true,
+            warnings: allWarnings.length > 0 ? allWarnings : undefined,
+            modifiedArgs: currentArgs !== args ? currentArgs : undefined,
+        };
+    }
+}
+export const validationPipeline = new ValidationPipeline();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowley/rag-mcp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Universal RAG MCP Server for any project",
   "type": "module",
   "main": "dist/index.js",
@@ -35,8 +35,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "axios": "^1.6.0",
     "glob": "^11.0.0",
-    "zod": "^3.25.76",
-    "zod-to-json-schema": "^3.25.1"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",