---
name: mcp
description: |
  MCP server management and health check for SmartStack.
  Use this skill when:
  - User wants to check MCP status
  - User mentions "mcp", "healthcheck", "mcp status"
  - Before any MCP-dependent operation fails
  - After MCP configuration changes
  Subcommands: healthcheck, tools
model: haiku
allowed-tools: Read, Bash, Glob
---

## Current state (auto-injected)
- MCP cache: !`cat .claude/mcp-status.json 2>/dev/null || echo "no cache"`

# Skill MCP SmartStack

Manages MCP server connectivity and health verification.

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

## SUBCOMMANDS

| Command | Description |
|---------|-------------|
| `/mcp:healthcheck` | Full MCP health check with version verification |
| `/mcp:tools` | List all available MCP tools with descriptions |

---

## /mcp:healthcheck

Performs a complete MCP health check and updates the cache.

### Workflow

```
┌─────────────────────────────────────────────────────────────┐
│                    MCP HEALTH CHECK                         │
├─────────────────────────────────────────────────────────────┤
│  1. Test MCP Connectivity                                   │
│     └─▶ Call mcp__smartstack__validate_conventions          │
│                                                             │
│  2. Get MCP Version                                         │
│     └─▶ smartstack --version (bundled in CLI)               │
│                                                             │
│  3. List Available Tools                                    │
│     └─▶ Enumerate mcp__smartstack__* tools                  │
│                                                             │
│  4. Update Cache                                            │
│     └─▶ Write .claude/mcp-status.json                       │
└─────────────────────────────────────────────────────────────┘
```

### Step 1: Test Connectivity

Call MCP with minimal parameters:

```
mcp__smartstack__validate_conventions({
  checks: ["tables"]
})
```

**Expected:** Response without connection error

**On failure:**
```
❌ MCP CONNECTION FAILED
   Error: <error_message>

   Actions:
   1. Verify MCP is configured: claude mcp list
   2. Re-register: claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
   3. Restart Claude Code
```

### Step 2: Get Version

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

### Step 3: List Tools

Verify these critical tools are available:

| Tool | Purpose |
|------|---------|
| `validate_conventions` | Convention validation |
| `scaffold_extension` | Code generation |
| `suggest_migration` | Migration naming |
| `check_migrations` | Conflict detection |
| `generate_permissions` | RBAC generation |

### Step 4: Update Cache

Write to `.claude/mcp-status.json`:

```json
{
  "lastCheck": "<ISO_DATE>",
  "mcpVersion": "<VERSION>",
  "bundled": true,
  "status": "ok",
  "toolsAvailable": [
    "validate_conventions",
    "scaffold_extension",
    "suggest_migration",
    "check_migrations",
    "generate_permissions"
  ]
}
```

### Output Format

**Success:**
```
MCP HEALTH CHECK ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Status      : OK
  Version     : 2.0.0 (bundled)
  Tools       : 19 available
  Cache       : Updated (.claude/mcp-status.json)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Next check  : in 7 days (auto)
```

**Warning (update available):**
```
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

  Troubleshooting:
  1. Check registration: claude mcp list
  2. Re-register: claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
  3. Update CLI: npm update -g @atlashub/smartstack-cli
  4. Restart Claude Code
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Cache File

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

**Structure:**
```json
{
  "lastCheck": "2024-01-15T10:30:00.000Z",
  "mcpVersion": "2.0.0",
  "bundled": true,
  "status": "ok" | "error",
  "toolsAvailable": ["tool1", "tool2", ...],
  "errors": ["error1", ...] // only if status = error
}
```

**Validity:** 7 days

---

## Integration with Hook

The `mcp-check` hook automatically:
1. Reads this cache before any `mcp__smartstack__*` call
2. Displays warning if cache > 7 days
3. Blocks if last status was "error"

This skill provides the **full check** that the hook references.

---

## /mcp:tools

Lists all available MCP tools with their descriptions.

### Core Tools (6)
| Tool | Description |
|------|-------------|
| `validate_conventions` | Validate SmartStack conventions (tables, migrations, services, namespaces, controllers) |
| `check_migrations` | Analyze EF Core migrations for conflicts and ordering issues |
| `scaffold_extension` | Generate code: feature, entity, service, controller, component, dto, validator, repository |
| `api_docs` | Get API documentation from Swagger/OpenAPI or controller files |
| `suggest_migration` | Suggest migration name following SmartStack conventions |
| `generate_permissions` | Generate RBAC permissions (HasData for PermissionConfiguration.cs) |

### Test Tools (4)
| Tool | Description |
|------|-------------|
| `scaffold_tests` | Generate test files for entities, services, controllers |
| `analyze_test_coverage` | Analyze test coverage and identify missing tests |
| `validate_test_conventions` | Validate test naming and structure conventions |
| `suggest_test_scenarios` | Suggest test scenarios based on code analysis |

### Frontend Tools (5)
| Tool | Description |
|------|-------------|
| `scaffold_routes` | Generate frontend routes from backend NavRoute attributes |
| `validate_frontend_routes` | Validate frontend routes match backend NavRoutes |
| `scaffold_api_client` | Generate TypeScript API client with React Query hooks |
| `scaffold_frontend_extension` | Generate frontend extension infrastructure (types, slots, contexts) |
| `analyze_extension_points` | Analyze React components for extension points |

### Security & Quality Tools (4)
| Tool | Description |
|------|-------------|
| `validate_security` | Validate OWASP security patterns |
| `analyze_code_quality` | Analyze code quality metrics |
| `analyze_hierarchy_patterns` | Analyze entity hierarchy patterns |
| `review_code` | Comprehensive code review with security, performance, a11y checks |

### Output Format

```
MCP TOOLS REFERENCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CORE TOOLS (6)
  validate_conventions    Validate SmartStack conventions
  check_migrations        Analyze EF Core migrations
  scaffold_extension      Generate code (entity, service, etc.)
  api_docs                Get API documentation
  suggest_migration       Suggest migration name
  generate_permissions    Generate RBAC permissions

TEST TOOLS (4)
  scaffold_tests          Generate test files
  analyze_test_coverage   Analyze test coverage
  validate_test_conventions  Validate test conventions
  suggest_test_scenarios  Suggest test scenarios

FRONTEND TOOLS (5)
  scaffold_routes         Generate frontend routes
  validate_frontend_routes  Validate route alignment
  scaffold_api_client     Generate TypeScript API client
  scaffold_frontend_extension  Generate extension infrastructure
  analyze_extension_points  Analyze React extension points

SECURITY & QUALITY TOOLS (4)
  validate_security       Validate OWASP patterns
  analyze_code_quality    Analyze code quality
  analyze_hierarchy_patterns  Analyze hierarchy patterns
  review_code             Comprehensive code review

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total: 19 tools available
```
