MCP Overview - johnpeterman72/CursorRIPER.sigma GitHub Wiki
π MCP (Model Context Protocol) Integration Overview
CursorRIPERβ¦Ξ£ supports optional integration with MCP services, extending the framework's capabilities with external tools while maintaining its core efficiency.
π― What is MCP?
Model Context Protocol (MCP) is a standard for connecting AI assistants to external services. It enables:
- π§ Tool integration without custom code
- π Secure service connections
- π Extended capabilities
- π Consistent interfaces
π Available MCP Services
Core Services
Service | Symbol | Purpose | Commands |
---|---|---|---|
GitHub | Ξ | Repository management | !gr , !gp , !gpr |
Web Search | Ξ | Research capabilities | !ws , !wl , !wf |
Browser | Ξ₯ | Automation & testing | !pn , !ps , !pt |
Docker | Ξ | Container management | !dc , !dd , !dl |
Additional Services
- Filesystem (Built-in) - Advanced file operations
- SQLite - Database operations
- Fetch - URL content retrieval
- Memory - Knowledge graph
ποΈ Architecture
βββββββββββββββββββββββββββββββββββββββ
β CursorRIPERβ¦Ξ£ Framework β
βββββββββββββββββββββββββββββββββββββββ€
β Core Framework (Always Active) β
β βββ RIPER Modes (Ξ©) β
β βββ Memory System (Ξ£) β
β βββ Protection (Ξ¨) β
β βββ Permissions (β) β
βββββββββββββββββββββββββββββββββββββββ€
β MCP Layer (Optional) β
β βββ GitHub Service (Ξ) β
β βββ Web Search (Ξ) β
β βββ Browser Automation (Ξ₯) β
β βββ Docker Service (Ξ) β
βββββββββββββββββββββββββββββββββββββββ
π Quick Setup
1. Install MCP Services
# GitHub Integration
npm install -g @modelcontextprotocol/server-github
export GITHUB_TOKEN=your_token
# Web Search
npm install -g @modelcontextprotocol/server-brave-search
export BRAVE_SEARCH_API_KEY=your_key
# Browser Automation
npm install -g @executeautomation/playwright-mcp-server
# Docker
npm install -g docker-mcp
2. Configure Cursor
Update .cursor/mcp.json
:
{
"mcpServers": {
"github": {
"command": "mcp-server-github",
"env": {
"GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
}
},
"brave-search": {
"command": "mcp-server-brave-search",
"env": {
"BRAVE_SEARCH_API_KEY": "${env:BRAVE_SEARCH_API_KEY}"
}
}
}
}
3. Enable in Framework
Uncomment service sections in your framework rules.
π Mode-Specific Restrictions
Service Availability by Mode
Service | Research | Innovate | Plan | Execute | Review |
---|---|---|---|---|---|
GitHub Read | β | β | β | β | β |
GitHub Write | β | β | β | β | β |
Web Search | β | β | β | β | β |
Browser Read | β | β | β | β | β |
Browser Write | β | β | β | β | β |
Docker Read | β | β | β | β | β |
Docker Write | β | β | β | β | β |
Why These Restrictions?
- No search in EXECUTE: Maintains implementation focus
- Write operations limited: Prevents accidental modifications
- Read always allowed: Information gathering is safe
π‘ Integration Benefits
1. Enhanced Research
/research
!ws "latest authentication best practices"
!gr "oauth2 implementation examples"
2. Automated Testing
/execute
!pn https://localhost:3000
!ps login-page
!pt # Start test recording
3. Repository Management
/execute
!gp # Push completed feature
!gpr # Create pull request
4. Container Development
/execute
!dc nodejs:18 # Create dev container
!dl my-app # Check logs
π― Best Practices
1. Optional by Design
- Framework works perfectly without MCP
- Enable only services you need
- Start with core framework first
2. Mode Awareness
- Services respect mode permissions
- Some operations blocked by mode
- Plan service usage appropriately
3. Security First
- Store API keys securely
- Use environment variables
- Never commit credentials
4. Gradual Adoption
- Master core framework
- Add one service at a time
- Learn service-specific commands
- Integrate into workflow
π Service Symbols & Commands
Symbol Mapping
β = {
Ξ: { // GitHub
1: {op: "search_repositories", h: "!gr"},
2: {op: "create_repository", h: "!gc"},
3: {op: "push_files", h: "!gp"},
4: {op: "create_pull_request", h: "!gpr"}
},
Ξ: { // Web Search
1: {op: "web_search", h: "!ws"},
2: {op: "local_search", h: "!wl"},
3: {op: "fetch_url", h: "!wf"}
},
Ξ₯: { // Browser
1: {op: "navigate", h: "!pn"},
2: {op: "screenshot", h: "!ps"},
3: {op: "test_record", h: "!pt"}
},
Ξ: { // Docker
1: {op: "create_container", h: "!dc"},
2: {op: "deploy_compose", h: "!dd"},
3: {op: "get_logs", h: "!dl"}
}
}
π¨ Common Integration Issues
Service Not Available
Error: MCP service 'github' not found
Solution: Install service and restart Cursor
Permission Denied
β οΈ GitHub write operations not allowed in RESEARCH mode
Solution: Switch to EXECUTE mode
API Key Missing
Error: GITHUB_TOKEN not set
Solution: Export environment variable
Mode Conflict
β οΈ Web search blocked in EXECUTE mode
Solution: Complete task, then switch modes
π§ Troubleshooting
Check Service Status
"Show available MCP services"
"Test GitHub connection"
"Verify web search API"
Debug Commands
!mcp-status # Check all services
!mcp-test github # Test specific service
!mcp-reload # Reload services
π Usage Patterns
Research Enhancement
/research
!ws "microservices patterns" # Web search
!gr "microservice examples" # GitHub search
!wf "https://patterns.dev" # Fetch specific page
Development Workflow
/execute
!gc my-new-project # Create repo
# ... develop feature ...
!gp # Push changes
!gpr # Create PR
Testing Automation
/execute
!pn http://localhost:3000 # Navigate
!ps before-change # Screenshot
# ... make changes ...
!ps after-change # Screenshot
!pt # Record test
π Learning Path
Week 1: Core Only
- Master RIPER modes
- Learn memory system
- Understand protections
Week 2: First Service
- Enable GitHub or Web Search
- Learn basic commands
- Integrate into workflow
Week 3: Multiple Services
- Add browser automation
- Combine services
- Create workflows
Week 4: Advanced
- Custom integrations
- Service combinations
- Team workflows
π Next Steps
Ready to integrate specific services?
- GitHub Integration - Repository management
- Web Search - Research capabilities
- Browser Automation - Testing tools
- Docker Integration - Container management