Modes

You run a dedicated MCP server to manage Roo's custom operational modes, enabling you to configure, validate, and operate complex mode workflows with programmatic control and robust validation.

How to use

You interact with the Modes MCP Server through your MCP client to list, create, view, update, validate, and delete custom modes. Use the available endpoints to manage mode definitions, enforce schema validation, and react to configuration changes as you tune workflows. You can start with listing existing modes, then progressively create new ones, validate configurations before saving, and apply updates atomically.

How to install

# Prerequisites
- Node.js (LTS) and npm installed on your system
- Git installed

# Clone the Modes MCP Server 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

# Start the server
npm start

Configuration and usage notes

Configure how the server loads its custom modes and how it is invoked by your MCP environment. You can set environment variables to point to your custom modes file, and you configure the MCP integration to load and run the server as an MCP endpoint.

Key configuration details you will use include:

• MODES_CONFIG_PATH: Path to your custom modes configuration file.
• The server is started as a local stdio MCP endpoint using Node, with the index script executed by the Node runtime.

Configuration reference

Below are the configuration examples you will typically use to wire up the Modes MCP Server. They show how the server is started and how it locates its configuration.

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

Operational modes framework

The server manages a comprehensive set of operational modes to cover planning, analytics, research, implementation, troubleshooting, quality control, integration, and documentation. You can configure each mode’s slug, display name, role definition, allowed tool groups, and optional custom instructions.

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

Example mode definitions and tools

You manage modes using a structured schema that includes a slug, name, roleDefinition, groups, and optional customInstructions. The available MCP tools let you list, get, create, update, delete, and validate modes.

Error handling and testing

The server adheres to standard MCP error handling for invalid parameters, unknown tools, and internal issues. When validating a mode configuration, you ensure the mode object conforms to the required schema before saving.

Development

Make changes to the source code in the src directory. Build and start to test locally:
- npm run build
- npm start

Available tools

list_modes

List all custom modes currently configured.

get_mode

Get details of a specific mode by its slug.

create_mode

Create a new custom mode with slug, name, roleDefinition, groups, and optional customInstructions.

update_mode

Update an existing custom mode by slug with new field values.

delete_mode

Delete a custom mode by slug.

validate_mode

Validate a mode configuration without saving it.