modes-mcp-server

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

• 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

# 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

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)

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."
    }
  ]
}

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": []
    }
  }
}

The server manages a comprehensive set of operational 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

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

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

Lists all custom modes currently configured.

Get details of a specific mode by its slug.

Parameters:

• slug: The unique identifier of the 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 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 a custom mode.

Parameters:

• slug: The unique identifier of the mode to delete

Validate a mode configuration without saving it.

Parameters:

• mode: Complete mode configuration object to validate

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
}

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

npm run build

3. Start the server:

npm start

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

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

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

1. Fork repository
2. Create feature branch
3. Submit pull request
4. Follow coding standards

MIT License - see LICENSE for details