Konnexx Development MCP Server

Centralized command server for all Konnexx projects - One npm package, works across all your Laravel, Next.js, Architecture, and Flutter projects. No more copying commands to each project!

🎯 What Is This?

This is an MCP (Model Context Protocol) server that provides standardized development workflow commands to Cursor AI. Instead of maintaining commands in each project's .cursor folder, you install this package once globally and use it everywhere.

Key Benefits:

• ✅ One install, all projects - Install globally, works everywhere
• ✅ Auto-detection - Automatically detects project type (Laravel, Next.js, Architecture, Flutter)
• ✅ Team-wide consistency - Everyone uses the same commands
• ✅ Easy updates - Update once, team gets it automatically (with remote commands)
• ✅ Version controlled - Commands stored as markdown files in Git

---

🚀 Quick Start (3 Steps)

Step 1: Install Globally

npm install -g konnexx-dev-mcp

Step 2: Configure Cursor

Open Cursor Settings → Features → MCP and add:

{
  "mcpServers": {
    "konnexx-dev": {
      "command": "konnexx-dev-mcp"
    }
  }
}

Step 3: Restart Cursor & Test

Restart Cursor completely, then in any project, type in AI chat:

Use verify_mcp_servers

That's it! The MCP server will auto-detect your project type and show relevant commands.

---

✅ Verifying Tool Access

Quick Verification (From Any Project)

Run this command from any project directory to verify installation and see expected tools:

# From the konnexx-dev-mcp package directory
npm run verify

# OR from any project (if you have the package locally)
npx konnexx-dev-mcp verify

This will:

• ✅ Check if konnexx-dev-mcp is installed globally
• ✅ Detect your project type (API, Web, Mobile, Architecture)
• ✅ Show which tools should be available
• ✅ Provide instructions for testing in Cursor

Verifying in Cursor

Method 1: Use the verify command

1. Open Cursor in your project
2. In AI chat, type: Use verify_mcp_servers
3. This will test all MCP servers and show their status

Method 2: Test a specific tool

1. Open Cursor in your project (e.g., a Laravel API project)
2. In AI chat, type: Use implement_feature
3. If the tool is available, Cursor will show it in autocomplete
4. Provide the ticket: Ticket: Add user authentication feature
5. The tool should execute and start the workflow

Method 3: Check tool list

1. Open Cursor
2. Open MCP panel (usually in the sidebar or settings)
3. Look for konnexx-dev server
4. Check the tools list - you should see tools like implement_feature, commit_pr, etc.

Troubleshooting

Tools not appearing?

• ✅ Restart Cursor completely (not just reload window)
• ✅ Check Cursor Settings → Features → MCP → konnexx-dev is configured
• ✅ Verify installation: npm list -g konnexx-dev-mcp
• ✅ Check MCP server logs in Cursor's MCP panel for errors

Project type not detected?

• ✅ For API: Ensure composer.json contains "laravel/framework" in require
• ✅ For Web: Ensure package.json contains "next" in dependencies
• ✅ For Mobile: Ensure pubspec.yaml exists in project root
• ✅ For Architecture: Ensure project path contains "architecture"

Tool executes but shows error?

• ✅ Check that command markdown files exist in the commands/ directory
• ✅ Verify MCP server can access the commands directory
• ✅ Check MCP server logs for file path issues

---

📝 Available Commands

The server automatically detects your project type and shows only relevant commands. Total: 26 commands across all project types.

How to Use Commands:

• Simply type Use {command_name} in Cursor AI chat (e.g., Use implement_feature or Use commit_pr)
• Commands are automatically available based on your project type
• No parameters needed for most commands - they'll prompt you if needed

🏗️ Architecture Projects (8 commands)

Detected when: Project path contains "architecture" or no framework detected

Command	Parameters	Description
generate_tickets	epic (string), phase (string)	Generate development tickets in batches of 5
generate_tickets_batch	epic (string), phases (array)	Generate multiple ticket batches for phases
design_erd	None	Design Entity-Relationship Diagram from requirements
extract_requirements	None	Extract and structure requirements from documentation
specify_api_endpoints	None	Specify API endpoints from requirements and ERD
create_timeline_gantt	None	Create timeline and Gantt chart
synthesize_documentation	None	Orchestrate complete architecture workflow
commit_pr	None	Commit changes and create PR

🔧 API Projects - Laravel (5 commands)

Detected when: composer.json exists + Laravel framework detected

Command	Parameters	Description
implement_feature	ticket (string, required), architecture_report (string, optional)	Full feature implementation workflow (plan → implement → review → test)
test_fix	spec (enum: "low", "default", "high", optional)	Run tests and fix failures using parallel agents
test_fix_incremental	spec (enum: "low", "default", "high", optional)	Run tests incrementally, fixing one at a time
architecture_review	None	Review code for architectural compliance (DDD, Laravel patterns)
commit_pr	None	Commit changes and create PR

🌐 Web Projects - Next.js (5 commands)

Detected when: package.json exists + Next.js dependency detected

