# 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

```bash
npm install -g konnexx-dev-mcp
```

### Step 2: Configure Cursor

Open **Cursor Settings** → **Features** → **MCP** and add:

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

```bash
# 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

```bash
npm install -g konnexx-dev-mcp
```

**Cursor Config:**
```json
{
  "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:**
```bash
npm install -g konnexx-dev-mcp
```

**Cursor Config:**
```json
{
  "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

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

**Cursor Config:**
```json
{
  "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):**
```bash
# 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):**
```bash
# 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](./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:**
```bash
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:**
   ```bash
   npm list -g konnexx-dev-mcp
   ```

2. **Verify command exists:**
   ```bash
   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:**
   ```bash
   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](./docs/GETTING_STARTED.md)** - **Complete setup guide** - Installation, configuration, and basic usage
- **[docs/USAGE.md](./docs/USAGE.md)** - **How to use commands** - Detailed guide on using commands in your projects
- **[docs/QUICK_REFERENCE.md](./docs/QUICK_REFERENCE.md)** - Daily usage cheat sheet

### 📖 For Team Leads
- **[docs/SETUP.md](./docs/SETUP.md)** - Initial setup and publishing to npm
- **[docs/PUBLISHING_WORKFLOW.md](./docs/PUBLISHING_WORKFLOW.md)** - Complete guide: How to update commands and publish new versions

### 🔍 For Developers
- **[docs/BEST_PRACTICES_REVIEW.md](./docs/BEST_PRACTICES_REVIEW.md)** - Code review and best practices
- **[docs/COMPREHENSIVE_ASSESSMENT.md](./docs/COMPREHENSIVE_ASSESSMENT.md)** - Complete codebase assessment
- **[docs/COMMANDS_REVIEW.md](./docs/COMMANDS_REVIEW.md)** - Commands directory structure review
- **[docs/FIXES_APPLIED.md](./docs/FIXES_APPLIED.md)** - Summary of fixes and improvements

### 📝 Reference
- **[docs/README.md](./docs/README.md)** - Documentation index
- **[CHANGELOG.md](./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](./docs/USAGE.md) for complete usage instructions!