The Modes MCP Server provides programmatic control over Roo's custom operational modes, enabling complete management of mode configurations including:
List custom modes: Retrieve all currently configured custom modes
Get mode details: Retrieve details of a specific mode using its slug
Create a new mode: Define a new custom mode with a unique slug, name, role definition, allowed tool groups, and optional custom instructions
Update a mode: Modify existing mode configurations
Delete a mode: Remove a custom mode by its slug
Validate mode configuration: Check the validity of a mode configuration without saving it
Schema validation: Ensure mode configurations adhere to the defined schema using Zod
File system watching: Monitor and respond to changes in the custom modes configuration file
Atomic file operations: Perform safe file operations to avoid data corruption
Standard error handling: Use consistent MCP error codes for various error types
Used for environment variable configuration through .env files
Used for version control and cloning the repository
Used as the source repository for the MCP server code
Mentioned as a file format that can be edited with specific permissions in the example configuration
Used for visualizing the mode transition flow in the documentation
Used for package management and running build scripts
Used for defining the mode configuration schema
Used for schema validation of mode configurations
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Modes MCP Server list all custom modes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for managing Roo's custom operational modes, providing programmatic control over mode configuration and management.
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
Related MCP server: AX Local Operations MCP Server
# 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 buildCopy .env.example to .env and adjust as needed:
cp .env.example .envAvailable environment variables:
MODES_CONFIG_PATH: Path to custom modes configuration file (default: %APPDATA%/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_custom_modes.json)
Create a JSON file for your custom modes configuration. See examples/modes.example.json for the format:
{
"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."
}
]
}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:
{
"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": []
}
}
}The server manages a comprehensive set of operational modes:
Planning Mode 🎯
Strategic Planning Specialist
System design and resource allocation
Project roadmap development
Analytics Mode 📊
Data Analysis Expert
Metrics tracking and analysis
Performance monitoring
Research Mode 🔍
System Research Specialist
Best practices research
Solution exploration
Implementation Mode ⚙️
Operations Implementation Expert
System deployment
Process execution
Troubleshooting Mode 🔧
System Resolution Specialist
Problem identification
Issue resolution
Quality Control Mode ✅
Quality Assurance Expert
System validation
Performance verification
Integration Mode 🔄
Systems Integration Specialist
Cross-system coordination
Workflow optimization
Documentation Mode 📝
Knowledge Management Specialist
Process documentation
Standard maintenance
Session Management Mode ⚡
Session Management Specialist
Daily workflow orchestration
State management
Trade Ops Manager
Systematic trading and risk management
Trade documentation and analysis
Market analysis and strategy optimization
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 --> ALists all custom modes currently configured.
Get details of a specific mode by its slug.
Parameters:
slug: The unique identifier of the 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 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 a custom mode.
Parameters:
slug: The unique identifier of the mode to delete
Validate a mode configuration without saving it.
Parameters:
mode: Complete mode configuration object to validate
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
}Make changes to the source code in src/
Build the project:
npm run buildStart the server:
npm startMode Selection
Choose appropriate mode for task
Follow mode-specific workflows
Use designated tool groups
Mode Transitions
Follow natural transition flow
Complete current mode tasks
Preserve context between modes
Configuration Management
Validate changes before saving
Maintain clear role definitions
Document mode capabilities
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
See TESTING.md for comprehensive test cases and validation procedures.
Fork repository
Create feature branch
Submit pull request
Follow coding standards
MIT License - see LICENSE for details
Create a new custom mode
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Unique slug for the mode (lowercase letters, numbers, and hyphens) | |
| name | Yes | Display name for the mode | |
| roleDefinition | Yes | Detailed description of the mode's role and capabilities | |
| groups | Yes | Array of allowed tool groups | |
| customInstructions | No | Optional additional instructions for the mode |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Create' implies a write/mutation operation, the description doesn't mention permission requirements, whether the creation is idempotent, what happens on duplicate slugs, or what the response contains. For a creation tool with zero annotation coverage, this represents significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 4 words, with zero wasted language. It's front-loaded with the essential action and resource, making it immediately scannable and understandable. Every word earns its place in conveying the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with no annotations and no output schema, the description is insufficiently complete. It doesn't address what constitutes a successful creation, what gets returned, error conditions, or how this tool relates to the sibling tools in the mode management system. The combination of mutation functionality with minimal description creates significant contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no parameter information beyond what's already in the schema. However, with 100% schema description coverage, all 5 parameters are well-documented in the input schema itself. The baseline score of 3 reflects that the schema adequately covers parameter semantics, though the description adds no additional value in this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('a new custom mode'), making the purpose immediately understandable. It distinguishes this from sibling tools like delete_mode, get_mode, and update_mode by specifying creation rather than modification or retrieval. However, it doesn't explicitly differentiate from validate_mode, which might have overlapping creation-related functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like validate_mode that might be used before creation, and update_mode for modifications, there's no indication of prerequisites, sequencing, or appropriate contexts for choosing create_mode over other options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a custom mode
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Slug of the mode to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action is 'delete,' implying a destructive mutation, but doesn't specify if deletion is permanent, requires specific permissions, has side effects (e.g., cascading deletions), or what happens on success/failure. This is a significant gap for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste: 'Delete a custom mode.' It is front-loaded with the core action and resource, making it highly concise and well-structured for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a destructive operation with no annotations and no output schema, the description is incomplete. It lacks critical context such as behavioral traits (e.g., permanence, permissions), usage prerequisites, and expected outcomes, which are essential for safe and effective tool invocation by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the single parameter 'slug' documented as 'Slug of the mode to delete.' The description adds no additional parameter semantics beyond this, such as format examples or validation rules. Given high schema coverage, the baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a custom mode' clearly states the action (delete) and target resource (custom mode), which distinguishes it from sibling tools like create_mode, get_mode, list_modes, update_mode, and validate_mode. However, it doesn't specify what a 'mode' is or the scope of deletion, keeping it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing mode), exclusions (e.g., not for default modes), or refer to sibling tools like get_mode to check existence first, leaving the agent with minimal context for proper selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific mode
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Slug of the mode to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is a read operation ('Get'), implying it is non-destructive, but does not cover aspects like error handling (e.g., what happens if the slug is invalid), authentication needs, rate limits, or response format. For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys the core action without unnecessary words. It is front-loaded with the main purpose, though it could be slightly more informative (e.g., by specifying what 'details' include) to improve utility without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a read operation with one parameter) and the absence of annotations and an output schema, the description is incomplete. It does not explain what 'details' are returned, error conditions, or how it differs from siblings like 'list_modes'. For a tool with no structured output information, more context is needed to guide the agent effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'slug' parameter documented as 'Slug of the mode to retrieve'. The description does not add any meaning beyond this, such as explaining slug format or examples. Given the high schema coverage, a baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details of a specific mode' clearly states the verb ('Get') and resource ('mode'), making the purpose understandable. However, it does not differentiate this tool from its sibling 'list_modes' (which likely lists multiple modes) or specify what 'details' include, leaving it somewhat vague compared to more specific alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing a mode slug), exclusions, or comparisons to siblings like 'list_modes' for bulk retrieval or 'validate_mode' for checking mode validity, leaving the agent without contextual usage cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all custom modes
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('List all custom modes') but doesn't describe return format (e.g., list structure, pagination), error conditions, or any constraints (e.g., permissions needed, rate limits). This leaves significant gaps for an agent to understand how the tool behaves beyond its basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description 'List all custom modes' is a single, efficient sentence that front-loads the core action and resource. It wastes no words and is appropriately sized for a simple tool with no parameters, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema), the description is minimal but incomplete. It lacks details on return values (since no output schema exists), behavioral traits, or usage context relative to siblings. For a tool in a set with multiple modes-related operations, more guidance would help an agent use it correctly in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate here. A baseline of 4 is applied since the schema fully covers the absence of parameters, and the description doesn't introduce unnecessary or conflicting information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all custom modes' clearly states the verb ('List') and resource ('custom modes'), making the purpose immediately understandable. It distinguishes from siblings like create_mode or delete_mode by specifying a read-only listing operation, though it doesn't explicitly differentiate from get_mode (which might retrieve a single mode).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_mode (for a single mode) or validate_mode. The description implies usage for retrieving all custom modes, but lacks explicit context, prerequisites, or exclusions that would help an agent choose between sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing custom mode
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Slug of the mode to update | |
| updates | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is an update operation, implying mutation, but doesn't disclose critical behavioral traits like required permissions, whether changes are reversible, error handling, or what happens to unspecified fields. For a mutation tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single, front-loaded sentence that directly states the tool's purpose. There is no wasted verbiage or unnecessary elaboration, making it efficient for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with nested objects, no output schema, and no annotations), the description is inadequate. It doesn't address behavioral aspects, parameter details beyond the schema, or expected outcomes, leaving the agent with insufficient context to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-specific information beyond what's in the schema. With 50% schema description coverage (only 'slug' has a description), the description doesn't compensate by explaining the 'updates' object structure, the meaning of fields like 'roleDefinition' or 'groups', or how nested arrays work. The baseline is 3 since schema coverage is moderate, but the description adds no value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('update') and resource ('an existing custom mode'), making the purpose immediately understandable. It distinguishes this as an update operation rather than creation or deletion, though it doesn't explicitly differentiate from sibling tools like 'validate_mode' which might also involve mode modifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing mode), when not to use it, or how it differs from siblings like 'create_mode' or 'validate_mode' in practical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a mode configuration without saving it
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the key behavioral trait: validation without saving, which is useful. However, it lacks details on what validation entails (e.g., checks for required fields, format errors, or conflicts), error handling, or any rate limits or permissions needed, leaving significant gaps for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the purpose ('Validate a mode configuration') and adds critical context ('without saving it'). There is no wasted text, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested object parameter, no annotations, no output schema), the description is incomplete. It doesn't explain what validation checks are performed, what the output might look like (e.g., success/failure, error messages), or how it interacts with sibling tools, leaving the agent with insufficient context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter with 0% description coverage, and the description doesn't add any parameter-specific details beyond the general 'mode configuration'. It doesn't explain what 'mode' object contains or the semantics of its properties (e.g., slug, roleDefinition). Baseline is 3 due to schema coverage being low, but the description doesn't compensate adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('validate') and resource ('mode configuration'), specifying it's a validation operation without persistence. However, it doesn't explicitly differentiate from siblings like 'create_mode' or 'update_mode' beyond the 'without saving it' clause, which is somewhat implied but not directly contrasted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: validate before saving, suggesting it's a pre-check for operations like create or update. However, it doesn't explicitly state when to use this versus alternatives (e.g., use before 'create_mode' to avoid errors) or provide exclusions, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
create_modedelete_modeget_modelist_modesupdate_modevalidate_modeEvery tool has a clearly distinct purpose with no ambiguity. Each tool targets a specific action on the 'mode' resource: create, delete, get, list, update, and validate are all unique operations that cannot be confused with one another.
All tools follow a perfectly consistent verb_noun pattern with 'mode' as the noun. The naming convention is uniform throughout the set, using snake_case consistently without any deviations or mixed styles.
Six tools is well-scoped and appropriate for a server managing custom modes. Each tool earns its place by covering essential CRUD operations and validation, with no unnecessary redundancy or missing functionality.
The tool set provides complete CRUD/lifecycle coverage for the mode domain, including create, read (get and list), update, and delete operations. The addition of validate_mode offers a useful extra without creating gaps, ensuring agents can handle all expected workflows without dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
MCP server for Product Management
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
MCP server for managing FormDesigner forms, fields, logic rules, themes, and entries
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ccc0168/modes-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