Command	Parameters	Description
implement_feature_web	ticket (string, required)	Implement features following 7-step process (Types → Service → Hooks → Components → Screens → Routes)
test_fix_web	spec (enum: "low", "default", "high", optional)	Run tests and fix failures
test_fix_incremental_web	spec (enum: "low", "default", "high", optional)	Run tests incrementally, fixing one at a time
architecture_review_web	None	Review code for architectural compliance (Next.js patterns)
commit_pr	None	Commit changes and create PR

📱 Mobile Projects - Flutter (2 commands)

Detected when: pubspec.yaml exists

Command	Parameters	Description
implement_feature_mobile	ticket (string, required)	Implement features for Flutter applications
commit_pr	None	Commit changes and create PR

🔄 Shared Commands (7 commands)

Available in every project type:

Command	Parameters	Description
verify_mcp_servers	None	Verify all MCP servers are working (Context7, GitHub, Filesystem, Database, Browser)
clear_plans	None	Clean up Cursor plan files automatically
db_query	query (string, required)	Query database using Database MCP
docs_lookup	query (string, required)	Look up documentation using Context7 MCP
test_package	None	Test the konnexx-dev-mcp package locally (builds, creates npm link, validates)
publish_package	None	Publish konnexx-dev-mcp to npm (reviews changes, versions, builds, publishes)
commit_pr	None	Commit changes and create PR (auto-detects project type)

---

💡 How It Works

1. You open a project in Cursor (Laravel API, Next.js web app, Architecture project, etc.)
2. MCP server auto-detects project type by checking for:
   • composer.json + Laravel → API Project
   • package.json + Next.js → Web Project
   • pubspec.yaml → Mobile Project
   • Path contains "architecture" → Architecture Project
3. Server shows relevant commands - Only commands for your project type appear
4. You use commands in AI chat - Type Use implement_feature or Use commit_pr
5. Command executes - The server loads the markdown command file and Cursor executes it

🎮 How to Use Commands

Basic Usage

Simply type in Cursor AI chat:

Use {command_name}

Examples:

• Use implement_feature - Start feature implementation
• Use commit_pr - Commit and create PR
• Use verify_mcp_servers - Test MCP connectivity
• Use architecture_review - Review code architecture

Commands with Parameters

Some commands require parameters. When you use them, Cursor will prompt you:

Example:

Use implement_feature

Ticket: Add user authentication feature

Commands that need parameters:

• implement_feature - requires ticket (string)
• implement_feature_web - requires ticket (string)
• implement_feature_mobile - requires ticket (string)
• db_query - requires query (string)
• docs_lookup - requires query (string)
• generate_tickets - requires epic (string) and phase (string)
• generate_tickets_batch - requires epic (string) and phases (array)

Finding Available Commands

The MCP server automatically shows only commands relevant to your project type. To see all available commands:

1. Open Cursor AI chat
2. Type Use and Cursor will show autocomplete suggestions
3. Or check the command tables above for your project type

---

🎯 Project Auto-Detection

Detection Criteria	Project Type	Commands Available
composer.json + laravel/framework	API (Laravel)	implement_feature, test_fix, test_fix_incremental, architecture_review, commit_pr
package.json + next dependency	Web (Next.js)	implement_feature_web, test_fix_web, test_fix_incremental_web, architecture_review_web, commit_pr
pubspec.yaml exists	Mobile (Flutter)	implement_feature_mobile, commit_pr
Path contains "architecture" OR no framework detected	Architecture	generate_tickets, generate_tickets_batch, design_erd, extract_requirements, specify_api_endpoints, create_timeline_gantt, synthesize_documentation, commit_pr

Plus shared commands (verify_mcp_servers, clear_plans, db_query, docs_lookup) are available in all project types.

---

📦 Installation Options

Option 1: npm Global Install (Recommended)

Best for: Team members, production use

npm install -g konnexx-dev-mcp

Cursor Config:

{
  "mcpServers": {
    "konnexx-dev": {
      "command": "konnexx-dev-mcp"
    }
  }
}

---

Option 2: With Remote Commands (Always Up-to-Date)

Best for: Teams that want instant updates without npm republishing

Install:

npm install -g konnexx-dev-mcp

Cursor Config:

{
  "mcpServers": {
    "konnexx-dev": {
      "command": "konnexx-dev-mcp",
      "env": {
        "KONNEXX_MCP_REMOTE_SOURCE": "https://raw.githubusercontent.com/Konnexx-Software-Developers/konnexx-dev-mcp/main",
        "KONNEXX_MCP_USE_REMOTE": "true"
      }
    }
  }
}

Benefits:

• ✅ Commands fetched from GitHub on each use
• ✅ Team gets updates automatically (no npm update needed)
• ✅ Instant updates when you push to GitHub

---

Option 3: Local Development

Best for: Developing the MCP server itself

git clone https://github.com/Konnexx-Software-Developers/konnexx-dev-mcp.git
cd konnexx-dev-mcp
npm install
npm run build

Cursor Config:

{
  "mcpServers": {
    "konnexx-dev": {
      "command": "node",
      "args": ["C:\\path\\to\\konnexx-dev-mcp\\dist\\index.js"]
    }
  }
}

