littlebearapps/learn-code-mcp
If you are the rightful owner of learn-code-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Model Context Protocol (MCP) server is designed to facilitate the learning of code concepts and patterns through a structured protocol.
Learn Code MCP v0.1.0 🚀
Production Released: Fast, deterministic code explanations for terminal automation workflows with perfect Claude Code integration.
✨ Production Features
🎯 v0.1.0 Released - Terminal/CLI Excellence
- ✅ Claude Code Integration:
/learn-code-mcp:explain_*
commands working perfectly - ✅ CLI Mastery:
teach explain
with file input, stdin pipelines, automation workflows - ✅ 4 Length Presets: micro (1-3 lines), short (4-6 bullets), paragraph (120-180 words), deep (250-350 words)
- ✅ Git Integration: Perfect for code review, CI/CD, and PR documentation
- ✅ Performance: <400ms total execution, memory optimized
- ✅ Cross-Platform: macOS, Linux, Windows compatibility verified
- ✅ Security: Built-in secret redaction with 11+ patterns
🔮 Future Scope
- 🗓️ v0.2: VS Code extension integration (deferred from v0.1)
- 🗓️ v0.3: Enhanced workspace context and plugin system
🚀 Quick Start
Installation
npm install -g @learn-code/mcp
CLI Usage
# File input
teach explain app.py --length short
# Stdin pipeline
cat main.js | teach explain -l micro
# Line range selection
teach explain utils.py --lines 45-67 --length deep
# Format options
git diff HEAD~1 | teach explain --format plain
Claude Code Integration ✅
Already integrated! No setup required:
# In Claude Code terminal - just use directly:
/learn-code-mcp:explain_short [select your code]
/learn-code-mcp:explain_micro [select your code]
/learn-code-mcp:explain_paragraph [select your code]
/learn-code-mcp:explain_deep [select your code]
Perfect for: Code review, understanding complex functions, documentation
📏 Length Presets
Preset | Output | Tokens | Use Case |
---|---|---|---|
micro | 1-3 bullets | 150 | Quick overview |
short | 4-6 bullets | 250 | Standard explanation |
paragraph | 120-180 words + example | 450 | Detailed with usage |
deep | 250-350 words + checklist | 700 | Comprehensive analysis |
💻 CLI Reference
Input Options
<file>
- Read from specific file--lines <start-end>
- Line range (e.g., 10-20)--language <lang>
- Override language detection
Output Options
--length <type>
- micro|short|paragraph|deep (default: short)-l <type>
- Short alias for --length--format <type>
- markdown|plain (default: markdown)--no-color
- Disable ANSI colors--no-redact
- Disable secret redaction
Debug Options
--debug
- Show MCP communication details--help
- Show usage information
🔒 Security Features
Automatically detects and redacts 11+ types of secrets:
- API keys (OpenAI, AWS, etc.)
- Database URLs and connection strings
- JWT tokens and bearer tokens
- Private keys and certificates
- Passwords and secrets
- GitHub tokens
- Email addresses in auth contexts
# Input with secrets gets automatically redacted
echo 'const key = "sk-1234567890abcdef";' | teach explain
# 🔒 Security Notice: 1 potential secret redacted for privacy
📁 Examples
Basic Usage
# Explain a Python function
teach explain calculate_distance.py --length short
# Quick overview of JavaScript
echo "const users = await User.find({ active: true });" | teach explain -l micro
# Deep analysis with context
teach explain complex-algorithm.cpp --length deep --language cpp
Pipeline Workflows
# Git integration
git show HEAD:src/auth.ts | teach explain --format plain
# Find and explain specific functions
grep -A 10 "function processData" app.js | teach explain -l paragraph
# Explain recent changes
git diff HEAD~1 | teach explain --length short
Line Range Selection
# Focus on specific lines
teach explain large-file.py --lines 100-120 --length deep
# Error handling section
teach explain server.js --lines 45-67 --language javascript
⚡ Performance
- Startup time: ~77ms average (CLI + MCP server)
- Processing: ~75ms for typical code snippets
- Memory usage: ~47MB (optimized with V8 flags)
- Cross-platform: Native performance on all platforms
# Run performance benchmark
npm run benchmark
🏗️ Architecture
MCP Server
- Prompts: 4 manual explanation prompts for any MCP client
- Tools: 3 tools for VS Code extension communication
- Transport: stdio JSON-RPC for universal compatibility
VS Code Extension
- Chat Participant: Native VS Code chat integration
- Selection Capture: Automatic code selection via hotkeys
- Context Collection: Workspace metadata and project detection
- MCP Communication: Direct server communication via tools
CLI Interface
- Pipeline Compatible: Standard Unix tool behavior
- Format Options: Markdown (colored) or plain text
- Input Flexibility: Files, stdin, line ranges
- Cross-Platform: Handles paths, Unicode, line endings
🔧 Development
Local Setup
git clone https://github.com/little-bear-apps/learn-code-mcp.git
cd learn-code-mcp
npm install
npm run build
Testing
# Run all tests
npm run test:all
# CLI tests only (12/12 passing)
npm run test:cli
# Cross-platform compatibility (5/5 passing)
npm run test:cross-platform
# Validate before publish
npm run validate
Manual Testing
# Start MCP server in dev mode
npm run dev:server
# Test CLI in dev mode
npm run dev:cli -- test-file.js --length micro --debug
# Test comprehensive functionality
./test-cli-comprehensive.sh
🛠️ Troubleshooting
Common Issues
CLI not found after install:
# Check global bin path
npm list -g --depth=0
# Or use npx
npx @learn-code/mcp explain file.js
VS Code extension not working:
# Verify MCP server path
node ./node_modules/@learn-code/mcp/dist/server.js
Permission errors:
# Fix CLI permissions
chmod +x ./node_modules/.bin/teach
Debug Mode
Use --debug
flag to see MCP communication:
teach explain file.js --debug --length micro
🤝 Contributing
- Fork the repository
- Create a feature branch
- Make changes with tests
- Run
npm run validate
- Submit a pull request
📜 License
MIT © Little Bear Apps
🎯 Real-World Automation Examples
Git Integration & Code Review
# Explain recent changes
git diff HEAD~1 | teach explain --length short
# Analyze specific commits
git show abc123 | teach explain --format plain
# PR documentation generation
git diff --name-only HEAD~1 | xargs -I {} teach explain {} -l micro
CI/CD Pipeline Integration
# Automated code analysis in CI
find . -name "*.ts" -newer /tmp/last-build | xargs -I {} teach explain {} -l short
# Pre-commit hooks
git diff --cached | teach explain --length micro --format plain
Development Workflows
# Understand complex functions
grep -A 20 "function processPayment" app.js | teach explain -l deep
# Quick file overview
teach explain server.py --lines 1-50 --length paragraph
# Pipeline debugging
echo 'const result = data.filter(x => x.status === "active").map(x => x.id)' | teach explain -l short
🗺️ Roadmap
- v0.1.0: ✅ Production Released - Terminal/CLI automation excellence
- Claude Code integration (
/learn-code-mcp
commands) - CLI mastery (
teach explain
with all options) - Git workflow automation and CI/CD pipeline support
- Cross-platform compatibility and performance optimization
- Claude Code integration (
- v0.2.0: VS Code extension integration (deferred from v0.1)
- Native VS Code chat participant
- Workspace context collection
- Selection hotkeys and context menus
- v0.3.0: Enhanced workspace intelligence
- Project type detection and framework-specific insights
- Custom explanation templates and plugin system
- v1.0.0: Stable API and marketplace publishing
🚀 Built with Model Context Protocol | v0.1.0 Production Released