@razroo/code-validation-mcp-client 1.0.2 → 1.2.0

package/README.md

@@ -178,6 +178,74 @@ Get code files for a specific step.
 
 **Output:** Array of code files with content
 
+### 4. `search_with_context` ⭐
+
+**⚠️ MOST POWERFUL TOOL** - Search and get complete recipe context in one call.
+
+**Simplified API (Recommended):**
+- `code` (required): Code snippet to search
+- `responseMode` (optional): One of `'minimal'`, `'preview'`, `'full'` (default: `'preview'`)
+  - **`'minimal'`**: Recipe metadata only, no code files (~5KB per recipe) - **Best for discovery**
+  - **`'preview'`**: Code snippets + key steps (~20KB per recipe) - **Best for most queries** (DEFAULT)
+  - **`'full'`**: Complete code + all steps (~50KB+ per recipe) - **Use only when you need complete details**
+- `framework` (optional): Filter by framework
+- `language` (optional): Filter by language
+- `operationType` (optional): Filter by operation type
+- `limit` (optional): Number of recipe matches (default: 10)
+- `offset` (optional): Pagination offset - skip first N items (default: 0)
+
+**Advanced Options (Override `responseMode`):**
+- `includeCodeFiles` (optional): Include code content
+- `maxStepsPerRecipe` (optional): Max steps per recipe
+- `maxFilesPerStep` (optional): Max files per step
+- `maxFileSize` (optional): Max characters per file
+- `stepSelectionStrategy` (optional): `'complete'` or `'adjacent'`
+
+**Output:** Complete recipe matches with all steps, recommendations, execution plan, and pagination metadata
+
+**When to Use Each Mode:**
+- **`'minimal'`**: "Show me AWS starters", "What authentication recipes exist?"
+- **`'preview'`**: "Add authentication to my app", "Create a user registration form" (MOST COMMON)
+- **`'full'`**: "Show me the complete AWS CDK starter implementation"
+
+**Progressive Fetching Example:**
+```typescript
+// Step 1: Discovery with minimal mode
+const recipes = await search_with_context({
+  code: "AWS starter",
+  responseMode: "minimal"
+});
+// Returns: List of AWS starters with metadata (~5KB)
+
+// Step 2: User selects "AWS CDK Starter"
+// Step 3: Fetch full code for selected recipe
+const fullRecipe = await search_with_context({
+  code: "AWS CDK Starter",
+  responseMode: "full",
+  limit: 1
+});
+// Returns: Complete implementation (~50KB)
+```
+
+**Pagination Example:**
+```typescript
+// Fetch first 5 results
+const page1 = await search_with_context({
+  code: "authentication",
+  responseMode: "preview",
+  limit: 5,
+  offset: 0
+});
+
+// Fetch next 5 results
+const page2 = await search_with_context({
+  code: "authentication",
+  responseMode: "preview",
+  limit: 5,
+  offset: 5
+});
+```
+
 ## Troubleshooting
 
 ### "RAZROO_API_KEY is required"

package/dist/index.js

@@ -128,6 +128,38 @@ const TOOLS = [
                     description: 'Number of recipe matches to return (default: 10, max: 50)',
                     default: 10,
                 },
+                offset: {
+                    type: 'number',
+                    description: 'Pagination offset - skip first N items (default: 0)',
+                    default: 0,
+                },
+                responseMode: {
+                    type: 'string',
+                    enum: ['minimal', 'preview', 'full'],
+                    description: 'Response mode preset (RECOMMENDED - Simple API): "minimal" = recipe metadata only (~5KB), "preview" = code snippets + key steps (~20KB, DEFAULT), "full" = complete code + all steps (~50KB+). Use minimal for discovery, preview for most queries, full only when you need complete implementation details.',
+                    default: 'preview',
+                },
+                includeCodeFiles: {
+                    type: 'boolean',
+                    description: 'Advanced: Include code file contents (overrides responseMode if specified)',
+                },
+                maxStepsPerRecipe: {
+                    type: 'number',
+                    description: 'Advanced: Maximum steps per recipe to return (overrides responseMode if specified)',
+                },
+                maxFilesPerStep: {
+                    type: 'number',
+                    description: 'Advanced: Maximum files per step to return (overrides responseMode if specified)',
+                },
+                maxFileSize: {
+                    type: 'number',
+                    description: 'Advanced: Maximum characters per file (overrides responseMode if specified)',
+                },
+                stepSelectionStrategy: {
+                    type: 'string',
+                    enum: ['complete', 'adjacent'],
+                    description: 'Advanced: Step selection strategy (overrides responseMode if specified)',
+                },
             },
             required: ['code'],
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@razroo/code-validation-mcp-client",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "MCP client bridge for Razroo Code Validation API",
   "type": "module",
   "bin": {