npm package: @razroo/code-validation-mcp-client
Description: MCP client bridge for Razroo Code Validation API
Author: Razroo
Latest version: 1.4.0

# Razroo Code Validation MCP Client

**Local bridge between Claude Code and Razroo HTTP API**

## What This Does

This is a small MCP client that:
1. Runs locally on your machine
2. Connects to Claude Code via stdio (MCP protocol)
3. Forwards requests to Razroo's hosted HTTP API
4. Returns results back to Claude Code

```
Claude Code (your machine)
    ↕ stdio (MCP protocol)
MCP Client Bridge (this tool)
    ↕ HTTPS (REST API)
Razroo API Server (AWS Lambda)
    ↕
Razroo's data (Qdrant, DynamoDB, S3)
```

## Installation

### NPM Package (Recommended)

```bash
npm install -g @razroo/code-validation-mcp-client
```

### From Source

```bash
git clone https://github.com/razroo/code-validation-client
cd code-validation-client
npm install
npm run build
npm link
```

## Configuration

### 1. Get Your API Key & URL

You need these from Razroo:
- **API Key**: `rzr_abc123...` (Razroo generates this for you)
- **API URL**:
  - Production: `https://api.razroo.com/v1`
  - Development: `https://api-dev.razroo.com/v1`

### 2. Configure Claude Code

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "razroo-code-validation": {
      "command": "razroo-mcp-client",
      "env": {
        "RAZROO_API_KEY": "rzr_your_api_key_here",
        "RAZROO_API_URL": "https://api.razroo.com/v1"
      }
    }
  }
}
```

**Or if installed from source:**

```json
{
  "mcpServers": {
    "razroo-code-validation": {
      "command": "node",
      "args": ["/absolute/path/to/code-validation-client/dist/index.js"],
      "env": {
        "RAZROO_API_KEY": "rzr_your_api_key_here",
        "RAZROO_API_URL": "https://api.razroo.com/v1"
      }
    }
  }
}
```

### 3. Restart Claude Code

Close and reopen Claude Code completely.

## Usage

Once configured, Claude Code will automatically use the tools:

### Example 1: Search for Similar Code

```
You: I'm adding authentication to my Angular app. Can you search for similar patterns?

Claude: [Automatically calls search_similar_code]
I found several matching patterns! The top match is "Add Authentication" with 92% similarity.
This recipe has 4 steps:
1. Create Auth Service
2. Add Auth Guard
3. Update Routing
4. Create Login Component

Let me help you implement each step...
```

### Example 2: Get Recipe Steps

```
You: Show me all the steps for the authentication recipe

Claude: [Calls get_recipe_steps]
Here are all 4 steps in the "Add Authentication" recipe:

Step 1: Create Auth Service
- Files: auth.service.ts, auth.service.spec.ts
[Shows code]

Step 2: Add Auth Guard
- Files: auth.guard.ts, auth.guard.spec.ts
[Shows code]

...
```

### Example 3: Validate Generated Code

```
You: I just generated an auth service. Can you validate it against known patterns?

[You paste your code]

Claude: [Calls search_similar_code with your code]
Your code has 88% similarity to the "Add Authentication" pattern.
It looks good! Here are a few suggestions based on the pattern:
1. Add error handling for login failures
2. Include token refresh logic
3. Add logout method
...
```

## Available Tools

### 1. `search_similar_code`

Search for similar code patterns.

**Input:**
- `code` (required): Code snippet to search
- `framework` (optional): Filter by framework
- `language` (optional): Filter by language
- `operationType` (optional): Filter by operation type
- `limit` (optional): Number of results (default: 10)

**Output:** Array of matching patterns with scores

### 2. `get_recipe_steps`

Get all steps for a recipe.

**Input:**
- `orgId` (required): Organization ID (usually "community")
- `pathId` (required): Path/workspace ID
- `recipeId` (required): Recipe ID

**Output:** Array of steps with code files

### 3. `get_step_code_files`

Get code files for a specific step.

**Input:**
- `orgId` (required): Organization ID
- `pathId` (required): Path/workspace ID
- `recipeId` (required): Recipe ID
- `stepId` (required): Step ID

**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"

**Problem:** API key not set

**Fix:** Add `RAZROO_API_KEY` to your Claude Code config (see Configuration above)

### "401 Unauthorized"

**Problem:** Invalid API key

**Fix:**
1. Check your API key is correct
2. Verify key is active (not revoked)
3. Contact Razroo support if needed

### "429 Too Many Requests"

**Problem:** Rate limit exceeded

**Fix:**
1. Wait 1 minute for rate limit to reset
2. Upgrade to higher tier if needed
3. Reduce frequency of requests

### Tools Not Appearing in Claude Code

**Problem:** Claude Code doesn't see the tools

**Fix:**
1. Verify config file location: `~/.claude/claude_desktop_config.json`
2. Check for JSON syntax errors
3. Ensure absolute paths (not relative)
4. Restart Claude Code completely

### "Command not found: razroo-mcp-client"

**Problem:** NPM package not installed globally

**Fix:**
```bash
# If installed from source
cd code-validation-client
npm link

# Or use absolute path in config instead
```

## Development

### Run Locally

```bash
npm run build
RAZROO_API_KEY=rzr_your_key RAZROO_API_URL=https://your-api npm start
```

### Test with MCP Inspector

```bash
npx @modelcontextprotocol/inspector \
  node dist/index.js \
  --env RAZROO_API_KEY=rzr_your_key \
  --env RAZROO_API_URL=https://your-api
```

## What Users Need

✅ **API Key** - Get from Razroo
✅ **API URL** - Get from Razroo
✅ **This client** - Install via NPM
✅ **Claude Code** - Already installed

That's it! No AWS credentials, no Qdrant setup, no infrastructure.

## Cost

**For users:** FREE (client runs locally)

**For Razroo:** Usage charged based on API calls (your pricing model)

## Support

- Installation help: See README
- API issues: Contact Razroo support
- Feature requests: [GitHub Issues](https://github.com/razroo/code-validation-client/issues)

## License

MIT