---

🔄 Updating Commands

For Team Leads: Publishing Updates

Quick Update (Remote Commands - Recommended):

# Edit command file
code commands/api/implement-feature.md

# Commit and push
git add commands/api/implement-feature.md
git commit -m "feat: Updated implement-feature workflow"
git push

# ✅ Team gets updates automatically!

Major Release (npm Package):

# Make changes, then:
npm version patch  # or minor/major
npm publish --access public

# Team updates with:
npm update -g konnexx-dev-mcp

Complete Guide: See docs/PUBLISHING_WORKFLOW.md for:

• Step-by-step publishing workflow
• Update methods (remote vs npm)
• Team notification templates
• Version strategy
• Troubleshooting

For Team Members: Getting Updates

If using remote commands: Updates are automatic! Just restart Cursor.

If using npm only:

npm update -g konnexx-dev-mcp
# Then restart Cursor

---

📂 Package Structure

konnexx-dev-mcp/
├── commands/              # Command markdown files
│   ├── api/              # Laravel API commands (5 files)
│   ├── architecture/     # Architecture commands (8 files)
│   ├── web/              # Next.js web commands (5 files)
│   ├── mobile/          # Flutter mobile commands (future)
│   └── shared/           # Shared utilities (5 files)
├── src/                  # MCP server source code
│   └── index.ts         # Main server implementation
├── docs/                 # Documentation
├── dist/                 # Compiled JavaScript (built)
├── package.json
└── README.md

Total: 26 command files organized by project type

---

🔧 Troubleshooting

MCP Server Not Showing in Cursor

1. Check installation:

   npm list -g konnexx-dev-mcp
   

2. Verify command exists:

   which konnexx-dev-mcp    # Mac/Linux
   where konnexx-dev-mcp    # Windows
   

3. Check Cursor settings:

   • Settings → Features → MCP
   • Verify konnexx-dev is listed
   • Check command path is correct

4. Restart Cursor completely (not just reload window)

Commands Not Loading

1. Check project type detection:

   • Verify project has proper markers (composer.json, package.json, etc.)
   • Check Cursor logs for detection messages

2. Verify command files exist:

   npm list -g konnexx-dev-mcp
   # Check if commands/ directory exists in package
   

3. Check remote source (if using remote commands):

   • Verify GitHub URL is accessible
   • Check KONNEXX_MCP_USE_REMOTE is set to "true"

Wrong Project Type Detected

• For Laravel projects: Ensure composer.json exists and contains "laravel/framework"
• For Next.js projects: Ensure package.json exists and next is in dependencies
• For Architecture projects: Ensure project path contains "architecture" or add explicit marker

---

📊 Benefits vs .cursor Files

Aspect	.cursor Files (Old)	MCP Server (This)
Installation	Copy to each project	Install once globally
Updates	Copy-paste to all projects	Update once, team gets it
Team Sync	Manual per project	Automatic (with remote)
Maintenance	4+ locations	1 central location
Versioning	Per-project Git	Centralized Git
Consistency	Varies by project	Same everywhere

---

📚 Documentation

🚀 Getting Started

• docs/GETTING_STARTED.md - Complete setup guide - Installation, configuration, and basic usage
• docs/USAGE.md - How to use commands - Detailed guide on using commands in your projects
• docs/QUICK_REFERENCE.md - Daily usage cheat sheet

📖 For Team Leads

• docs/SETUP.md - Initial setup and publishing to npm
• docs/PUBLISHING_WORKFLOW.md - Complete guide: How to update commands and publish new versions

🔍 For Developers

• docs/BEST_PRACTICES_REVIEW.md - Code review and best practices
• docs/COMPREHENSIVE_ASSESSMENT.md - Complete codebase assessment
• docs/COMMANDS_REVIEW.md - Commands directory structure review
• docs/FIXES_APPLIED.md - Summary of fixes and improvements

📝 Reference

• docs/README.md - Documentation index
• CHANGELOG.md - Version history and changes

---

🎊 What You Get

Once installed and configured:

• ✅ One install, all projects - Works across all your Laravel, Next.js, Architecture, and Flutter projects
• ✅ Auto-detection - No per-project configuration needed
• ✅ Team consistency - Everyone uses the same commands
• ✅ Easy updates - Update once, team gets it automatically
• ✅ Version controlled - Commands stored as markdown in Git
• ✅ MCP-enhanced - Commands use GitHub, Filesystem, Database, Context7 MCPs for better workflows

---

📦 Package Information

• Package Name: konnexx-dev-mcp
• Version: 1.1.0
• npm: https://www.npmjs.com/package/konnexx-dev-mcp
• GitHub: https://github.com/Konnexx-Software-Developers/konnexx-dev-mcp
• License: MIT
• Node.js: Requires 18.0.0 or higher

---

👥 Team

Created for: DinDin & Konnexx Software Developers Team
Purpose: Centralize development workflow commands across all projects
Maintainer: DinDin @ Konnexx

---

📄 License

MIT - Konnexx Software Developers

---

Ready to get started? See docs/USAGE.md for complete usage instructions!