MCP Learning Platform

An interactive educational platform for learning the Model Context Protocol (MCP) with staged progression, quizzes, and comprehensive concept coverage.

🎯 Features

5 Progressive Learning Stages: From foundations to mastery
20 Interactive Modules: Comprehensive MCP concept coverage
40 Quiz Questions: Test your understanding
Progress Tracking: Analytics and session metrics
Knowledge Map: Visual concept relationships
Accessibility: WCAG AA compliant
Session-Based: All progress stored in browser session

🏗️ Architecture

Tech Stack

Framework: Next.js 15.0.0 with static export
Language: TypeScript 5.7.3 (strict mode)
Styling: Tailwind CSS 3.4.17
UI Components: shadcn/ui (Radix UI primitives)
Icons: Lucide React
Storage: Browser sessionStorage
Testing: Jest, React Testing Library, Playwright

Project Structure

agentdevplatform/
├── src/
│   ├── app/                    # Next.js 15 App Router pages
│   │   ├── page.tsx           # Home/dashboard
│   │   ├── stage/[id]/        # Stage detail pages
│   │   ├── module/[id]/       # Module content pages
│   │   ├── quiz/[stageId]/    # Quiz pages
│   │   ├── progress/          # Progress dashboard
│   │   ├── knowledge-map/     # Concept visualization
│   │   ├── about/             # Platform information
│   │   ├── not-found.tsx      # 404 page
│   │   └── layout.tsx         # Root layout with error boundary
│   ├── components/            # React components
│   │   ├── ui/               # shadcn/ui components
│   │   ├── QuizQuestion.tsx
│   │   ├── ProgressBar.tsx
│   │   ├── StageCard.tsx
│   │   ├── ModuleCard.tsx
│   │   ├── KnowledgeMap.tsx
│   │   ├── FeedbackDialog.tsx
│   │   ├── NavigationHeader.tsx
│   │   └── ErrorBoundary.tsx
│   ├── services/              # Business logic layer
│   │   ├── LearnerService.ts  # Learner profile management
│   │   ├── QuizService.ts     # Quiz logic and scoring
│   │   ├── ContentService.ts  # Content retrieval
│   │   ├── AnalyticsService.ts# Progress analytics
│   │   ├── FeedbackService.ts # User feedback
│   │   └── StorageService.ts  # SessionStorage abstraction
│   ├── content/               # MCP educational content
│   │   ├── stages.ts         # 5 learning stages
│   │   ├── modules.ts        # 20 modules (4 per stage)
│   │   └── quizzes.ts        # 40 questions (8 per stage)
│   ├── lib/                   # Utilities
│   │   ├── utils.ts          # General utilities
│   │   └── accessibility.ts  # WCAG compliance helpers
│   └── types/                 # TypeScript type definitions
│       └── index.ts          # Core types from data-model.md
├── public/                    # Static assets
├── ACCESSIBILITY.md           # WCAG AA compliance checklist
└── README.md                  # This file

🚀 Getting Started

Prerequisites

Node.js 18+
npm 9+

Installation

# Clone the repository
git clone <repository-url>
cd agentdevplatform

# Install dependencies
npm install

# Run development server
npm run dev

Open http://localhost:3000 in your browser.

Available Scripts

Development:

npm run dev - Start development server (port 3000)
npm run lint - Run ESLint
npm test - Run Jest unit tests
npm run test:e2e - Run Playwright E2E tests

Production:

npm run build - Build for production (SSR mode)
npm run build:static - Build static export for GitHub Pages
npm start - Serve production build

Local Testing:

# Test static export locally before deployment
npm run build:static
npx serve out -p 8080
# Visit: http://localhost:8080/mcp-learning-platform/

📚 Learning Journey

Stage 1: MCP Foundations

Core protocol concepts
JSON-RPC basics
Client-server architecture
4 modules, 8 quiz questions

Stage 2: Architecture & Messages

Message structure
Resource management
Tool implementation
4 modules, 8 quiz questions

Stage 3: Advanced Patterns

Sampling strategies
Error handling
Progressive disclosure
4 modules, 8 quiz questions

Stage 4: Building & Debugging

Server implementation
Testing strategies
Debugging techniques
4 modules, 8 quiz questions

Stage 5: Mastery

Performance optimization
Security best practices
Production deployment
4 modules, 8 quiz questions

🎓 User Flow

