Mode Manager MCP

Instructions

Implementation Reference

• src/mode_manager_mcp/tools/instruction_tools.py:35-50 (handler)

  MCP tool handler function for 'create_instruction'. Checks read-only mode and delegates core logic to InstructionManager.create_instruction, returning success/error messages.

  def create_instruction(
      instruction_name: Annotated[str, "The name for the new instruction (with or without extension)"],
      description: Annotated[str, "A brief description of what this instruction does"],
      content: Annotated[str, "The main content/instructions in markdown format"],
  ) -> str:
      """Create a new VS Code .instructions.md file with the specified description and content."""
      if read_only:
          return "Error: Server is running in read-only mode"
      try:
          success = instruction_manager.create_instruction(instruction_name, description, content)
          if success:
              return f"Successfully created VS Code instruction: {instruction_name}"
          else:
              return f"Failed to create VS Code instruction: {instruction_name}"
      except Exception as e:
          return f"Error creating VS Code instruction '{instruction_name}': {str(e)}"

• src/mode_manager_mcp/instruction_manager.py:401-436 (helper)

  Core helper method in InstructionManager that implements the file creation logic: ensures extension, checks existence, builds frontmatter with applyTo '**' and description, writes file using write_frontmatter_file.

  def create_instruction(self, instruction_name: str, description: str, content: str) -> bool:
      """
      Create a new instruction file.
  
      Args:
          instruction_name: Name for the new .instructions.md file
          description: Description of the instruction
          content: Instruction content
  
      Returns:
          True if successful
  
      Raises:
          FileOperationError: If file cannot be created
      """
  
      # Ensure filename has correct extension
      instruction_name = self._ensure_instruction_extension(instruction_name)
  
      file_path = self.prompts_dir / instruction_name
  
      if file_path.exists():
          raise FileOperationError(f"Instruction file already exists: {instruction_name}")
  
      # Create frontmatter with applyTo field so instructions are actually applied
      frontmatter: Dict[str, Any] = {"applyTo": "**", "description": description}
  
      try:
          success = write_frontmatter_file(file_path, frontmatter, content, create_backup=False)
          if success:
              logger.info(f"Created instruction file: {instruction_name}")
          return success
  
      except Exception as e:
          raise FileOperationError(f"Error creating instruction file {instruction_name}: {e}")

• src/mode_manager_mcp/tools/__init__.py:20-20 (registration)

  Triggers registration of all instruction tools, including 'create_instruction', via register_instruction_tools() call in register_all_tools().

  register_instruction_tools()

• src/mode_manager_mcp/tools/instruction_tools.py:20-30 (schema)

  Tool schema definition in @app.tool annotations, specifying parameters (instruction_name, description, content), return type, and hints like non-idempotent and non-readonly.

  annotations={
      "idempotentHint": False,
      "readOnlyHint": False,
      "title": "Create Instruction",
      "parameters": {
          "instruction_name": "The name for the new instruction. If .instructions.md extension is not provided, it will be added automatically.",
          "description": "A brief description of what this instruction does. This will be stored in the frontmatter.",
          "content": "The main content/instructions in markdown format.",
      },
      "returns": "Returns a success message if the instruction was created, or an error message if the operation failed.",
  },