valentin-harrang/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:

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

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

{
  success: boolean;
  message: string;
  feature: string;
  created: string[];
}

validate_architecture

Parameters:

• targetDir (optional): Directory to validate (default: current directory)

Returns:

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

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