# FRD Orchestrator - MCP Server

🚀 **Automated NestJS boilerplate generation powered by MCP and structured FRDs**

MCP (Model Context Protocol) server that exposes NestJS boilerplate FRDs so **GitHub Copilot** can regenerate the complete architecture from scratch in any project, following **Clean Architecture, SOLID principles, and best practices**.

![mcp-vscode](https://github.com/user-attachments/assets/fc066845-38e9-468d-90b2-1969316a31bd)

## 🤔 What is MCP and why use it?

**MCP (Model Context Protocol)** is a standardized way for AI assistants like **GitHub Copilot** to access external tools and data sources. Think of it as a "bridge" that allows Copilot to:

- 📖 **Read live documents** (your FRDs) instead of outdated copies
- 🔧 **Access specialized tools** beyond basic file operations  
- 📊 **Get structured data** with validation and logging
- 🔄 **Always stay updated** - changes to FRDs are immediately available

### Why FRDs via MCP instead of just reading files?

| Traditional File Reading | MCP + FRDs |
|-------------------------|------------|
| ❌ Stale content when files change | ✅ Always fresh content |
| ❌ No validation or error handling | ✅ Built-in validation and logging |
| ❌ Manual file path management | ✅ Structured ID-based access |
| ❌ No usage tracking | ✅ Full audit trail of what was read |

## 🎯 What does this server do?

This MCP server exposes **5 carefully crafted FRDs** that define a complete NestJS boilerplate:

- **FRD-00**: 🎭 **Master orchestration** - How GitHub Copilot should execute the 4 phases
- **FRD-01**: 🏗️ **Boilerplate core** - Basic NestJS + Products CRUD + Swagger
- **FRD-02**: 🗄️ **Database layer** - TypeORM + migrations + repository pattern
- **FRD-03**: 🔐 **Authentication** - JWT + Passport + protected endpoints
- **FRD-04**: 🧪 **Unit testing** - Jest + mocks + coverage for all modules

## 🔄 How does the orchestration work?

When you tell GitHub Copilot to generate a boilerplate, here's what happens:

1. **📋 Copilot reads FRD-00** (master orchestration) to understand the plan
2. **🏗️ Phase 1**: Reads FRD-01 → Creates basic NestJS + Products CRUD
3. **🗄️ Phase 2**: Reads FRD-02 → Adds database + TypeORM + migrations
4. **🔐 Phase 3**: Reads FRD-03 → Implements JWT auth + protected routes
5. **🧪 Phase 4**: Reads FRD-04 → Generates unit tests for everything
6. **📝 Final**: Generates comprehensive README with setup instructions

Each phase is **automatic** - no manual intervention required. GitHub Copilot follows the FRDs religiously and ensures each phase works before moving to the next.

## ✨ Complete workflow example

```bash
# 1. You say this to GitHub Copilot:
"folder name: my-api. Start the orchestration."

# 2. GitHub Copilot automatically:
# - Reads FRD-00 to understand the plan
# - Creates `my-api/` directory
# - Executes Phase 1: Basic NestJS setup
# - Executes Phase 2: Database integration  
# - Executes Phase 3: JWT authentication
# - Executes Phase 4: Unit tests
# - Generates final README

# 3. Result: Complete production-ready API with:
# ✅ Products CRUD with validation
# ✅ Swagger documentation at /api
# ✅ Database persistence (SQLite by default)
# ✅ JWT authentication protecting all routes
# ✅ Unit tests with >80% coverage
# ✅ Clean Architecture + SOLID principles
# ✅ Complete setup documentation
```

The entire process takes **5-10 minutes** and results in a **production-ready** NestJS API that you can deploy immediately.

## Requirements

- **Python 3.10+**
- **VS Code** with **GitHub Copilot** enabled
- **uv** (recommended) or `pip`

## Installation

### 1. Clone/Copy this folder to your project

```bash
# Add this MCP server to your existing project
git clone <your-repo> mcp-server
cd mcp-server
```

### 2. Install dependencies

**Option A: With uv (recommended)**

```bash
uv sync
```

**Option B: With pip**

```bash
pip install fastmcp
```

### 3. Verify installation

```bash
python main.py
```

You should see logs like:
```
[FRD-Orchestrator] 12:34:56 | INFO | Starting MCP FRD-Orchestrator server (stdio)
[FRD-Orchestrator] 12:34:56 | INFO | FRD Directory: /path/to/mcp-server/frd
```

## VS Code + GitHub Copilot Configuration

### 1. Create MCP configuration in your workspace

Create `.vscode/mcp.json` in your project root:

```json
{
  "_note": "This configuration is for academic purposes. The command path depends on the execution environment and may vary based on where the UV tool is installed on different systems.",
  "servers": {
    "frd-orchestrator": {
      "type": "stdio", 
      "command": "/Users/[your-username]/.local/bin/uv",
      "args": ["run", "main.py"]
    }
  }
}
```

**⚠️ Important:**
- Adjust the **path to UV** according to your system
- Use `which uv` to find your UV installation path
- If using Python directly: `"command": "python"` and `"args": ["main.py"]`

### 2. Ensure GitHub Copilot has MCP access

GitHub Copilot in VS Code automatically detects MCP servers configured in `.vscode/mcp.json` when MCP support is enabled.

### 3. Test the connection

Open VS Code in your project and ask GitHub Copilot:
```
"Show me what's available in FRD-00"
```

If working correctly, you'll see logs in the terminal and Copilot will access the FRD content.

## Usage

Once configured, GitHub Copilot automatically has access to the `get_frd` tool and can read all FRDs on demand.

### 🎯 Simple commands to get started:

```
"folder name: my-awesome-api. Start the orchestration."
```

That's it! GitHub Copilot will:
1. Create the folder
2. Read all FRDs automatically 
3. Execute all 4 phases in sequence
4. Generate a complete, working API

### 🛠️ Advanced usage:

```
"Generate just the core boilerplate (Phase 1 only)"
"Add database layer following FRD-02" 
"Implement JWT authentication according to FRD-03"
"Generate comprehensive unit tests per FRD-04"
"Show me what FRD-01 contains"
```

### 🔍 Behind the scenes:

When GitHub Copilot executes, you'll see logs like:
```
[FRD-Orchestrator] Reading FRD from disk: /path/to/frd/FRD-01-boilerplate-core-products.md
[FRD-Orchestrator] Tool get_frd requested with frd_id=01
[FRD-Orchestrator] FRD read successfully: FRD-01-boilerplate-core-products.md (15,432 characters)
```

This means GitHub Copilot is actively reading the latest version of your FRDs and following them exactly.

### ⚡ What makes this powerful:

- **🎯 Zero configuration** - Just one command and everything works
- **📋 Structured approach** - Each phase builds on the previous
- **🔄 Always updated** - FRDs are read fresh every time
- **🏗️ Production ready** - Not just demos, real deployable code
- **📚 Self-documenting** - Generated README explains everything
- **🧪 Fully tested** - Unit tests included for all modules

## File structure

```
mcp-server/
├── main.py                          # MCP Server
├── README.md                        # This file
├── pyproject.toml                   # Dependencies (create if not exists)
└── frd/
    ├── FRD-00-master-orchestration.md
    ├── FRD-01-boilerplate-core-products.md
    ├── FRD-02-products-database.md
    ├── FRD-03-auth-security.md
    └── FRD-04-unit-testing.md
```

## Troubleshooting

### Claude doesn't recognize the `get_frd` tool

1. Verify that Claude Desktop is restarted
2. Check logs in:
   - **macOS:** `~/Library/Logs/Claude/mcp*.log`
   - **Windows:** `%APPDATA%\Claude\logs\`
3. Make sure to use absolute paths in `claude_desktop_config.json`

### Error: `FRD_DIR does not exist`

The `frd/` directory must be next to `main.py`:

```bash
ls -la mcp-server/
# Should show: main.py, frd/
```

### Logs don't appear

Change the log level in `claude_desktop_config.json`:

```json
"env": {
  "FRD_ORCH_LOG_LEVEL": "DEBUG"
}
```

### Python not found

If using `uv`:

```json
{
  "command": "uv",
  "args": ["run", "/absolute/path/to/mcp-server/main.py"]
}
```

## Environment variables

| Variable | Description | Default |
|----------|-------------|---------|
| `FRD_ORCH_LOG_LEVEL` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |

## Portability

This directory is **100% portable**. To use in another project:

1. Copy the entire `mcp-server/` folder
2. Update the path in `claude_desktop_config.json`
3. Restart Claude Desktop
4. Ready ✅

## Update FRDs

To modify an FRD:

1. Edit the file in `frd/*.md`
2. It's **not** necessary to restart the server
3. The next time Jarvis calls `get_frd`, it will get the updated version

---

**Author:** @jorgegomez  
**Version:** 1.0.0  
**Date:** December 2025