---
description: SmartStack MCP Integration Guide
---

# SmartStack MCP Integration

This document describes how SmartStack CLI commands integrate with the **SmartStack MCP Server** for consistent, structured operations across all development environments.

---

## Overview

The SmartStack MCP Server provides four main tools:

| MCP Tool | CLI Commands Using It | Purpose |
|----------|----------------------|---------|
| `validate_conventions` | `/validate` | Check naming conventions |
| `check_migrations` | `/efcore:conflicts`, `/efcore:scan`, `/efcore:db-status` | Migration analysis |
| `scaffold_extension` | `/controller:create`, `/application:create` | Code generation |
| `api_docs` | (future) `/docs:api` | API documentation |

---

## MCP Tools Reference

### 1. validate_conventions

**Description:** Validate SmartStack conventions for SQL schemas, table prefixes, migration naming, service interfaces, and namespace structure.

**Parameters:**

```typescript
{
  path?: string;           // Project path (default: auto-detect)
  checks: Array<'tables' | 'migrations' | 'services' | 'namespaces' | 'all'>;
}
```

**Response:**

```typescript
interface ValidationResult {
  valid: boolean;
  errors: ValidationIssue[];
  warnings: ValidationIssue[];
  summary: string;
}
```

**Used by:** `/validate`, `/validate:tables`, `/validate:migrations`, etc.

---

### 2. check_migrations

**Description:** Analyze EF Core migrations for conflicts, ordering issues, and ModelSnapshot discrepancies between branches.

**Parameters:**

```typescript
{
  projectPath?: string;    // EF Core project path
  branch?: string;         // Git branch to check (default: current)
  compareBranch?: string;  // Branch to compare against
}
```

**Response:**

```typescript
interface MigrationCheckResult {
  hasConflicts: boolean;
  migrations: MigrationInfo[];
  conflicts: MigrationConflict[];
  suggestions: string[];
}

interface MigrationInfo {
  name: string;
  context: string;      // core, extensions
  version: string;      // 1.0.0, 1.2.0
  sequence: string;     // 001, 002
  description: string;
  file: string;
  applied: boolean;
}

interface MigrationConflict {
  type: 'order' | 'snapshot' | 'dependency' | 'naming';
  description: string;
  files: string[];
  resolution: string;
}
```

**Used by:** `/efcore:conflicts`, `/efcore:scan`, `/efcore:db-status`

---

### 3. scaffold_extension

**Description:** Generate code to extend SmartStack: services, entities, controllers, or React components.

**Parameters:**

```typescript
{
  type: 'service' | 'entity' | 'controller' | 'component';
  name: string;          // e.g., "UserProfile", "Order"
  options?: {
    namespace?: string;
    baseEntity?: string;
    methods?: string[];
    outputPath?: string;
  }
}
```

**Response:**

```typescript
interface ScaffoldResult {
  success: boolean;
  files: GeneratedFile[];
  instructions: string[];
}

interface GeneratedFile {
  path: string;
  content: string;
  type: 'created' | 'modified';
}
```

**Used by:** `/controller:create`, `/application:create`

---

### 4. api_docs

**Description:** Get API documentation from Swagger/OpenAPI or by parsing controller files.

**Parameters:**

```typescript
{
  endpoint?: string;     // Filter by path, e.g., "/api/users"
  format?: 'markdown' | 'json' | 'openapi';
  controller?: string;   // Filter by controller name
}
```

**Used by:** Future `/docs:api` command

---

## Convention Alignment

### Migration Naming

Both CLI and MCP use the same format:

```
{context}_v{version}_{sequence}_{Description}
```

| Component | Values | Example |
|-----------|--------|---------|
| context | `core`, `extensions` | `core` |
| version | Semver | `1.2.0` |
| sequence | 3-digit | `001` |
| Description | PascalCase | `AddUserRoles` |

**Full example:** `core_v1.2.0_001_AddUserRoles`

### Table Prefixes

Valid prefixes enforced by `validate_conventions`:

- `auth_` - Authentication
- `nav_` - Navigation
- `usr_` - User data
- `ai_` - AI features
- `cfg_` - Configuration
- `wkf_` - Workflow
- `support_` - Support
- `entra_` - Entra ID
- `ref_` - Reference data
- `loc_` - Localization
- `lic_` - Licensing

### Service Pattern

```
Interface:      I{Name}Service
Implementation: {Name}Service
```

### Namespaces

```
SmartStack.Domain.*
SmartStack.Application.*
SmartStack.Infrastructure.*
SmartStack.Api.*
```

---

## Command to MCP Mapping

### /efcore:conflicts

```
1. Get current branch
2. CALL mcp__smartstack__check_migrations({
     branch: currentBranch,
     compareBranch: "develop"
   })
3. Display conflicts from response
4. Exit 1 if hasConflicts is true
```

### /efcore:scan

```
1. List all worktrees
2. FOR each branch:
   CALL mcp__smartstack__check_migrations({
     branch: branchName,
     compareBranch: "develop"
   })
3. Aggregate results
4. Calculate merge order by risk level
5. Display summary
```

### /validate

```
1. CALL mcp__smartstack__validate_conventions({
     checks: ["all"]
   })
2. Display errors and warnings
3. Exit 1 if not valid
```

### /controller:create

```
1. Parse arguments (area, module, entity)
2. CALL mcp__smartstack__scaffold_extension({
     type: "controller",
     name: moduleName,
     options: { namespace: "SmartStack.Api.Controllers.{area}" }
   })
3. Write generated files
4. Add permissions
5. Create migration if needed
```

---

## Benefits of MCP Integration

1. **Single Source of Truth**
   - Convention rules defined once in MCP config
   - No duplication between CLI and other tools

2. **Consistency**
   - Same logic in CLI, CI/CD, IDE
   - Identical results everywhere

3. **Structured Output**
   - Typed responses instead of text parsing
   - Easier automation and scripting

4. **Maintainability**
   - Update logic in one place (MCP)
   - All commands automatically benefit

5. **Extensibility**
   - Add new checks/features in MCP
   - Available to all consumers immediately

---

## CI/CD Integration

```yaml
# GitHub Actions example
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate conventions
        run: |
          OUTPUT=$(claude-code "/validate --json")
          if [ "$(echo $OUTPUT | jq '.valid')" != "true" ]; then
            echo "::error::Convention violations detected"
            exit 1
          fi

      - name: Check migration conflicts
        run: |
          OUTPUT=$(claude-code "/efcore:conflicts --json")
          if [ "$(echo $OUTPUT | jq '.hasConflicts')" = "true" ]; then
            echo "::error::Migration conflicts detected"
            exit 1
          fi
```

---

## Fallback Behavior

When MCP is unavailable, commands fall back to:

1. **Local bash scripts** for simple operations
2. **Manual template generation** for scaffolding
3. **Warning message** indicating degraded mode

To check MCP availability:

```bash
# MCP health check
claude-code --mcp-status smartstack
```
