aiworkflow-mcp/README.md

MCP Server for BRD → Miro → Figma → Full-Stack Application Workflow

# AIWorkflow MCP Server

**Transform Business Requirements into Full-Stack Applications**

An MCP (Model Context Protocol) server that automates the complete workflow from Business Requirements Document (BRD) to production-ready full-stack applications through Miro visualization and Figma UX design.

## 🌟 Features

- **📄 BRD Parsing** - AI-powered analysis of business requirements documents
- **🎨 Miro Visualization** - Automatic creation of visual requirement boards
- **🖼️ Figma Design** - UX design generation from requirements
- **⚡ Full-Stack Generation** - Complete application code generation
- **🤖 AI-Enhanced** - Uses GPT-4/Claude for intelligent analysis
- **🔧 Customizable** - Flexible tech stack selection

## 🚀 Quick Start

**🪟 Windows Users**: Installing via npm? See [WINDOWS_NPM_INSTALL.md](./WINDOWS_NPM_INSTALL.md) first!

### Prerequisites

- Node.js 20.x or higher
- npm or pnpm
- Miro account and API access (see [SETUP_MIRO.md](./SETUP_MIRO.md))
- Figma account and API access (see [SETUP_FIGMA.md](./SETUP_FIGMA.md))
- OpenAI API key (or Anthropic API key)

### Installation

#### Option 1: Install from npm (Recommended)

```bash
npm install -g aiworkflow-mcp
```

**⚠️ Windows Users**: See [WINDOWS_NPM_INSTALL.md](./WINDOWS_NPM_INSTALL.md) for Windows-specific setup instructions.

#### Option 2: Use with npx (No Installation - Most Reliable)

No installation needed! Configure Cursor to use npx (see configuration below).

#### Option 3: Install from Source

1. **Clone and install**
   ```bash
   git clone https://github.com/srivatsanlakshmanan/aiworkflow-mcp.git
   cd aiworkflow-mcp
   npm install
   npm run build
   ```

### Configuration

Create or edit `~/.cursor/mcp.json` (Windows: `C:\Users\YourName\.cursor\mcp.json`):

#### Recommended: Using npx (Works on All Platforms)
```json
{
  "mcpServers": {
    "aiworkflow": {
      "command": "npx",
      "args": ["-y", "aiworkflow-mcp"],
      "env": {
        "MIRO_ACCESS_TOKEN": "your_token",
        "FIGMA_ACCESS_TOKEN": "your_token",
        "OPENAI_API_KEY": "your_key"
      }
    }
  }
}
```
**Why npx?** Works reliably on Windows, macOS, and Linux without path issues.

#### Alternative: If installed globally (Linux/macOS)
```json
{
  "mcpServers": {
    "aiworkflow": {
      "command": "aiworkflow-mcp",
      "env": {
        "MIRO_ACCESS_TOKEN": "your_token",
        "FIGMA_ACCESS_TOKEN": "your_token",
        "OPENAI_API_KEY": "your_key"
      }
    }
  }
}
```
**⚠️ Note**: This may not work on Windows. Use npx method above instead.

#### If installed from source:
```json
{
  "mcpServers": {
    "aiworkflow": {
      "command": "node",
      "args": ["/absolute/path/to/aiworkflow-mcp/dist/index.js"]
    }
  }
}
```

**Note**: See `.env.example` for all available environment variables.

### Restart Cursor

After configuration, completely close and reopen Cursor to load the MCP server.

## 📖 Complete Setup Guides

### API Setup

1. **Miro API Setup** - See [SETUP_MIRO.md](./SETUP_MIRO.md)
   - Create Miro app
   - Get access token
   - Enable AI features

2. **Figma API Setup** - See [SETUP_FIGMA.md](./SETUP_FIGMA.md)
   - Generate personal access token
   - Get team ID
   - Optional: Set up Figma Plugin

## 🛠️ Available MCP Tools

### 1. `parse_brd`
Parse and analyze Business Requirements Documents.

