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.

🤔 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

# 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

# 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)

uv sync

Option B: With pip

pip install fastmcp

3. Verify installation

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:

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

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

Logs don't appear

Change the log level in claude_desktop_config.json:

"env": {
  "FRD_ORCH_LOG_LEVEL": "DEBUG"
}

Python not found

If using uv:

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