Agent MCP

# The Complete MCD (Main Context Document) Guide > **"The MCD is your application blueprint - think of it as writing a detailed book about your app before building it."** ## What is an MCD? A **Main Context Document (MCD)** is the cornerstone of effective AI collaboration. Based on the theoretical foundation established in our [Context chapter](./chapter-2-context-foundation.md), the MCD serves as a comprehensive operational blueprint that bridges the gap between human intent and AI execution. ### Why MCDs Matter - ✅ **Eliminates ambiguity** that causes AI hallucinations - ✅ **Provides single source of truth** for all agents - ✅ **Enables deterministic outcomes** instead of guesswork - ✅ **Prevents context loss** across multiple sessions - ✅ **Facilitates agent coordination** in multi-agent systems ## The MCD Philosophy ### Applications as Books > *"If LLMs are made for languages and translating between them, and text can be code, and code can be text, then an application is a book."* The MCD embodies this philosophy by treating your application as a comprehensive narrative that can be: - **Read** by AI agents to understand requirements - **Translated** into executable code - **Referenced** for consistent decision-making - **Updated** as requirements evolve ### Cognitive Empathy in Practice MCDs are the practical application of **Cognitive Empathy** - understanding that AI needs explicit, structured information where humans rely on intuition and implied knowledge. ## MCD Structure: The 8 Essential Sections ### 🎯 **1. Overview & Goals** **Purpose**: Define the *why* and *what* ```markdown ## 🎯 Overview & Goals **Project Vision**: [Specific, concrete description of what you're building] **Target Users**: [Who will use this - be specific about user types] **Core Features**: [Main functionality - prioritized list with clear boundaries] **Success Criteria**: [Measurable outcomes that define completion] **Business Context**: [Why this matters, what problem it solves] ``` **Real Example**: ```markdown ## 🎯 Overview & Goals **Project Vision**: Build a real-time collaborative task management SaaS platform that enables remote teams to track project progress with integrated video communication and file sharing. **Target Users**: - Remote software development teams (5-50 people) - Project managers who need real-time visibility - Developers who want integrated workflow tools **Core Features**: 1. Real-time task boards with drag-drop functionality 2. Integrated video calling directly from task cards 3. File attachment and version control per task 4. Time tracking with automated reporting 5. Team dashboard with progress analytics **Success Criteria**: - Teams can create and assign tasks in <30 seconds - Video calls launch in <5 seconds from task cards - Real-time updates appear across all clients within 2 seconds - 95% uptime for collaborative features ``` ### 🏗️ **2. Technical Architecture** **Purpose**: Define the *where* and *how* ```markdown ## 🏗️ Technical Architecture **Frontend**: [Framework, state management, key libraries] **Backend**: [Framework, database, hosting platform] **APIs**: [External services, authentication methods] **Infrastructure**: [CI/CD, hosting, scaling considerations] **Technology Justification**: [Why these choices were made] ``` **Real Example**: ```markdown ## 🏗️ Technical Architecture **Frontend**: - React 18 with TypeScript for type safety - Zustand for state management (lightweight, plays well with real-time) - Socket.io-client for real-time updates - TailwindCSS for rapid UI development - Vite for fast development builds **Backend**: - Node.js with Express for rapid development - PostgreSQL for structured data (tasks, users, projects) - Redis for session management and real-time caching - Socket.io for WebSocket management - JWT for stateless authentication **APIs**: - Zoom SDK for video calling integration - AWS S3 for file storage - Stripe for subscription billing - SendGrid for email notifications **Infrastructure**: - Docker containers for consistent deployment - AWS ECS for container orchestration - AWS RDS for PostgreSQL hosting - CloudFront CDN for global performance - GitHub Actions for CI/CD pipeline **Technology Justification**: - React/Node.js for team JavaScript expertise - PostgreSQL for ACID compliance in task management - Redis for sub-second real-time performance requirements - AWS for enterprise-grade scalability and compliance ``` ### 📋 **3. Detailed Implementation Specs** **Purpose**: Granular feature definitions ```markdown ## 📋 Detailed Implementation **Database Schema**: [Tables, relationships, indexes, constraints] **API Endpoints**: [HTTP methods, routes, request/response schemas] **UI Components**: [Component hierarchy, props, state management] **Business Logic**: [Core algorithms, validation rules, workflows] **Integration Points**: [How external services connect] ``` **Real Example**: ```markdown ## 📋 Detailed Implementation ### Database Schema ```sql -- Core entities CREATE TABLE users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), email VARCHAR(255) UNIQUE NOT NULL, name VARCHAR(100) NOT NULL, avatar_url TEXT, created_at TIMESTAMP DEFAULT NOW() ); CREATE TABLE projects ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name VARCHAR(100) NOT NULL, description TEXT, owner_id UUID REFERENCES users(id), status VARCHAR(20) DEFAULT 'active', created_at TIMESTAMP DEFAULT NOW() ); CREATE TABLE tasks ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), title VARCHAR(200) NOT NULL, description TEXT, status VARCHAR(20) DEFAULT 'todo', -- todo, in_progress, done assignee_id UUID REFERENCES users(id), project_id UUID REFERENCES projects(id), position INTEGER NOT NULL, -- for drag-drop ordering due_date TIMESTAMP, created_at TIMESTAMP DEFAULT NOW() ); ``` ### API Endpoints ```typescript // Task Management POST /api/tasks // Create new task GET /api/tasks/:projectId // Get all tasks for project PUT /api/tasks/:id // Update task (title, status, assignee) DELETE /api/tasks/:id // Delete task PATCH /api/tasks/:id/position // Update task position (drag-drop) // Real-time Events WebSocket /ws/projects/:id // Real-time task updates Events: 'task:created', 'task:updated', 'task:deleted', 'task:moved' // File Management POST /api/tasks/:id/files // Upload file to task GET /api/tasks/:id/files // List task files DELETE /api/files/:id // Delete file ``` ### UI Components ```typescript // Component Hierarchy <ProjectDashboard> <TaskBoard> <TaskColumn status="todo" | "in_progress" | "done"> <TaskCard> <TaskTitle /> <TaskAssignee /> <TaskFiles /> <VideoCallButton /> </TaskCard> </TaskColumn> </TaskBoard> <TeamSidebar> <UserList /> <ProjectStats /> </TeamSidebar> </ProjectDashboard> // Key Props & State interface TaskCardProps { task: Task; onUpdate: (task: Partial<Task>) => void; onDelete: (taskId: string) => void; onStartCall: (taskId: string) => void; } ``` ``` ### 📁 **4. File Structure & Organization** **Purpose**: Guide physical implementation ```markdown ## 📁 File Structure & Organization **Project Layout**: [Directory structure with explanations] **Naming Conventions**: [File, variable, function naming patterns] **Code Organization**: [How to structure components, utilities, tests] **Environment Setup**: [Required dependencies, environment variables] ``` **Real Example**: ```markdown ## 📁 File Structure & Organization ### Project Layout ``` task-manager/ ├── frontend/ # React application │ ├── src/ │ │ ├── components/ # Reusable UI components │ │ │ ├── TaskCard/ │ │ │ │ ├── TaskCard.tsx │ │ │ │ ├── TaskCard.test.tsx │ │ │ │ └── TaskCard.module.css │ │ │ └── TaskBoard/ │ │ ├── pages/ # Page-level components │ │ ├── store/ # Zustand stores │ │ ├── hooks/ # Custom React hooks │ │ ├── utils/ # Helper functions │ │ └── types/ # TypeScript type definitions │ ├── public/ │ └── package.json ├── backend/ # Node.js API server │ ├── src/ │ │ ├── controllers/ # Route handlers │ │ ├── models/ # Database models │ │ ├── middleware/ # Express middleware │ │ ├── routes/ # API route definitions │ │ ├── services/ # Business logic │ │ ├── utils/ # Helper functions │ │ └── types/ # TypeScript interfaces │ ├── migrations/ # Database migrations │ └── package.json ├── shared/ # Shared types & utilities │ └── types/ # Common TypeScript interfaces └── docs/ # Documentation ├── api.md # API documentation └── deployment.md # Deployment guide ``` ### Naming Conventions - **Components**: PascalCase (`TaskCard`, `UserProfile`) - **Files**: Match component names (`TaskCard.tsx`) - **Variables**: camelCase (`taskList`, `currentUser`) - **Constants**: UPPER_SNAKE_CASE (`API_BASE_URL`) - **Database**: snake_case (`user_id`, `created_at`) ### Environment Variables ```bash # Frontend (.env) VITE_API_URL=http://localhost:3001 VITE_SOCKET_URL=http://localhost:3001 VITE_ZOOM_SDK_KEY=your_zoom_key # Backend (.env) DATABASE_URL=postgresql://user:pass@localhost:5432/taskmanager REDIS_URL=redis://localhost:6379 JWT_SECRET=your-super-secret-key AWS_ACCESS_KEY_ID=your-aws-key AWS_SECRET_ACCESS_KEY=your-aws-secret ``` ``` ### ✅ **5. Task Breakdown & Implementation Plan** **Purpose**: Define execution sequence ```markdown ## ✅ Task Breakdown & Implementation Plan **Phase 1**: [Foundation - core infrastructure] **Phase 2**: [Core Features - main functionality] **Phase 3**: [Advanced Features - enhancements] **Phase 4**: [Polish - optimization and deployment] ### Task Details **Each task should include**: - Clear deliverable description - Acceptance criteria - Dependencies on other tasks - Estimated complexity - Required files/components ``` **Real Example**: ```markdown ## ✅ Task Breakdown & Implementation Plan ### Phase 1: Foundation (Week 1) **1.1 Project Setup** - Initialize React + Node.js projects with TypeScript - Setup ESLint, Prettier, and testing frameworks - Configure development environment with hot reload - **Acceptance**: Dev servers run without errors, linting passes **1.2 Database Setup** - Create PostgreSQL schema with migrations - Setup Redis for caching - Implement basic database connection and health checks - **Acceptance**: Database migrations run successfully, connections stable **1.3 Authentication System** - Implement JWT-based auth with refresh tokens - Create user registration and login endpoints - Setup middleware for protected routes - **Acceptance**: Users can register, login, and access protected endpoints ### Phase 2: Core Features (Week 2-3) **2.1 Task Management Backend** - Implement CRUD operations for tasks - Create real-time WebSocket handlers - Setup task position management for drag-drop - **Acceptance**: All task operations work via API, real-time updates functioning **2.2 Task Board Frontend** - Build TaskCard and TaskBoard components - Implement drag-and-drop functionality - Connect to WebSocket for real-time updates - **Acceptance**: Users can create, edit, delete, and reorder tasks in real-time **2.3 User Management** - Implement team member invitation system - Create user assignment functionality - Build team management UI - **Acceptance**: Users can invite team members and assign tasks ### Phase 3: Advanced Features (Week 4) **3.1 Video Integration** - Integrate Zoom SDK for task-based video calls - Implement call invitation system - Create video call UI within task cards - **Acceptance**: Users can start video calls directly from tasks **3.2 File Management** - Implement file upload to AWS S3 - Create file attachment UI for tasks - Add file versioning and download functionality - **Acceptance**: Users can attach, version, and download files from tasks ### Phase 4: Polish (Week 5) **4.1 Performance Optimization** - Implement Redis caching for frequent queries - Add database indexing for performance - Optimize bundle size and implement code splitting - **Acceptance**: Page load times <2s, real-time updates <500ms **4.2 Deployment** - Setup Docker containers and AWS ECS deployment - Configure CI/CD pipeline with automated testing - Implement monitoring and error tracking - **Acceptance**: Application deployed successfully with 99.9% uptime ``` ### 🔗 **6. Integration & Dependencies** **Purpose**: Map connections and requirements ```markdown ## 🔗 Integration & Dependencies **Internal Dependencies**: [How components depend on each other] **External Services**: [Third-party APIs, services, and their integration points] **Data Flow**: [How information moves through the system] **Error Handling**: [How failures are managed across integrations] ``` ### 🧪 **7. Testing & Validation Strategy** **Purpose**: Ensure quality and reliability ```markdown ## 🧪 Testing & Validation Strategy **Unit Tests**: [Component and function-level testing] **Integration Tests**: [API and database testing] **End-to-End Tests**: [User workflow testing] **Performance Tests**: [Load and stress testing requirements] **Acceptance Criteria**: [How to validate each feature works correctly] ``` ### 🚀 **8. Deployment & Operations** **Purpose**: Production readiness ```markdown ## 🚀 Deployment & Operations **Environment Configuration**: [Production vs development settings] **Deployment Process**: [CI/CD pipeline and deployment steps] **Monitoring**: [What to monitor and how] **Scaling Considerations**: [How the system should handle growth] **Maintenance Tasks**: [Regular operational requirements] ``` ## MCD Quality Checklist ### ✅ Completeness Check - [ ] All 8 sections are present and detailed - [ ] Technical specifications are specific, not generic - [ ] Business requirements are clearly defined - [ ] Implementation tasks are actionable - [ ] Dependencies and integrations are mapped - [ ] Success criteria are measurable ### ✅ Clarity Check - [ ] Technical jargon is defined when first used - [ ] Code examples are syntactically correct - [ ] API schemas include all required fields - [ ] Database relationships are explicit - [ ] File organization is logical and explained ### ✅ Actionability Check - [ ] An agent could implement features from these specifications - [ ] Acceptance criteria are testable - [ ] Error conditions are anticipated and handled - [ ] Integration points have clear protocols - [ ] Performance requirements are quantified ## MCD Creation Workflow ### Step 1: Research Phase Use **Gemini 2.0 Flash** or **Claude** for deep research: ``` Help me create a comprehensive MCD for [your project type]. Research the latest best practices for [your tech stack] and break down implementation into granular, actionable tasks. Include: - Current industry standards for [specific domain] - Common architectural patterns for [specific use case] - Integration best practices for [specific services] - Performance benchmarks for [specific requirements] - Testing strategies for [specific features] ``` ### Step 2: Structure Creation Start with the 8-section template and fill each section methodically: 1. Begin with Overview & Goals to establish vision 2. Define Technical Architecture based on requirements 3. Detail Implementation Specs for each feature 4. Plan File Structure for organized development 5. Break down Tasks with clear dependencies 6. Map Integration points and data flows 7. Define Testing strategy for quality assurance 8. Plan Deployment and operational requirements ### Step 3: Validation & Refinement - **Peer Review**: Have team members review for completeness - **Technical Review**: Validate architectural decisions - **Feasibility Check**: Ensure timelines and scope are realistic - **Agent Test**: Try using the MCD with an AI agent to identify gaps ### Step 4: Living Document Maintenance - **Version Control**: Track MCD changes alongside code - **Regular Updates**: Reflect architectural decisions and scope changes - **Context Refresh**: Update based on implementation learnings - **Team Sync**: Ensure all team members understand current state ## Common MCD Mistakes to Avoid ### ❌ **Too Generic** ```markdown BAD: "Build a web application with user authentication" GOOD: "Build a React-based task management SaaS with JWT authentication, real-time WebSocket updates, and integrated video calling using Zoom SDK" ``` ### ❌ **Missing Implementation Details** ```markdown BAD: "Users can create tasks" GOOD: "Users can create tasks via POST /api/tasks with required fields: title (max 200 chars), description (optional), assignee_id, project_id, due_date (optional). Task creation triggers WebSocket event 'task:created' to all project members." ``` ### ❌ **Unclear Success Criteria** ```markdown BAD: "The application should be fast" GOOD: "Page load times <2 seconds, real-time updates appear within 500ms, video calls connect in <5 seconds" ``` ### ❌ **Missing Dependencies** ```markdown BAD: "Implement user profiles" GOOD: "Implement user profiles (depends on: authentication system, file upload for avatars, database user table). Integrates with: task assignment system, team management, notification preferences." ``` ## MCD Examples for Different Project Types ### 🛒 **E-commerce Platform** Focus on: Product catalog, shopping cart, payment processing, order management, inventory tracking ### 📱 **Mobile App Backend** Focus on: API design, push notifications, user management, data synchronization, offline capabilities ### 🔧 **Developer Tool** Focus on: CLI interface, plugin architecture, configuration management, integration ecosystem ### 📊 **Analytics Dashboard** Focus on: Data ingestion, real-time processing, visualization components, export capabilities ### 🎮 **Gaming Platform** Focus on: User progression, matchmaking, real-time multiplayer, leaderboards, in-app purchases ## Advanced MCD Techniques ### Modular MCDs For large projects, create separate MCDs for major subsystems and link them: - **Master MCD**: Overall architecture and integration - **Frontend MCD**: UI/UX specifications and component details - **Backend MCD**: API, database, and business logic - **Infrastructure MCD**: Deployment, monitoring, and operations ### Agent-Specific MCDs Create specialized MCDs for different types of agents: - **Frontend Agent MCD**: Component-focused with UI specifications - **Backend Agent MCD**: API and database-focused - **DevOps Agent MCD**: Infrastructure and deployment-focused - **Testing Agent MCD**: Quality assurance and validation-focused ### Iterative Refinement Evolve your MCD through implementation: 1. **Initial MCD**: High-level requirements and architecture 2. **Detailed MCD**: Specific implementation details as you learn 3. **Production MCD**: Actual implementation patterns and lessons learned 4. **Maintenance MCD**: Operational procedures and troubleshooting --- ## Conclusion The MCD is your most powerful tool for AI collaboration. It transforms vague ideas into precise instructions, eliminates ambiguity that causes hallucinations, and enables true partnership between human insight and artificial intelligence. **Remember**: A well-crafted MCD is the difference between frustrating back-and-forth with AI and seamless, productive collaboration that builds exactly what you envision. > **Next Steps**: > 1. Choose one of your current projects > 2. Create an MCD using this guide > 3. Test it with an AI agent > 4. Refine based on results > 5. Share your experience with the community **Master the MCD, and master AI collaboration.**