Clean Architecture MCP Server

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)

# 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

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

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

Or if globally installed:

{
  "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

# 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

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:

npm publish

Then users can install globally:

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
• MCP SDK Documentation
• Clean Architecture

---

Made with ❤️ for Clean Architecture enthusiasts