---
slug: "modes"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ccc0168/modes-mcp-server@main/README.md"
repo: "https://github.com/ccc0168/modes-mcp-server"
source_file: "README.md"
branch: "main"
---
# Modes MCP Server

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

## Features

- 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

## Installation

```bash
# 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
```

## Configuration

### 1. Environment Variables
Copy `.env.example` to `.env` and adjust as needed:
```bash
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`)

### 2. Custom Modes Configuration
Create a JSON file for your custom modes configuration. See `examples/modes.example.json` for the format:

```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"
        }],
        "command",
        "mcp"
      ],
      "customInstructions": "Example custom instructions for the mode."
    }
  ]
}
```

### 3. MCP Settings
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:

```json
{
  "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:

### Core System 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

### Specialized Modes
- **Trade Ops Manager**
  - Systematic trading and risk management
  - Trade documentation and analysis
  - Market analysis and strategy optimization

## Mode Transition Flow

```mermaid
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
```

## Available Tools

### list_modes
Lists all custom modes currently configured.

### get_mode
Get details of a specific mode by its slug.

Parameters:
- `slug`: The unique identifier of the mode

### create_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_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_mode
Delete a custom mode.

Parameters:
- `slug`: The unique identifier of the mode to delete

### validate_mode
Validate a mode configuration without saving it.

Parameters:
- `mode`: Complete mode configuration object to validate

## Mode Configuration Schema

```typescript
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
}
```

## Development

1. Make changes to the source code in `src/`
2. Build the project:
```bash
npm run build
```
3. Start the server:
```bash
npm start
```

## Best Practices

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

## Error Handling

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

## Testing

See [TESTING.md](https://github.com/ccc0168/modes-mcp-server/blob/HEAD/TESTING.md) for comprehensive test cases and validation procedures.

## Contributing

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

## License

MIT License - see [LICENSE](https://github.com/ccc0168/modes-mcp-server/tree/HEAD/LICENSE) for details