Modes

You manage Roo’s custom operational modes through a dedicated MCP server that handles creation, validation, and management of modes, giving you programmatic control and robust configuration handling for complex workflows.

How to use

You interact with the Modes MCP Server through an MCP client to perform full CRUD operations on custom modes. You can list all configured modes, fetch details for a specific mode by its slug, create new modes, update existing ones, delete modes you no longer need, and validate configurations before saving.

Key capabilities you will use include: creating a mode with a unique slug, assigning a name, providing a detailed role definition, grouping access controls, and optionally adding custom instructions. You can validate a mode configuration to catch errors before committing it to your active settings. When you need to adjust operations, you can update fields like the mode name, role definition, groups, or custom instructions, and you can remove modes as needed.

Operational modes flow through a practical lifecycle, from planning and research to implementation, integration, quality control, analytics, troubleshooting, and documentation. You can adopt a clear transition path and preserve context across transitions to maintain continuity in your workflows.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system. You will build and run the MCP server locally as described.

# 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

Configuration and setup beyond installation

Prepare your environment and configuration files to run the Modes MCP Server. You will define where the custom modes configuration is read from and how the server is started by your MCP client.

# Copy the example environment file and adjust it as needed
cp .env.example .env

Runtime configuration example

Below is an explicit runtime configuration example you place in your MCP settings to run the Modes MCP Server locally via Node.

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

Usage notes

The server reads the custom modes configuration from the path you provide via MODES_CONFIG_PATH and exposes CRUD endpoints through the MCP interface. Use the provided tools to manage modes and ensure you validate configurations before saving changes to avoid runtime errors.

Development

If you want to change core behavior, modify the source in the src/ directory, rebuild, and restart the server.

# Rebuild after changes
npm run build

# Start the server (during development you may use a direct start command as shown here)
npm start

Best practices

• Validate mode configurations before saving to ensure compatibility and correct permissions.
• Maintain clear, concise role definitions and documented capabilities for each mode.
• Document mode capabilities and expected behavior to aid future maintenance.

Error handling

The server uses standard MCP error codes to signal issues such as invalid input or missing modes. Typical codes include InvalidParams for invalid input, MethodNotFound for unknown tool requests, and InternalError for file system or internal issues.

Notes on testing and contribution

For comprehensive test coverage and validation procedures, refer to the project’s testing guidance. When contributing, follow established workflows for forking, branching, and submitting pull requests, and adhere to coding standards.

Available tools

list_modes

Lists all custom modes currently configured.

get_mode

Fetches details of a specific mode by its slug.

create_mode

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

update_mode

Updates an existing custom mode with provided changes.

delete_mode

Deletes a custom mode by its slug.

validate_mode

Validates a mode configuration without persisting it.