Reddit MCP Server

# BrainLoop MCP Server v2 - Project Statistics Report **Generated**: November 14, 2025 **Branch**: fix-track-handlers-build-errors **Snapshot Date**: 2025-11-14 **Version**: 3.4.2 --- ## 📊 Project Overview **Project Name**: brainloop-mcp-server **Description**: BRAINLOOP MCP server with OAuth 2.1 authentication for personalized learning data access. Built on proven MCP implementation with TypeScript and production-ready architecture. **Purpose**: Model Context Protocol (MCP) server that enables AI assistants to interact with BrainLoop learning platform through authenticated API access. --- ## 📅 Project Timeline - **Start Date**: September 30, 2025 - **Latest Commit**: October 24, 2025 - **Duration**: **~24 days** (3.5 weeks) - **Active Development Days**: 10 days (42% of total days) --- ## 💻 Lines of Code (LOC) ### Overall Statistics ``` Total Files: 128 Total LOC: 20,963 Blank Lines: 2,138 Comment Lines: 3,969 ``` ### By Language | Language | Files | LOC | % of Total | |----------|-------|-----|------------| | TypeScript | 92 | 9,230 | 44.0% | | JSON | 8 | 8,055 | 38.4% | | Markdown | 19 | 2,875 | 13.7% | | Shell Scripts | 5 | 704 | 3.4% | | JavaScript | 2 | 68 | 0.3% | | YAML | 1 | 22 | 0.1% | | Dockerfile | 1 | 9 | 0.04% | ### Code Distribution - **Core Code**: 9,230 LOC (TypeScript) - **Documentation**: 2,875 LOC (Markdown) - **Configuration**: 8,055 LOC (JSON) - **Scripts**: 704 LOC (Shell) - **Other**: 99 LOC --- ## 🔄 Git Statistics ### Commits - **Total Commits**: 71 - **Last 30 Days**: 2 commits - **Last 7 Days**: 0 commits - **Commits/Day (avg)**: 7.1 commits/day (over project lifetime) ### Branches - **Total Branches**: 4 - **Current Branch**: fix-track-handlers-build-errors ### Contributors - **Total Contributors**: 1 - **Developer**: Oscar Valdez (71 commits) ### Recent Commits (Last 10) 1. `856216a` - fix: Add missing track methods and interfaces to BrainloopService 2. `64997b4` - Added tracks to mcp 3. `0efbcf6` - fix: add missing timestamp fields and handle optional updatedAt 4. `ed0a711` - feat: add get_lesson tool to retrieve full lesson content 5. `5dcec0c` - feat: add comprehensive diagnostic logging for tool execution (v3.4.2) 6. `45117d6` - fix: auto-recreate lost sessions on container restart (v3.4.1) 7. `a442326` - feat: add unit reordering tool (v3.4.0) 8. `ea5eb4d` - fix: use condensed lesson template to prevent response timeout (v3.3.3) 9. `037600b` - fix: inject lesson template directly into expand_brainloop response (v3.3.2) 10. `5e6c773` - feat: add structured lesson template guideline as MCP resource (v3.3.1) --- ## 🏗️ Project Structure ### Source Directory (`src/`) ``` src/ ├── constants/ # Tool and constant definitions ├── handlers/ # MCP protocol handlers │ ├── tools/ # Tool implementations (15+ tools) │ └── callbacks/ # OAuth and notification callbacks ├── server/ # Server configuration ├── services/ # External API integration ├── types/ # TypeScript type definitions └── utils/ # Utility functions ``` ### Key Components - **TypeScript Files**: 86 files - **Tool Handlers**: 56+ handler/tool files - **Documentation Files**: 19 markdown files ### Documentation - `README.md` (29,312 chars) - Comprehensive server documentation - `CODE_STRUCTURE_GUIDE.md` - Architecture documentation - `MCP_API_AUDIT.md` - API compliance audit - `LESSON_UPDATE_STRATEGY.md` - Feature documentation - `TRACK_TOOLS_ADDED.md` - Track tools documentation - `DEPLOYMENT.md` - Deployment guide - `RAILWAY_DEPLOYMENT.md` - Railway-specific deployment - `SECURITY.md` - Security guidelines --- ## 🛠️ Technology Stack ### Core Technologies - **Runtime**: Node.js - **Language**: TypeScript - **MCP SDK**: @modelcontextprotocol/sdk - **Web Framework**: Express.js ### Key Dependencies - **@modelcontextprotocol/sdk** - MCP protocol implementation - **express** - Web server framework - **cors** - Cross-origin resource sharing - **dotenv** - Environment configuration - **jose** - JSON Web Token operations - **zod** - Schema validation - **ajv-formats** - JSON schema validation - **cookie-parser** - Cookie handling ### Development Tools - **TypeScript**: Static typing - **ESLint**: Code linting - **Prettier**: Code formatting - **Docker**: Containerization - **Railway**: Cloud deployment platform --- ## 🔧 MCP Server Features ### MCP Protocol Support - ✅ **OAuth 2.1 Authentication** - Complete flow with PKCE - ✅ **Tools** - 20+ BrainLoop interaction tools - ✅ **Prompts** - Dynamic content generation - ✅ **Resources** - Learning resources access - ✅ **Sampling** - AI-assisted content with approval - ✅ **Notifications** - Real-time progress updates - ✅ **Callbacks** - OAuth and event callbacks ### BrainLoop Tools Implemented #### Course Management Tools - `create_course` - Create new courses - `view_courses` - List accessible courses - `get_course` - Get course details - `update_course` - Update course information - `enroll_in_course` - Enroll in courses - `expand_brainloop` - Expand course outlines #### Lesson Tools - `create_lesson` - Create lessons - `update_lesson` - Update lesson content - `get_lesson` - Get full lesson content - `reorder_units` - Reorder lesson units #### Track (Learning Path) Tools - `create_track` - Create learning tracks - `view_tracks` - List available tracks - `get_track` - Get track details with courses - `add_course_to_track` - Add courses to tracks - `enroll_in_track` - Enroll in tracks #### Review Tools - `get_pending_reviews` - Get scheduled reviews - `submit_review` - Submit review responses #### User Tools - `get_user_info` - Get user profile - `get_user_stats` - Get learning statistics --- ## 📈 Development Velocity ### Project Phases **Phase 1: Initial Setup** (Sept 30) - MCP server foundation - OAuth 2.1 implementation - Basic tool structure **Phase 2: Core Tools** (Oct 1-3) - Course management tools - Lesson tools - User tools **Phase 3: Advanced Features** (Oct 3-13) - Track/learning path tools - Review system integration - Lesson templates - Unit reordering **Phase 4: Stabilization** (Oct 13-24) - Bug fixes - Session management improvements - Build error fixes - Performance optimizations ### Version History - **v3.4.2** - Comprehensive diagnostic logging - **v3.4.1** - Auto-recreate lost sessions - **v3.4.0** - Unit reordering tool - **v3.3.3** - Condensed lesson templates - **v3.3.2** - Lesson template injection - **v3.3.1** - Structured lesson templates --- ## 🌐 Deployment ### Deployment Platform - **Primary**: Railway - **Containerization**: Docker - **Configuration Files**: - `Dockerfile` - `docker-compose.yml` - `.env.railway` - `RAILWAY_DEPLOYMENT.md` ### Environment Configuration - `.env` - Local development - `.env.railway` - Railway production - `.env.test` - Testing environment - `.env.example` - Template with documentation --- ## 📊 Summary Metrics | Metric | Value | |--------|-------| | **Total LOC** | 20,963 | | **TypeScript LOC** | 9,230 | | **Total Commits** | 71 | | **Branches** | 4 | | **Development Days** | 10 / 24 | | **Active Days %** | 42% | | **TypeScript Files** | 86 | | **Tool/Handler Files** | 56+ | | **Documentation Files** | 19 | | **MCP Tools Implemented** | 20+ | | **Contributors** | 1 | | **Current Version** | 3.4.2 | | **Commits/Day (avg)** | 7.1 | --- ## 🔑 Key Achievements 1. **Complete MCP Implementation** - Full OAuth 2.1 flow with PKCE - All major MCP protocol features - Production-ready architecture 2. **Comprehensive Tool Set** - 20+ tools for BrainLoop interaction - Course, lesson, and track management - Review system integration - User profile and statistics 3. **Production Deployment** - Railway deployment configured - Docker containerization - Environment management - Session persistence 4. **Developer Experience** - Comprehensive documentation (19 files) - Code structure guide - API audit documentation - Clear deployment guides 5. **Rapid Development** - 71 commits in 24 days - Multiple version releases - Active bug fixing and improvements --- ## 🎯 Architecture Highlights - **Modular Design**: Clear separation of concerns - **Type Safety**: Full TypeScript implementation - **Validation**: Zod schema validation - **Authentication**: OAuth 2.1 with JWT - **Error Handling**: Comprehensive error management - **Logging**: Diagnostic logging for debugging - **Testing**: E2E test suite included --- ## 📝 Notes - **Focused Project**: Single-purpose MCP server for BrainLoop - **Rapid Development**: Achieved production readiness in ~3 weeks - **Well Documented**: Extensive documentation for all features - **Active Maintenance**: Regular updates and fixes - **Production Ready**: Deployed to Railway with Docker --- **Report Generated**: November 14, 2025 **Next Review**: Recommended at major version updates