Modes MCP Server

An MCP server for managing Roo's custom operational modes, providing programmatic control over mode configuration and management.

Features

• Full CRUD operations for custom modes
• Schema validation with Zod
• File system watching for config changes
• Error handling with standard MCP error codes
• Atomic file operations

Operational Modes Framework

The server manages a comprehensive set of operational modes:

Core System Modes

1. Planning Mode 🎯

   • Strategic Planning Specialist
   • System design and resource allocation
   • Project roadmap development

2. Analytics Mode 📊

   • Data Analysis Expert
   • Metrics tracking and analysis
   • Performance monitoring

3. Research Mode 🔍

   • System Research Specialist
   • Best practices research
   • Solution exploration

4. Implementation Mode ⚙️

   • Operations Implementation Expert
   • System deployment
   • Process execution

5. Troubleshooting Mode 🔧

   • System Resolution Specialist
   • Problem identification
   • Issue resolution

6. Quality Control Mode ✅

   • Quality Assurance Expert
   • System validation
   • Performance verification

7. Integration Mode 🔄

   • Systems Integration Specialist
   • Cross-system coordination
   • Workflow optimization

8. Documentation Mode 📝

   • Knowledge Management Specialist
   • Process documentation
   • Standard maintenance

9. Session Management Mode ⚡

   • Session Management Specialist
   • Daily workflow orchestration
   • State management

Specialized Modes

• Trade Ops Manager
  • Systematic trading and risk management
  • Trade documentation and analysis
  • Market analysis and strategy optimization

Mode Transition Flow

graph TD
    A[Planning] --> B[Research]
    B --> C[Implementation]
    C --> D[Integration]
    D --> E[Quality Control]
    E --> F[Analytics]
    F --> G[Troubleshooting]
    G --> H[Documentation]
    H --> A

Available Tools

list_modes

Lists all custom modes currently configured.

get_mode

Get details of a specific mode by its slug.

Parameters:

• slug: The unique identifier of the mode

create_mode

Create a new custom mode.

Parameters:

• slug: Unique identifier (lowercase letters, numbers, and hyphens)
• name: Display name for the mode
• roleDefinition: Detailed description of the mode's role and capabilities
• groups: Array of allowed tool groups
• customInstructions: (optional) Additional instructions for the mode

update_mode

Update an existing custom mode.

Parameters:

• slug: The unique identifier of the mode to update
• updates: Object containing the fields to update (name, roleDefinition, groups, customInstructions)

delete_mode

Delete a custom mode.

Parameters:

• slug: The unique identifier of the mode to delete

validate_mode

Validate a mode configuration without saving it.

Parameters:

• mode: Complete mode configuration object to validate

Development

1. Make changes to the source code in src/
2. Build the project:

npm run build

3. Start the server:

npm start

Best Practices

1. Mode Selection

   • Choose appropriate mode for task
   • Follow mode-specific workflows
   • Use designated tool groups

2. Mode Transitions

   • Follow natural transition flow
   • Complete current mode tasks
   • Preserve context between modes

3. Configuration Management

   • Validate changes before saving
   • Maintain clear role definitions
   • Document mode capabilities

Error Handling

The server uses standard MCP error codes:

• InvalidParams: Invalid input parameters or mode not found
• MethodNotFound: Unknown tool requested
• InternalError: File system errors or other internal issues

Testing

See TESTING.md for comprehensive test cases and validation procedures.

Installation

# Clone the repository
git clone https://github.com/mkc909/modes-mcp-server.git
cd modes-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

1. Environment Variables

Copy .env.example to .env and adjust as needed:

cp .env.example .env

Available environment variables:

• MODES_CONFIG_PATH: Path to custom modes configuration file (default: %APPDATA%/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_custom_modes.json)

2. Custom Modes Configuration

Create a JSON file for your custom modes configuration. See examples/modes.example.json for the format:

{
  "customModes": [
    {
      "slug": "example-mode",
      "name": "Example Mode",
      "roleDefinition": "Example role definition describing the mode's capabilities and responsibilities.",
      "groups": [
        "read",
        ["edit", {
          "fileRegex": "\\.md$",
          "description": "Can edit markdown files only"
        }],
        "command",
        "mcp"
      ],
      "customInstructions": "Example custom instructions for the mode."
    }
  ]
}

3. MCP Settings

Add the server configuration to your MCP settings file (typically at %APPDATA%/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json). See examples/mcp-settings.example.json for the format:

{
  "mcpServers": {
    "modes": {
      "command": "node",
      "args": ["/path/to/modes-mcp-server/build/index.js"],
      "env": {
        "MODES_CONFIG_PATH": "/path/to/custom/modes.json"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Mode Configuration Schema

interface CustomMode {
  slug: string;  // Lowercase letters, numbers, and hyphens only
  name: string;  // Display name
  roleDefinition: string;  // Detailed description
  groups: (string | [string, { fileRegex: string, description: string }])[];
  customInstructions?: string;  // Optional additional instructions
}

License

MIT License - see LICENSE for details