learn-code-mcp

littlebearapps/learn-code-mcp

3.1

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.

License: MIT Node.js Version MCP Version

✨ 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

PresetOutputTokensUse Case
micro1-3 bullets150Quick overview
short4-6 bullets250Standard explanation
paragraph120-180 words + example450Detailed with usage
deep250-350 words + checklist700Comprehensive 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

  1. Fork the repository
  2. Create a feature branch
  3. Make changes with tests
  4. Run npm run validate
  5. 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
  • 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