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

package/README.md

@@ -178,29 +178,73 @@ Get code files for a specific step.
 
 **Output:** Array of code files with content
 
-### 4. `search_with_context`
+### 4. `search_with_context` ⭐
 
 **⚠️ MOST POWERFUL TOOL** - Search and get complete recipe context in one call.
 
-**Input:**
+**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)
-- `includeCodeFiles` (optional): Include code content (default: true)
-- `maxStepsPerRecipe` (optional): Max steps per recipe (default: 10)
-- `maxFilesPerStep` (optional): Max files per step (default: 20)
-- `maxFileSize` (optional): Max characters per file (default: 10000)
-- `stepSelectionStrategy` (optional): Step selection strategy (default: 'complete')
-  - `'complete'`: Returns ALL steps in the recipe (best for starters/scaffolds)
-  - `'adjacent'`: Returns only matched + setup + nearby steps (minimal context)
-
-**Output:** Complete recipe matches with all steps, recommendations, and execution plan
-
-**When to Use:**
-- Use `'complete'` strategy (default) for: AWS starters, authentication setup, form scaffolds, API integration
-- Use `'adjacent'` strategy for: Specific bug fixes, targeted changes where you only need minimal context
+- `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
 

package/dist/index.js

@@ -128,31 +128,37 @@ 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: 'Include code file contents in response (default: true). Set to false for summaries only.',
-                    default: true,
+                    description: 'Advanced: Include code file contents (overrides responseMode if specified)',
                 },
                 maxStepsPerRecipe: {
                     type: 'number',
-                    description: 'Maximum steps per recipe to return (default: 10, max: 20)',
-                    default: 10,
+                    description: 'Advanced: Maximum steps per recipe to return (overrides responseMode if specified)',
                 },
                 maxFilesPerStep: {
                     type: 'number',
-                    description: 'Maximum files per step to return (default: 20, max: 50)',
-                    default: 20,
+                    description: 'Advanced: Maximum files per step to return (overrides responseMode if specified)',
                 },
                 maxFileSize: {
                     type: 'number',
-                    description: 'Maximum characters per file (default: 10000, max: 50000)',
-                    default: 10000,
+                    description: 'Advanced: Maximum characters per file (overrides responseMode if specified)',
                 },
                 stepSelectionStrategy: {
                     type: 'string',
                     enum: ['complete', 'adjacent'],
-                    description: 'Step selection strategy (default: "complete"). Use "complete" to get ALL steps in the recipe (best for starters/scaffolds). Use "adjacent" for minimal context (matched + setup + nearby steps only).',
-                    default: 'complete',
+                    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.1.0",
+  "version": "1.2.0",
   "description": "MCP client bridge for Razroo Code Validation API",
   "type": "module",
   "bin": {