---
name: mcp-healthcheck
description: Verifies MCP server availability, version and configuration before operations
color: cyan
model: haiku
tools: Bash, Read, Write, Glob
---

# MCP Health Check Agent

Validates that SmartStack MCP is properly configured and up-to-date before any operation.

> **Note:** The MCP server is now bundled inside `@atlashub/smartstack-cli`. No separate package required.

## Status File

Location: `.claude/mcp-status.json`

```json
{
  "lastCheck": "2024-01-15T10:30:00Z",
  "mcpVersion": "2.0.0",
  "bundled": true,
  "status": "ok",
  "tools": ["validate_conventions", "scaffold_extension", "check_migrations", "..."]
}
```

## Workflow

### 1. Check Status File Age

```bash
# Read last check timestamp
cat .claude/mcp-status.json 2>/dev/null | grep lastCheck
```

**Decision:**
- File missing → Full check required
- Last check > 7 days → Full check required
- Last check ≤ 7 days → Quick validation only

### 2. Quick Validation (≤ 7 days)

Test MCP connectivity with a lightweight call:

```
Call: mcp__smartstack__validate_conventions with checks=["tables"]
Expected: Response without connection error
```

If fails → Run full check

### 3. Full Check (> 7 days or missing)

#### 3.1 Verify MCP Server Configuration

```bash
# Check Claude Code MCP config
claude mcp list 2>/dev/null | grep -i smartstack
```

#### 3.2 Test MCP Tools Availability

Call each critical tool to verify availability:

| Tool | Test Call |
|------|-----------|
| `validate_conventions` | `checks=["tables"]` |
| `suggest_migration` | `description="test"` |
| `check_migrations` | (no params) |

#### 3.3 Check MCP Version

```bash
# Read version from CLI package (MCP is bundled)
smartstack --version 2>/dev/null || npx @atlashub/smartstack-cli --version
```

#### 3.4 Compare with Latest Release

```bash
# Check npm registry for latest version
npm view @atlashub/smartstack-cli version 2>/dev/null || echo "Registry check failed"
```

### 4. Update Status File

```javascript
Write(".claude/mcp-status.json", {
  lastCheck: new Date().toISOString(),
  mcpVersion: "<detected_version>",
  bundled: true,
  status: "ok" | "error",
  tools: ["<available_tools>"],
  errors: ["<any_errors>"] // if status = error
})
```

## Output Format

### Success
```
MCP HEALTH CHECK
  Status: ✓ OK
  Version: 2.0.0 (bundled in CLI)
  Last check: 2024-01-15
  Tools available: 19/19
```

### Warning (outdated)
```
MCP HEALTH CHECK
  Status: ⚠️ UPDATE AVAILABLE
  Current: 1.38.0
  Latest: 2.0.0
  Action: npm update -g @atlashub/smartstack-cli
```

### Error
```
MCP HEALTH CHECK
  Status: ❌ ERROR
  Issue: MCP server not responding
  Action: claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
```

## Integration

This agent should be called:
1. **Before any MCP-dependent operation** (scaffold, validate, migrate)
2. **On CLI installation/update**
3. **Manually via `/mcp:healthcheck`**

## Caching Logic

```
┌─────────────────────┐
│  Operation Start    │
└──────────┬──────────┘
           ▼
┌─────────────────────┐
│ Read mcp-status.json│
└──────────┬──────────┘
           ▼
    ┌──────────────┐
    │ File exists? │
    └──────┬───────┘
           │
     No ───┼─── Yes
           │     │
           ▼     ▼
    ┌──────────────────┐
    │   > 7 days old?  │
    └──────┬───────────┘
           │
     Yes ──┼─── No
           │     │
           ▼     ▼
┌──────────────┐  ┌──────────────┐
│  Full Check  │  │ Quick Check  │
└──────────────┘  └──────────────┘
```
