# Change Risk Assessor MCP Server

Autonomous Model Context Protocol server for code change risk assessment with ultra-low token budget (50-100 tokens).

## Installation

### Global Install

```bash
npm install -g mcp-change-risk-assessor
```

### Using npx (No Install)

```bash
npx mcp-change-risk-assessor
```

## Purpose

Provides a single MCP tool (`assess_change_risk`) that evaluates code changes and returns structured risk metadata for consumption by AI agents in IDEs.

**Key Features:**
- ✅ No API keys required
- ✅ Works offline
- ✅ Ultra-low token budget (50-100 tokens)
- ✅ 8-word reasoning limit
- ✅ 10-word advice limit
- ✅ Classification-based (not prose-based)

## Usage

### MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Cursor, Cline):

**Using npx (recommended):**

```json
{
  "mcpServers": {
    "change-risk-assessor": {
      "command": "npx",
      "args": ["-y", "mcp-change-risk-assessor"]
    }
  }
}
```

**If installed globally:**

```json
{
  "mcpServers": {
    "change-risk-assessor": {
      "command": "mcp-change-risk-assessor"
    }
  }
}
```

### Tool Interface

**Tool Name:** `assess_change_risk`

**Input Schema:**
```json
{
  "diff": "string (optional)",
  "files_changed": ["array of strings (optional)"],
  "language": "string (optional)",
  "context_hint": "string (optional)"
}
```

**Output Schema:**
```json
{
  "risk_level": "low | medium | high",
  "risk_types": ["data_loss", "auth", "perf", "breaking_change", "infra", "unknown"],
  "confidence": 0.0,
  "reasoning": "max 8 words, fragments only",
  "agent_advice": "max 10 words, imperative"
}
```

**Reasoning Examples:**
- `"auth logic changed, rollback unclear"`
- `"schema mutation, irreversible"`
- `"refactor only, no behavior delta"`

**Advice Examples:**
- `"run full test suite before deploy"`
- `"verify rollback plan exists"`
- `"standard review, check build"`

## Architecture

This MCP server acts as a **pure tool definition** that relies entirely on the host IDE's built-in LLM (Claude Code, Cursor, etc.) to perform risk analysis.

### Ultra-Low Token Budget

**Token Target:** 50-100 tokens per invocation  
**Reasoning Limit:** 8 words maximum  
**Advice Limit:** 10 words maximum  

The server enforces strict word limits to minimize token usage while preserving classification accuracy.

### Responsibility Split

**The MCP Server:**
- Defines the tool name and classification framework
- Enforces strict word limits (8 words reasoning, 10 words advice)
- Validates and normalizes output schema
- Truncates overlong responses

**The Host IDE's LLM:**
- Reads the tool description
- Classifies risk immediately (single-pass, no chain-of-thought)
- Returns fragmented reasoning (no full sentences)
- Provides imperative advice (no explanations)

### No External Dependencies

✅ No API keys required  
✅ No external LLM calls  
✅ No network requests  
✅ No configuration needed  
✅ Works offline  

### Classification Approach

**Classification over explanation:**
- Immediate risk judgment (HIGH/MEDIUM/LOW)
- Fragmented reasoning only (≤8 words)
- Bounded vocabulary (no file descriptions, no diff repetition)
- Single-pass judgment (no step-by-step reasoning)

### Risk Classification

**High Risk**
- Irreversible data changes
- Auth/security logic modifications
- Infrastructure changes
- Breaking external contracts

**Medium Risk**
- Behavior changes with unclear test coverage
- Configuration or dependency updates
- Performance-sensitive logic modifications

**Low Risk**
- Comments only
- Formatting changes
- Renames without behavior change
- Test-only changes
- Refactors with no semantic delta

## How It Works

```javascript
// 1. IDE detects code change and calls the MCP tool
{
  "diff": "- const user = getUser()\n+ const user = await getUser()",
  "files_changed": ["src/auth/login.js"],
  "context_hint": "pre-commit"
}

// 2. Host IDE's LLM reads the tool description and analyzes the change
// (The MCP server does NOT perform this analysis)

// 3. Host IDE's LLM generates assessment following the schema

// 4. MCP server validates and normalizes the output
{
  "risk_level": "medium",
  "risk_types": ["auth"],
  "confidence": 0.65,
  "reasoning": "auth logic changed, async pattern",
  "agent_advice": "verify test coverage, check integration impacts"
}
```

## Design Philosophy

- Pure MCP tool definition
- No external LLM calls or API keys
- Analysis performed by host IDE's LLM
- Schema validation and normalization only
- No data persistence or state
- Deterministic output schema
- Machine-readable output only
- Autonomous operation in IDE context
- Works offline