**Input:**
\`\`\`typescript
{
  source: string;              // File path or text content
  sourceType: 'file' | 'text'; // Source type
  options?: {
    includeAIAnalysis: boolean;
    extractDataModels: boolean;
    generateComponentSuggestions: boolean;
  };
}
\`\`\`

**Output:** Structured BRD data with user stories, requirements, entities, and components.

---


### 2. `create_miro_board`
Create visual Miro board from parsed BRD.

**Input:**
\`\`\`typescript
{
  brdData: ParsedBRD;  // From parse_brd tool
  options?: {
    enableAI: boolean;
    autoShare: boolean;
    generateFlowDiagrams: boolean;
    generateJourneyMaps: boolean;
  };
}
\`\`\`

**Output:** Miro board URL and structure data.

---


### 3. `convert_brd_to_miro_format`
Convert parsed BRD data into a structured format optimized for Miro boards. This tool transforms BRD data into JSON with frames, items (sticky notes, cards), and connectors that can be easily imported into Miro or used with the Miro API.

**Input:**
\`\`\`typescript
{
  brdData: ParsedBRD;  // From parse_brd tool
  options?: {
    includeConnectors: boolean;  // Include connector relationships between items
    includeColors: boolean;     // Include color coding for items based on priority/complexity
    compactMode: boolean;       // Use compact layout with more items per row
  };
}
\`\`\`

**Output:** Structured Miro board format with:
- **Frames**: Organized sections (Overview, User Stories, Requirements, Data Entities, Components, Stakeholders, Business Rules)
- **Items**: Sticky notes, cards, and text elements with proper positioning
- **Connectors**: Relationships between items (dependencies, flows, associations)
- **Layout**: Ready-to-use positioning and styling for Miro boards

**Use Case**: Perfect for preparing BRD data before creating Miro boards, or for exporting structured data that can be manually imported into Miro or processed by other tools.

---


### 4. `export_miro_data`
Export structured data from Miro board.

**Input:**
\`\`\`typescript
{
  boardId: string;  // Miro board ID
}
\`\`\`

**Output:** Structured data for Figma design generation.

---


### 5. `generate_figma_design`
Generate Figma UX design specification.

**Input:**
\`\`\`typescript
{
  miroData: MiroExportData;  // From export_miro_data
  options?: {
    includeDesignSystem: boolean;
    generateResponsive: boolean;
    createPrototype: boolean;
    componentLibrary: 'custom' | 'material-ui' | 'chakra' | 'tailwind';
  };
}
\`\`\`

**Output:** Figma design specification (JSON).

---


### 6. `select_tech_stack`
Configure technology stack for application.

**Input:**
\`\`\`typescript
{
  projectType: 'web' | 'mobile' | 'desktop' | 'fullstack';
  frontend: {
    framework: 'react' | 'vue' | 'nextjs' | ...;
    language: 'typescript' | 'javascript';
    styling: 'tailwind' | 'mui' | ...;
  };
  backend: {
    framework: 'express' | 'fastify' | 'django' | ...;
    language: 'typescript' | 'python' | ...;
    apiStyle: 'rest' | 'graphql' | ...;
  };
  database: {
    type: 'postgresql' | 'mongodb' | 'mysql' | ...;
    migrations: boolean;
  };
}
\`\`\`

**Output:** Tech stack configuration.

---


### 7. `generate_application`
Generate complete full-stack application.

**Input:**
\`\`\`typescript
{
  brdData: ParsedBRD;
  designSpec: FigmaDesignSpec;
  techStack: TechStackConfig;
  options?: {
    includeTests: boolean;
    includeDocumentation: boolean;
    includeDocker: boolean;
    gitInit: boolean;
  };
}
\`\`\`

**Output:** Complete project with all files generated.

## 💡 Usage Example

### Full Workflow in Cursor

1. **Parse BRD**
   \`\`\`
   Use parse_brd tool to analyze my BRD file at ./docs/requirements.pdf
   \`\`\`

2. **Convert to Miro Format** (Recommended)
   \`\`\`
   Use convert_brd_to_miro_format with the parsed BRD data to get structured JSON format that Miro can easily read and understand. This creates organized frames, items, and connectors.
   \`\`\`

3. **Create Miro Board**
   \`\`\`
   Use create_miro_board with the parsed BRD data (or the converted Miro format) to visualize requirements on a Miro board
   \`\`\`

4. **Generate Figma Design**
   \`\`\`
   Use export_miro_data for board [board-id], then generate_figma_design with Tailwind component library
   \`\`\`

5. **Select Tech Stack**
   \`\`\`
   Use select_tech_stack with React + TypeScript + Tailwind for frontend, Express + TypeScript for backend, and PostgreSQL for database
   \`\`\`

6. **Generate Application**
   \`\`\`
   Use generate_application with all the data to create the complete application
   \`\`\`

## 📁 Project Structure

\`\`\`
AIWorkflowMCP/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── tools/                # MCP tool implementations
│   │   ├── parse-brd.tool.ts
│   │   ├── convert-brd-to-miro-format.tool.ts
│   │   ├── create-miro-board.tool.ts
│   │   ├── export-miro-data.tool.ts
│   │   ├── generate-figma-design.tool.ts
│   │   ├── select-tech-stack.tool.ts
│   │   └── generate-application.tool.ts
│   ├── services/             # Core business logic
│   │   ├── brd-service.ts
│   │   ├── miro-converter.ts
│   │   ├── miro-service.ts
│   │   ├── figma-service.ts
│   │   ├── codegen-service.ts
│   │   └── code-templates/   # Code generation templates
│   ├── types/                # TypeScript type definitions
│   └── utils/                # Utility functions
├── SETUP_MIRO.md             # Miro API setup guide
├── SETUP_FIGMA.md            # Figma API setup guide
├── package.json
├── tsconfig.json
└── README.md
\`\`\`

## 🔧 Configuration

### Environment Variables

See \`.env.example\` for all available configuration options:

- **Miro**: MIRO_ACCESS_TOKEN, MIRO_TEAM_ID
- **Figma**: FIGMA_ACCESS_TOKEN, FIGMA_TEAM_ID
- **AI**: OPENAI_API_KEY, AI_PROVIDER, AI_MODEL
- **Features**: ENABLE_MIRO_AI, ENABLE_TESTING_GENERATION, etc.

### Tech Stack Support

#### Frontend
- React, Vue, Angular, Svelte, Next.js, Nuxt.js
- TypeScript, JavaScript
- Tailwind, MUI, Chakra UI, Styled Components

#### Backend
- Express, Fastify, NestJS (Node.js)
- Django, Flask, FastAPI (Python)
- Go Gin, Spring Boot

#### Database
- PostgreSQL, MySQL, MongoDB, SQLite
- Firebase, Supabase

## 🧪 Development

### Run in Development Mode

\`\`\`bash
npm run dev
\`\`\`

### Run Tests

\`\`\`bash
npm test
npm run test:coverage
\`\`\`

### Lint and Format

\`\`\`bash
npm run lint
npm run format
\`\`\`

## 📝 Generated Application Structure

When you generate an application, you'll get:

\`\`\`
generated-apps/
└── your-project/
    ├── frontend/              # React/Vue/etc application
    │   ├── src/
    │   │   ├── components/   # UI components
    │   │   ├── pages/        # Page components
    │   │   └── App.tsx
    │   └── package.json
    ├── backend/               # Express/Django/etc API
    │   ├── src/
    │   │   ├── routes/       # API routes
    │   │   ├── controllers/  # Business logic
    │   │   ├── models/       # Database models
    │   │   └── index.ts
    │   └── package.json
    ├── docker-compose.yml     # Docker orchestration
    ├── README.md              # Project documentation
    └── .gitignore
\`\`\`

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## 📄 License

MIT License - see [LICENSE](./LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Model Context Protocol SDK](https://github.com/anthropics/mcp)
- Uses [Miro API](https://developers.miro.com/)
- Integrates with [Figma API](https://www.figma.com/developers/api)
- Powered by OpenAI GPT-4 or Anthropic Claude

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/your-repo/issues)
- **Documentation**: See \`SETUP_*.md\` files
- **Examples**: Check \`examples/\` directory

## 🗺️ Roadmap

- [ ] Support for more frontend frameworks
- [ ] GraphQL API generation
- [ ] Mobile app generation (React Native, Flutter)
- [ ] Enhanced Figma Plugin for direct file creation
- [ ] CI/CD pipeline templates
- [ ] Real-time collaboration features

---


**Made with ❤️ for developers who want to move fast**