# Clean Architecture MCP Server

**Model Context Protocol Server** for scaffolding and managing Clean Architecture in Next.js projects.

## 🎯 Features

This MCP Server provides 3 powerful tools:

1. **`initialize_clean_architecture`** - Set up complete Clean Architecture structure
2. **`create_feature`** - Generate new features with all layers
3. **`validate_architecture`** - Check for architecture violations

## 🚀 Installation

### Option 1: Global Installation (Recommended)

```bash
# From the mcp-server directory
cd mcp-server
npm install
npm run build
npm link

# Now available globally as 'clean-architecture-mcp'
```

### Option 2: Local Installation

```bash
cd mcp-server
npm install
npm run build
```

## ⚙️ Configuration

### For Cursor/Claude Desktop

Add to your MCP configuration file:

**Mac/Linux:** `~/.config/cursor/mcp.json` or `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows:** `%APPDATA%\Cursor\mcp.json` or `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "clean-architecture": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"]
    }
  }
}
```

Or if globally installed:

```json
{
  "mcpServers": {
    "clean-architecture": {
      "command": "clean-architecture-mcp"
    }
  }
}
```

### Restart Cursor/Claude

After configuration, restart Cursor or Claude Desktop to load the MCP server.

## 📚 Usage

### Tool 1: Initialize Architecture

Initialize Clean Architecture in your Next.js project:

**In Cursor chat:**
```
Use the clean-architecture MCP server to initialize the project structure
```

**With parameters:**
```
Use clean-architecture to initialize with features: products, orders, customers
```

**What it does:**
- ✅ Creates complete directory structure
- ✅ Adds .gitkeep files
- ✅ Creates README.md in each layer
- ✅ Updates tsconfig.json paths
- ✅ Sets up domain/infra/components/tests folders

### Tool 2: Create Feature

Generate a complete feature:

**In Cursor chat:**
```
Use clean-architecture to create a "products" feature
```

**What it creates:**
```
src/domain/products/
├── models/product.ts              # Zod schema
├── business-rules/                # Pure business logic
├── services/product-service.ts    # Use cases
└── ports/product-repository.ts    # Interface

src/infra/adapters/
└── product-repository.prisma.ts   # Implementation

src/app/api/products/
├── route.ts                       # GET, POST
└── [id]/route.ts                  # GET, DELETE
```

### Tool 3: Validate Architecture

Check for architecture violations:

**In Cursor chat:**
```
Use clean-architecture to validate the project
```

**What it checks:**
- ❌ Next.js imports in domain layer
- ❌ React imports in domain layer
- ❌ Direct Prisma imports in domain
- ⚠️  Missing ports/interfaces
- ⚠️  Missing tests

**Output:**
```json
{
  "success": true,
  "score": 100,
  "issues": [],
  "warnings": [],
  "message": "✅ Architecture validation passed!"
}
```

## 🎨 Examples

### Example 1: New Project Setup

```
User: Initialize Clean Architecture in this Next.js project with features: users, products, orders

AI: [Uses initialize_clean_architecture tool]

Result:
✅ Created 45 directories
✅ Created 6 README files
✅ Updated tsconfig.json
✅ Ready to develop!
```

### Example 2: Create Feature

```
User: Create a "products" feature with fields: name, price, stock

AI: [Uses create_feature tool with featureName: "products"]

Result:
✅ Created models/product.ts
✅ Created business rules
✅ Created service layer
✅ Created repository port
✅ Created Prisma adapter
✅ Created API routes
```

### Example 3: Validate

```
User: Check if my architecture follows Clean Architecture principles

AI: [Uses validate_architecture tool]

Result:
❌ Found 2 issues:
  - src/domain/users/services/create-user.ts: Contains Next.js import
  - src/domain/products/models/product.ts: Direct Prisma import

Score: 60/100
```

## 🛠️ Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode (during development)
npm run dev

# Test the server
node dist/index.js
```

## 📋 Tool Reference

### initialize_clean_architecture

**Parameters:**
- `targetDir` (optional): Target directory (default: current directory)
- `features` (optional): Array of feature names (default: `['users', 'auth', 'payments']`)

**Returns:**
```typescript
{
  success: boolean;
  message: string;
  created: number;
  directories: string[];
  features: string[];
}
```

### create_feature

**Parameters:**
- `featureName` (required): Feature name in kebab-case
- `targetDir` (optional): Target directory (default: current directory)
- `fields` (optional): Custom model fields

**Returns:**
```typescript
{
  success: boolean;
  message: string;
  feature: string;
  created: string[];
}
```

### validate_architecture

**Parameters:**
- `targetDir` (optional): Directory to validate (default: current directory)

**Returns:**
```typescript
{
  success: boolean;
  score: number;
  issues: string[];
  warnings: string[];
  message: string;
}
```

## 🔧 Troubleshooting

### MCP Server not appearing in Cursor

1. Check configuration file path
2. Verify absolute path to `dist/index.js`
3. Restart Cursor completely
4. Check Cursor logs: `Help > Show Logs`

### "Command not found" error

If globally installed:
```bash
npm link
# Verify
which clean-architecture-mcp
```

### TypeScript errors

```bash
npm run build
# Check for compilation errors
```

### Tool execution fails

Check that you're in a Next.js project directory with `package.json`.

## 📦 Publishing

To publish to npm:

```bash
npm publish
```

Then users can install globally:

```bash
npm install -g clean-architecture-mcp-server
```

## 🤝 Contributing

1. Add new tools in `src/index.ts`
2. Update tool schemas
3. Test with `npm run build && node dist/index.js`
4. Update this README

## 📄 License

MIT

## 🔗 Resources

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)

---

**Made with ❤️ for Clean Architecture enthusiasts**