MCP Overview

🔌 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

1. Master core framework
2. Add one service at a time
3. Learn service-specific commands
4. 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

🔗 Additional Resources

• MCP Specification
• Service Documentation
• Community Services

---

← API Reference | Home | GitHub Integration →