This MCP server provides a configurable framework for managing Roo's custom operational modes. It exposes a set of tools to list, inspect, create, update, validate, and delete modes, all backed by a schema that enforces consistency of mode definitions. Core capabilities include supporting full CRUD operations for custom modes, validating mode configurations against the defined schema, watching the configuration file system for changes, and handling errors using standard MCP error codes. Available tools include: list_modes to enumerate configured modes; get_mode to fetch details for a specific mode by slug; create_mode to add a new mode with fields like slug, name, roleDefinition, groups, and optional customInstructions; update_mode to modify existing modes; delete_mode to remove modes; and validate_mode to verify a mode configuration without persisting it. Use these tools to manage your modes.json configuration file and ensure changes are atomic and well-formed.

Prerequisites:

• Node.js (16.x or newer) and npm installed on your system
• Access to a shell/terminal
• Git for cloning repository (optional but recommended)

Installation steps:

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

2. Install dependencies npm install

3. Build the project (produces build/index.js or equivalent) npm run build

4. Create and configure environment file (optional but recommended)

   • Copy example env and tailor values: cp .env.example .env

     Edit .env to set necessary paths

5. Run the MCP server via the configured command (as defined in mcp_config) npm start

Note: If you are integrating with an MCP manager, set the mode server entry in your MCP settings to point to the built index.js and ensure MODES_CONFIG_PATH points to your modes.json configuration file.

Tips and caveats:

• Ensure MODES_CONFIG_PATH points to a valid JSON file containing a customModes array with properly structured mode objects.
• The configuration supports atomic file operations; ensure you have permissions to read/write the target config locations.
• When adding or updating modes, follow the schema: slug (lowercase letters, numbers, hyphens only), name, roleDefinition, groups (array of strings or [string, { fileRegex, description }]), and optional customInstructions.
• Use validate_mode before creating or updating to catch schema errors early.
• If the server fails to access the configuration file, double-check file permissions and path correctness in MODES_CONFIG_PATH.
• In MCP settings, ensure the command points to the built server entry (build/index.js) and that environment variables are correctly propagated to the process at runtime.