Modes MCP Server

🚀 Modes MCP Server

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

🚀 Quick Start

This MCP server is designed to manage Roo's custom operation modes. It offers programming control for mode configuration and management.

✨ Features

• Complete CRUD operations for custom modes.
• Mode validation using Zod.
• Monitoring of file system changes.
• Handling of standard MCP error codes.
• Atomic file operations.

📦 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

📚 Documentation

Configuration Steps

1. Environment Variable Configuration

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

cp .env.example .env

Available environment variables:

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

2. Custom Mode Configuration

Create a JSON configuration file for custom modes. Refer to the format in examples/modes.example.json:

{
  "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"
        }],
        "write"
      ],
      "customInstructions": "These are additional instructions for using this mode."
    }
  ]
}

3. MCP Tool Configuration

Add the following content to config/mcp-tools.json:

{
  "modeManager": {
    "class": "FileModeManager",
    "args": {
      "configPath": "%MODES_CONFIG_PATH%",
      "schema": {
        "type": "object",
        "required": ["slug", "name", "roleDefinition"],
        "properties": {
          "slug": {"type": "string"},
          "name": {"type": "string"},
          "roleDefinition": {"type": "string"},
          "groups": {
            "type": "array",
            "items": [
              {"type": "string"},
              {
                "type": "array",
                "minLength": 2,
                "items": [
                  {"type": "string"},
                  {
                    "type": "object",
                    "required": ["fileRegex", "description"],
                    "properties": {
                      "fileRegex": {"type": "string"},
                      "description": {"type": "string"}
                    }
                  }
                ]
              }
            ]
          },
          "customInstructions": {"type": "string", "nullable": true}
        }
      }
    }
  }
}

Operating Mode Framework

Standard Modes

• Default Mode: default-mode
  • Display Name: Default Mode
  • Role Definition: Provides general file operation functions, suitable for various tasks.
  • Toolset: Basic file operations (read, edit, write)

Custom Modes

Developers can create custom modes to meet specific needs. For example:

{
  "slug": "my-custom-mode",
  "name": "My Custom Mode",
  "roleDefinition": "A custom mode for specialized tasks.",
  "groups": [
    ["custom-task", {
      "fileRegex": "\\.custom$",
      "description": "Handles files with .custom extension"
    }]
  ],
  "customInstructions": "Use this mode only for specific operations."
}

Available Tools

Create a Mode

POST /modes
Content-Type: application/json

{
  "mode": {
    "slug": "new-mode",
    "name": "New Mode",
    "roleDefinition": "Description of new mode.",
    "groups": ["read", "write"]
  }
}

Get All Modes

GET /modes

Update a Mode

PUT /modes/<slug>
Content-Type: application/json

{
  "mode": {
    "name": "Updated Mode",
    "roleDefinition": "Updated description.",
    "groups": ["read", "write"]
  }
}

Delete a Mode

DELETE /modes/<slug>

Development Guide

1. Modify the source code located in the src/ directory.
2. Build the project:

npm run build

3. Start the server:

npm start

Best Practices

Mode Selection

• Choose the appropriate mode based on the task.
• Follow the workflow of a specific mode.
• Use the specified toolset.

Mode Switching

• Operate according to the natural switching process.
• Complete the tasks of the current mode.
• Preserve the context between modes.

Configuration Management

• Validate changes before saving.
• Keep clear role definitions.
• Document mode capabilities.

Error Handling

The server uses standard MCP error codes:

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

Testing Guide

Refer to TESTING.md for comprehensive test cases and verification steps.

Contribution Guide

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

📄 License

This project is under the MIT License. See LICENSE for details.