Start Session: Platform initializes learner profile
Browse Stages: View available learning stages
Complete Modules: Read content, track progress
Take Quizzes: Test understanding (70% passing score)
Track Progress: View analytics and achievements
Explore Concepts: Visualize knowledge map

🔧 Services Architecture

LearnerService

Initialize and manage learner profiles
Track module completions
Manage stage progression
Calculate session duration

QuizService

Retrieve quizzes by stage
Grade quiz attempts (70% threshold)
Identify weak concepts
Track quiz statistics

ContentService

Provide stage and module content
Search functionality
Concept management
Progress calculations

AnalyticsService

Session analytics
Quiz performance metrics
Engagement tracking
Progress milestones

StorageService

SessionStorage abstraction
JSON serialization/deserialization
Error handling
Storage size monitoring

♿ Accessibility

This platform is built to meet WCAG AA standards:

✅ Keyboard navigation throughout
✅ Screen reader support with ARIA labels
✅ Focus indicators on all interactive elements
✅ Color contrast ratios meet 4.5:1 minimum
✅ Semantic HTML structure
✅ Error boundary for graceful error handling
✅ Skip links for main content
✅ Responsive design (mobile-first)

See ACCESSIBILITY.md for complete checklist.

🧪 Testing

Unit Tests

Tests for all services and utilities (Jest):

npm test

Component Tests

React component tests with Testing Library:

npm test -- --testPathPattern=components

E2E Tests

Full user journey tests with Playwright:

npm run test:e2e

📦 Build & Deployment

Static Export

This app is configured for static export:

npm run build:static

Output in out/ directory. Can be deployed to:

GitHub Pages (automatic via GitHub Actions)
Vercel
Netlify
Any static hosting service

Deployment

Live URL: https://[username].github.io/mcp-learning-platform/

Automatic Deployment:

Triggers on merge to main branch
GitHub Actions workflow builds and deploys
Build time: ~4-5 minutes (cached), ~7-8 minutes (cold)

Manual Deployment:

Navigate to repository "Actions" tab
Select "Deploy to GitHub Pages" workflow
Click "Run workflow" → "Run workflow"
Wait for deployment completion (~5 minutes)

Local Testing Before Deployment:

# Build static export
npm run build:static

# Serve locally
npx serve out -p 8080

# Test in browser
# Visit: http://localhost:8080/mcp-learning-platform/
# Test routes: /progress, /knowledge-map, /stage/foundations

Deployment Validation:

See quickstart.md for comprehensive validation scenarios
Verify client-side routing works (direct navigation to /progress)
Check all assets load correctly (images, JS bundles)
Test responsive design on mobile devices

Environment

No environment variables required - all content is bundled.

🎨 Styling

Tailwind CSS for utility-first styling
shadcn/ui components with Radix UI primitives
CSS Custom Properties for theming
Dark mode support built-in

📊 Data Model

All types defined in src/types/index.ts:

Learner - User profile and session data
Stage - Learning stage definition
Module - Content module
Quiz - Quiz with questions
Question - Quiz question with options
QuizAttempt - Quiz attempt record
ProgressRecord - Overall progress tracking
FeedbackEntry - User feedback

🔐 Privacy

No backend: All data stored in browser session
No analytics tracking: Privacy-first design
Session-only: Data cleared on browser close
No cookies: Uses sessionStorage only

🤝 Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

Code Style

TypeScript strict mode
ESLint configuration enforced
Prettier for formatting
Conventional commit messages

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

Model Context Protocol specification and documentation
shadcn/ui for beautiful component primitives
Vercel for Next.js framework
Radix UI for accessible component foundations

📞 Support

For issues and questions:

Open an issue on GitHub
Check ACCESSIBILITY.md for accessibility concerns
Review data-model.md for data structure

Built with ❤️ for the MCP community

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github		.github
.specify		.specify
scripts		scripts
specs		specs
src		src
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
ACCESSIBILITY.md		ACCESSIBILITY.md
README.md		README.md
components.json		components.json
jest.config.cjs		jest.config.cjs
jest.setup.cjs		jest.setup.cjs
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
postcss.config.mjs		postcss.config.mjs
tailwind.config.cjs		tailwind.config.cjs
tsconfig.json		tsconfig.json

tebinraouf/mcp-learning-platform

Folders and files

Latest commit

History

Repository files navigation